机器人接口简介
借助简洁可靠的 HTTP 接口,轻松打通消息推送、智能回复与业务流。只需简单几步,即可从发送首条消息跃升至实现全套企业级自动化。
轻量易用的 RESTful API
支持通过 HTTPS 发送请求并以 JSON 格式获取响应,方便各类主流编程语言轻松对接。
安全的服务端鉴权
各个机器人均采用专属的验证令牌,支持按需更换或注销,从而有效防范密钥外泄隐患。
Webhook 与轮询机制
测试时可借助长轮询来加速验证,上线后则改用 Webhook 实现事件的实时同步。
快速上手
快速开始
整个调用流程主要分为三步:新建机器人、获取令牌以及向指定接口发送HTTPS请求。接下来,我们以发送文字消息为例,带你快速走通最简接入流程。
-
1
创建一个 Bot
进入三条客户端的机器人管理界面,新建机器人并配置其名称、头像及使用权限。
-
2
保存访问令牌
请复制刚生成的 Token,并务必将其存放在服务端的环境变量里,切勿硬编码进网页前端或公开的代码仓库中。
stb_demo_x8mQ••••••••••••4n2K -
3
发送第一条消息
通过 身份授权 请求头携带 Token,同时借助 JSON 格式来收发会话及消息数据。
身份验证
鉴权机制及接口路径
全部请求皆需借助 Bot Token 进行身份核验,推荐采用标准的 Bearer 请求头部格式:
请妥善保管好你的Token。 严禁把该凭证推送到Git库、写入前端日志或是写死在浏览器JS代码里;一旦发生泄露,必须马上更新密钥。
通用请求格式
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/发送消息", { 请求方法: "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 | 请求参数无效 | 参照 message 字段核对必需的参数及相应的数据格式 |
| 401 | 40101 | 凭证失效或不在有效期内 | 刷新访问令牌,并核对 Bearer 认证头信息 |
| 403 | 40303 | 机器人暂无执行权限 | 核实机器人当前所处的对话窗口及其权限边界 |
| 404 | 40401 | 资源或方法不存在 | 请核对一下资源ID、具体路径以及API的版本号。 |
| 429 | 42901 | 请求频率超过限制 | 获取 Retry-After 头部信息后,采用指数退避算法再次尝试 |
| 500 | 50000 | 服务端暂时异常 | 保留 request_id,稍后重试或提交诊断 |
METHODS
可用方法
各类方法已按业务场景分类归纳。轻点任一方法即可查看其作用与核心参数,助您高效查找。
GET
getMe
查看当前机器人的基础档案
该接口用来校验 Token 的有效性,成功后会输出机器人的编号、昵称、头像以及具备的功能权限。
身份授权必填Bearer 机器人令牌
GET
getUpdates
通过长轮询机制来拉取最新的事件通知
该方案契合本地调试及轻量化服务场景;若部署于线上生产环境,推荐改用 Webhook 以防范频繁拉取带来的性能损耗。
offset可选首个需要返回的 update_idtimeout可选长轮询的超时等待时间,推荐设置为 20 到 50 秒
POST
发送消息
给特定的聊天窗口推送文字信息
兼容普通文本及基础 Markdown 格式,若操作成功将输出新建的 Message 实例。
chat_id必填目标会话唯一标识text必填正文内容最好控制在4000个字符以内。parse_mode可选支持纯文本或 Markdown 格式的消息
POST
sendPhoto
上传新图片或选择已有文件发送
可使用 multipart/form-data 上传文件,或通过 file_id 复用已有资源。
chat_id必填目标会话唯一标识photo必填图片文件、公开 URL 或 file_idcaption可选图片说明文字WEBHOOK
实时接收事件
每当有新消息推送、成员发生变动或触发按钮回调时,Webhook 都会主动向你的 HTTPS 端点推送事件通知。接收方在完成签名验证后,应当迅速作出响应 2xx对于耗时较长的操作,建议通过队列进行异步化处理。
上线前检查
下一步行动