Bot API 概览
SafeXTM Bot API 的核心是一套通过 HTTPS 请求进行交互、以 JSON 格式返回响应的软件服务。
Bot 本质上是一段程序、脚本或服务，通过 HTTPS 请求查询 API 并等待响应。你可以发起多种类型的请求，也可以使用和接收多种不同的对象。
获取 Bot Token
Token 是一个字符串，用于在 Bot API 上验证你的 Bot（而非你的账号）身份。每个 Bot 都有唯一的 Token，可以随时通过 @BotFather 撤销。
获取 Token 非常简单：联系 @BotFather，发送 /newbot 命令并按照步骤操作即可获得新 Token。你可以在快速开始中找到详细指引。
Token 格式如下：
4839574812:AAFD39kkdpWt3ywyRZergyOLMaJhac60qc发起请求
所有请求通过 URL 中的 Token 进行认证，格式为：
https://api.safew.bot/bot<YOUR_BOT_TOKEN>/methodName由于浏览器本身就能发送 HTTPS 请求，你可以用它快速体验 API。获取 Token 后，尝试在浏览器中粘贴以下地址：
https://api.safew.bot/bot<YOUR_BOT_TOKEN>/getMe理论上，你可以通过浏览器或 cURL 等工具发送这样的基本请求来与 API 交互。虽然对于上面这种简单请求来说没问题，但对于更大型的应用来说并不实用，也难以扩展。
请求数据格式为 JSON，文件上传使用 multipart/form-data。
标准响应格式
成功响应
json
{
"ok": true,
"result": {
...
}
}错误响应
json
{
"ok": false,
"error_code": 400,
"description": "Bad Request: ...",
"trace_id": "abc123"
}通用错误码
| 错误码 | 描述 |
|---|---|
| 400 | 请求参数错误 |
| 401 | Token 无效或已过期 |
| 403 | Bot 无权执行该操作 |
| 404 | 方法不存在或资源未找到 |
| 429 | 请求过于频繁，触发限流 |
| 500 | 服务器内部错误 |
可用方法
基础方法
| 方法 | 描述 | HTTP 方法 |
|---|---|---|
| getMe | 获取 Bot 基本信息 | GET / POST |
| getUpdates | 长轮询获取更新 | GET / POST |
发送消息
| 方法 | 描述 | HTTP 方法 |
|---|---|---|
| sendMessage | 发送文本消息 | POST |
| sendMessageDraft | 向用户私聊输入框推送草稿（SafeXTM 扩展） | POST |
| sendPhoto | 发送图片 | POST |
| sendVideo | 发送视频 | POST |
| sendVoice | 发送语音 | POST |
| sendAudio | 发送音频 | POST |
| sendDocument | 发送文档 | POST |
| sendMediaGroup | 发送媒体组 | POST |
| sendDice | 发送随机动画表情 | POST |
编辑消息
| 方法 | 描述 | HTTP 方法 |
|---|---|---|
| editMessageText | 编辑消息文本 | POST |
| editMessageReplyMarkup | 编辑消息回复标记 | POST |
小游戏
| 方法 | 描述 | HTTP 方法 |
|---|---|---|
| 小游戏概览 | HTML5 游戏接入说明与流程 | — |
| sendGame | 发送游戏卡片 | POST |
| setGameScore | 提交/更新用户分数 | POST |
| getGameHighScores | 获取游戏高分榜 | POST |
内联模式
| 方法 | 描述 | HTTP 方法 |
|---|---|---|
| answerInlineQuery | 回复内联查询 | POST |
文件上传说明
以下方法支持文件上传，需使用 multipart/form-data 编码：
sendPhoto- 图片文件，最大 10MBsendVideo- 视频文件sendVoice- 语音文件sendAudio- 音频文件sendDocument- 文档文件，最大 100MBsendMediaGroup- 媒体组，最多 10 个文件
除了直接上传文件外，也可以传入已上传文件的 file_id 来复用已有文件。