Message automation

让你的服务，自动参与对话

SafeW Bot API 是一组基于 HTTPS 的机器人接口。你的程序通过 Bot Token 调用方法，以 JSON 接收结果，并通过长轮询或 Webhook 获取新消息。

50+ 消息、群组、成员与邀请链接方法

2 种 长轮询与 Webhook 更新模式

100 MB 文档文件上传上限

JSON 统一成功与错误响应结构

01 / Understand

先理解三个角色

Bot 不是一个真人账号，而是由你的程序控制的服务身份。Token 把一次 API 请求与具体 Bot 关联起来。

BOT

机器人身份

通过 BotFather 创建。它代表你的服务与用户、群组或频道进行交互。

KEY

Bot Token

每个 Bot 的唯一调用凭证，放在请求 URL 中。它只能保存在可信的服务端。

APP

你的后端

发送 HTTPS 请求、处理更新、保存业务状态，并决定 Bot 下一步做什么。

01 / USER

用户发送消息

在 SafeW 中与 Bot 互动

02 / UPDATE

SafeW 传递更新

长轮询获取或 Webhook 推送

03 / RESPONSE

你的服务响应

调用 sendMessage 等方法

02 / Quick start

四步发送第一条消息

建议先验证最短链路：创建 Bot、拿到 Token、确定 chat_id，然后调用 sendMessage。

在 SafeW 中找到 BotFather

向 BotFather 发送 /newbot，按照提示设置 Bot 名称与用户名。

安全保存 Token

将 Token 放入服务端环境变量或密钥管理服务，不要写进前端代码和 Git 仓库。

准备目标 chat_id

chat_id 表示目标用户、群组或频道，是发送消息时的必要参数。

调用 sendMessage

以 JSON 提交 chat_id 与 text。成功后，result 中会返回完整 Message 对象。

cURL · sendMessage

curl -X POST "https://api.safew.bot/bot{YOUR_TOKEN}/sendmessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 123456789,
    "text": "Hello from SafeW",
    "parse_mode": "HTML"
  }'

03 / Request model

所有请求都遵循同一套结构

大多数方法支持 GET 和 POST；发送媒体文件时使用 POST 与 multipart/form-data。

URL

请求地址

https://api.safew.bot/bot{token}/{method}
方法名使用小写形式。

RES

统一响应

ok: true 时读取 result；失败时读取 error_code、description 与 trace_id。

JSON · success / error

// 成功
{
  "ok": true,
  "result": { "message_id": 100 }
}

// 失败
{
  "ok": false,
  "error_code": 400,
  "description": "Bad Request: chat not found",
  "trace_id": "abc123"
}

Token 就是 Bot 的身份凭证

URL 中包含 Token，因此不要把完整请求地址写入公开日志。Token 泄露后应立即通过 BotFather 撤销并重新生成。

04 / Receive updates

长轮询还是 Webhook？

两种模式不能同时使用。开发调试可先用长轮询，持续运行的生产服务通常更适合 Webhook。

更容易开始

长轮询 · getUpdates

你的服务主动请求更新。建议 timeout 设为约 30 秒，并用“已处理的 update_id + 1”作为下一次 offset。

无需公开 HTTPS 回调地址
适合本地开发与低流量服务
limit 范围 1–100

更适合生产

Webhook · setWebhook

SafeW 主动把更新推送到你的 HTTPS 地址。可以设置 secret_token，用于验证请求来源。

实时推送、无需持续轮询
适合稳定在线的后端服务
支持限定 allowed_updates

cURL · setWebhook

curl -X POST "https://api.safew.bot/bot{YOUR_TOKEN}/setwebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "secret_token": "YOUR_WEBHOOK_SECRET",
    "allowed_updates": ["message", "callback_query"]
  }'

05 / Capability map

从消息到群组管理

Bot API 不只是“发文字”。它覆盖媒体、消息编辑、Webhook、聊天与成员管理、邀请链接和交互回调。

getMe getUpdates sendMessage sendPhoto sendVideo sendVoice sendDocument sendMediaGroup editMessageText deleteMessage pinChatMessage getChat promoteChatMember restrictChatMember createChatInviteLink answerCallbackQuery

上传类型	请求方式	限制或说明
图片	`multipart/form-data`	最大 10 MB，也可复用 file_id
文档	`multipart/form-data`	最大 100 MB，也可复用 file_id
媒体组	`multipart/form-data`	一次最多 10 个文件

06 / Reliability

用错误码决定下一步

不要把所有失败都当成同一种错误。认证、权限、限流和服务异常需要不同的处理策略。

错误码	含义	建议处理
`400`	请求参数错误	检查必填字段、类型与目标 chat_id
`401`	Token 无效或过期	停止重试并检查凭证
`403`	Bot 无权执行操作	检查聊天权限和成员状态
`404`	方法或资源不存在	检查 URL、方法名与目标资源
`429`	请求过于频繁	指数退避，避免立即高频重试
`500`	服务端内部错误	记录 trace_id，稍后重试

✓

上线前检查

Token 仅保存在服务端；Webhook 使用 HTTPS 与 secret_token；日志隐藏 Token；429 使用退避策略；关键失败记录 trace_id。