机器人接口简介
借助稳定且规范的 HTTP 接口,轻松打通消息推送、自动回复以及业务系统。从发送第一条消息到实现全流程的企业自动化,全程仅需简单几步。
轻量易用的 RESTful API
支持通过 HTTPS 发送请求并以 JSON 格式获取响应,方便各类主流编程语言轻松接入。
安全的服务端鉴权
各机器人均配有专属验证令牌,支持随时更换或吊销,从而有效防范凭证外泄。
Webhook 与轮询机制对比
前期借助长轮询在开发中高效测试,上线后则通过 Webhook 实现事件的实时触发。
快速上手
快速开始
完整的调用流程由三步构成:新建机器人、申请 Token、调用相应接口发送 HTTPS 请求。接下来以发送文本消息为例,展示最简便的接入步骤。
-
1
创建一个 Bot
前往三条客户端的机器人管理后台,新建一个机器人并完善其昵称、头像以及权限范围。
-
2
保存访问令牌
请复制刚生成的 Token,并务必将其存放在服务端的环境变量里,切勿硬编码进前端页面或上传到公开的代码仓库中。
stb_demo_x8mQ••••••••••••4n2K -
3
发送第一条消息
请把令牌(Token)填入 权限验证 请求头中,同时采用 JSON 格式来收发会话及消息数据。
身份验证
关于身份校验及访问源IP
全部请求皆需通过 Bot Token 完成身份核验,推荐采用标准的 Bearer 请求头格式:
请妥善保管好你的访问令牌。 严禁把该凭证推送到 Git、写入客户端日志或放进浏览器前端代码里;一旦发生泄露,必须马上进行轮换。
通用请求格式
curl -X POST \
https://api.santiao.im/bot/v1/发送消息 \
-H "权限验证: Bearer <BOT_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"chat_id": "chat_8c12f",
"text": "Hello from Santiao Bot!"
}'
const response = await fetch(
"https://api.santiao.im/bot/v1/发送消息", { method: "POST", 请求头: { 授权认证: `Bearer ${process.env.SANTIAO_BOT_TOKEN}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
chat_id: "chat_8c12f",
text: "Hello from Santiao Bot!",
}),
}
);
const data = await response.json();
import os
import requests
response = requests.post(
"https://api.santiao.im/bot/v1/发送消息",
headers={
"权限验证": f"Bearer {os.environ['SANTIAO_BOT_TOKEN']}"
},
json={
"chat_id": "chat_8c12f",
"text": "Hello from Santiao Bot!",
},
)
print(response.json())
RESPONSE
标准响应格式
所有接口均采用 JSON 格式响应。基于 ok 检查接口调用状态;有效数据存放在
result,错误详情位于 error。
{
"ok": true,
"result": {
"message_id": "msg_91af2",
"chat_id": "chat_8c12f",
"status": "sent"
}
}
{
"ok": false,
"error": {
"code": 40002,
"message": "Invalid chat_id",
"request_id": "req_a71d"
}
}
ERRORS
通用错误码
| HTTP | 错误码 | 含义 | 建议处理 |
|---|---|---|---|
| 400 | 40002 | 请求参数无效 | 对照消息内容核对关键字段及数据格式 |
| 401 | 40101 | 令牌失效或过期,请重新获取 | 请刷新访问令牌,并核对 Bearer 认证请求头。 |
| 403 | 40303 | 机器人暂无相关执行权限 | 核实机器人所在的聊天场景及其权限配置 |
| 404 | 40401 | 资源或方法不存在 | 核实资源标识、访问路径及接口版本 |
| 429 | 42901 | 请求频率超过限制 | 通过获取 Retry-After 头部信息,采用指数退避策略进行重试 |
| 500 | 50000 | 服务端暂时异常 | 保留 request_id,稍后重试或提交诊断 |
METHODS
可用方法
各类方法已按具体的业务场景归类,点击即可查看其具体用途和核心参数,方便用户快速查找。
GET
getMe
查询此机器人(Bot)的概况信息
该接口用来校验Token的有效性,成功后会输出机器人的编号、昵称、头像以及所具备的功能权限。
权限验证必填Bearer Bot Token
GET
获取更新
通过长轮询机制来拉取最新的事件
该方案更契合本地调试及轻量级访问场景;若部署至生产环境,推荐改用 Webhook 以防范频繁轮询带来的资源浪费。
offset可选首个需要返回的 update_idtimeout可选长轮询的等待时间,推荐设定在20至50秒之间
POST
发送消息
给特定的对话框推送文字内容
兼容普通文本及基础 Markdown 格式,若操作成功则会输出新建的 Message 实体对象。
chat_id必填目标会话唯一标识text必填正文内容最好控制在4000个字符以内parse_mode可选支持纯文本(plain)与 markdown 两种消息格式
POST
发送图片
可直接传图,或是选用之前上传过的文件。
可使用 multipart/form-data 上传文件,或通过 file_id 复用已有资源。
chat_id必填目标会话唯一标识photo必填图片文件、公开 URL 或 file_idcaption可选图片说明文字WEBHOOK
实时接收事件
每当有新消息、人员变动或按钮触发时,Webhook 便会向你的 HTTPS 端点推送事件通知。服务方在完成签名验证后,应当迅速给出响应。 2xx,建议将耗时操作放入队列中进行异步执行。
上线前检查
后续行动计划