Bot API 概览

一次完整调用包含三个部分：创建 Bot、获取 Token、向对应方法发起 HTTPS 请求。 下面用发送文本消息演示最短接入路径。

1. 1

   创建一个 Bot

   在三条客户端中打开 Bot 管理入口，创建 Bot 并设置名称、头像与可用范围。

2. 2

   保存访问令牌

   复制创建后生成的 Token。它只应保存在你的服务端环境变量中，不要写入网页或公开仓库。

   stb_demo_x8mQ••••••••••••4n2K 复制
3. 3

   发送第一条消息

   将 Token 放入 Authorization 请求头，并使用 JSON 传递接收会话与消息内容。

所有请求均通过 Bot Token 验证身份。建议使用标准 Bearer 请求头：

通用请求格式

curl -X POST \
  https://api.santiao.im/bot/v1/sendMessage \
  -H "Authorization: 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/sendMessage",
  {
    method: "POST",
    headers: {
      Authorization: `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/sendMessage",
    headers={
        "Authorization": f"Bearer {os.environ['SANTIAO_BOT_TOKEN']}"
    },
    json={
        "chat_id": "chat_8c12f",
        "text": "Hello from Santiao Bot!",
    },
)

print(response.json())

接口统一返回 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"
  }
}

方法按业务场景组织。点击任意方法可展开用途与关键参数，便于快速定位。

Webhook 会在新消息、成员变更或按钮回调发生时，向你的 HTTPS 地址发送事件。 服务应在校验签名后快速返回 2xx，耗时任务建议进入队列异步处理。