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

机器人接口简介

借助稳定且规范的 HTTP 接口,轻松打通消息推送、自动回复以及业务系统。从发送第一条消息到实现全流程的企业自动化,全程仅需简单几步。

5 分钟快速接入

轻量易用的 RESTful API

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

安全的服务端鉴权

各机器人均配有专属验证令牌,支持随时更换或吊销,从而有效防范凭证外泄。

Webhook 与轮询机制对比

前期借助长轮询在开发中高效测试,上线后则通过 Webhook 实现事件的实时触发。

01

快速上手

快速开始

完整的调用流程由三步构成:新建机器人、申请 Token、调用相应接口发送 HTTPS 请求。接下来以发送文本消息为例,展示最简便的接入步骤。

  1. 1

    创建一个 Bot

    前往三条客户端的机器人管理后台,新建一个机器人并完善其昵称、头像以及权限范围。

  2. 2

    保存访问令牌

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

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

    发送第一条消息

    请把令牌(Token)填入 权限验证 请求头中,同时采用 JSON 格式来收发会话及消息数据。

02

身份验证

关于身份校验及访问源IP

全部请求皆需通过 Bot Token 完成身份核验,推荐采用标准的 Bearer 请求头格式:

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

请妥善保管好你的访问令牌。 严禁把该凭证推送到 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!"
  }'
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请求参数无效对照消息内容核对关键字段及数据格式
40140101令牌失效或过期,请重新获取请刷新访问令牌,并核对 Bearer 认证请求头。
40340303机器人暂无相关执行权限核实机器人所在的聊天场景及其权限配置
40440401资源或方法不存在核实资源标识、访问路径及接口版本
42942901请求频率超过限制通过获取 Retry-After 头部信息,采用指数退避策略进行重试
50050000服务端暂时异常保留 request_id,稍后重试或提交诊断
05

METHODS

可用方法

各类方法已按具体的业务场景归类,点击即可查看其具体用途和核心参数,方便用户快速查找。

GET getMe 查询此机器人(Bot)的概况信息

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

权限验证必填Bearer Bot Token
GET 获取更新 通过长轮询机制来拉取最新的事件

该方案更契合本地调试及轻量级访问场景;若部署至生产环境,推荐改用 Webhook 以防范频繁轮询带来的资源浪费。

offset可选首个需要返回的 update_id
timeout可选长轮询的等待时间,推荐设定在20至50秒之间
POST 发送消息 给特定的对话框推送文字内容

兼容普通文本及基础 Markdown 格式,若操作成功则会输出新建的 Message 实体对象。

chat_id必填目标会话唯一标识
text必填正文内容最好控制在4000个字符以内
parse_mode可选支持纯文本(plain)与 markdown 两种消息格式
POST 发送图片 可直接传图,或是选用之前上传过的文件。

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

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

WEBHOOK

实时接收事件

每当有新消息、人员变动或按钮触发时,Webhook 便会向你的 HTTPS 端点推送事件通知。服务方在完成签名验证后,应当迅速给出响应。 2xx,建议将耗时操作放入队列中进行异步执行。

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

上线前检查

07

后续行动计划

准备开始构建?

已复制到剪贴板