三条 开放平台 BETA
santiao.im
BOT API HTTPS JSON

机器人接口简介

借助简洁可靠的 HTTP 接口,轻松打通消息推送、智能回复与业务流。只需简单几步,即可从发送首条消息跃升至实现全套企业级自动化。

5 分钟快速接入

轻量易用的 RESTful API

支持通过 HTTPS 发送请求并以 JSON 格式获取响应,方便各类主流编程语言轻松对接。

安全的服务端鉴权

各个机器人均采用专属的验证令牌,支持按需更换或注销,从而有效防范密钥外泄隐患。

Webhook 与轮询机制

测试时可借助长轮询来加速验证,上线后则改用 Webhook 实现事件的实时同步。

01

快速上手

快速开始

整个调用流程主要分为三步:新建机器人、获取令牌以及向指定接口发送HTTPS请求。接下来,我们以发送文字消息为例,带你快速走通最简接入流程。

  1. 1

    创建一个 Bot

    进入三条客户端的机器人管理界面,新建机器人并配置其名称、头像及使用权限。

  2. 2

    保存访问令牌

    请复制刚生成的 Token,并务必将其存放在服务端的环境变量里,切勿硬编码进网页前端或公开的代码仓库中。

    stb_demo_x8mQ••••••••••••4n2K
  3. 3

    发送第一条消息

    通过 身份授权 请求头携带 Token,同时借助 JSON 格式来收发会话及消息数据。

02

身份验证

鉴权机制及接口路径

全部请求皆需借助 Bot Token 进行身份核验,推荐采用标准的 Bearer 请求头部格式:

接口根路径(参考样例)
https://api.santiao.im/bot/v1

请妥善保管好你的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!"
  }'
03

RESPONSE

标准响应格式

所有接口均采用JSON格式响应。经由 ok 检查接口是否调用成功,有效结果存放在 result,错误详情位于 error。

200 · 成功响应
{
  "ok": true,
  "result": {
    "message_id": "msg_91af2",
    "chat_id": "chat_8c12f",
    "status": "sent"
  }
}
400 · 错误响应
{
  "ok": false,
  "error": {
    "code": 40002,
    "message": "Invalid chat_id",
    "request_id": "req_a71d"
  }
}
04

ERRORS

通用错误码

HTTP错误码含义建议处理
40040002请求参数无效参照 message 字段核对必需的参数及相应的数据格式
40140101凭证失效或不在有效期内刷新访问令牌,并核对 Bearer 认证头信息
40340303机器人暂无执行权限核实机器人当前所处的对话窗口及其权限边界
40440401资源或方法不存在请核对一下资源ID、具体路径以及API的版本号。
42942901请求频率超过限制获取 Retry-After 头部信息后,采用指数退避算法再次尝试
50050000服务端暂时异常保留 request_id,稍后重试或提交诊断
05

METHODS

可用方法

各类方法已按业务场景分类归纳。轻点任一方法即可查看其作用与核心参数,助您高效查找。

GET getMe 查看当前机器人的基础档案

该接口用来校验 Token 的有效性,成功后会输出机器人的编号、昵称、头像以及具备的功能权限。

身份授权必填Bearer 机器人令牌
GET getUpdates 通过长轮询机制来拉取最新的事件通知

该方案契合本地调试及轻量化服务场景;若部署于线上生产环境,推荐改用 Webhook 以防范频繁拉取带来的性能损耗。

offset可选首个需要返回的 update_id
timeout可选长轮询的超时等待时间,推荐设置为 20 到 50 秒
POST 发送消息 给特定的聊天窗口推送文字信息

兼容普通文本及基础 Markdown 格式,若操作成功将输出新建的 Message 实例。

chat_id必填目标会话唯一标识
text必填正文内容最好控制在4000个字符以内。
parse_mode可选支持纯文本或 Markdown 格式的消息
POST sendPhoto 上传新图片或选择已有文件发送

可使用 multipart/form-data 上传文件,或通过 file_id 复用已有资源。

chat_id必填目标会话唯一标识
photo必填图片文件、公开 URL 或 file_id
caption可选图片说明文字
06

WEBHOOK

实时接收事件

每当有新消息推送、成员发生变动或触发按钮回调时,Webhook 都会主动向你的 HTTPS 端点推送事件通知。接收方在完成签名验证后,应当迅速作出响应 2xx对于耗时较长的操作,建议通过队列进行异步化处理。

1 事件发生 新消息 / 成员变更
2 三条推送 采用 HTTPS POST 请求结合数字签名
3 业务处理 验签 / 入队 / 响应

上线前检查

07

下一步行动

准备开始构建?

已复制到剪贴板