机器人开发

Bot API 参考

完整列出 Pabal 的 HTTP Bot API 接受的方法、收发的对象以及错误。与 Telegram Bot API 兼容。

Pabal 的 HTTP Bot API 使用与 Telegram Bot API 相同的地址格式、请求、响应和错误。本文档只列出 Pabal 实际接受的内容。这里没有列出的方法会返回 404 Not Found: method not found。如果你是第一次接触，请先阅读创建机器人教程。

发送请求

https://pabal.me/bot<令牌>/<方法>

HTTP 方法：GET 和 POST 都可以。
发送参数的四种方式——查询字符串（?chat_id=1&text=hi）、application/x-www-form-urlencoded、application/json，以及上传文件时的 multipart/form-data。也可以混合使用。
对象类型的参数（reply_markup、commands、allowed_updates）在 JSON 正文中直接写成对象或数组，在表单和查询字符串中则写成 JSON 字符串。
方法名不区分大小写（sendMessage = sendmessage）。
正文大小上限为 12MB（超过则返回 413）。
下载文件使用单独的地址 https://pabal.me/file/bot<令牌>/<file_path>（见 getFile）。

响应与错误

响应始终是 JSON。成功时返回 HTTP 200 和 result；失败时返回相应的 HTTP 状态、与之相同的 error_code，以及供人阅读的 description。

{"ok": true, "result": { … }}

{"ok": false, "error_code": 400, "description": "Bad Request: chat not found"}

error_code	何时出现	description 示例
`400`	参数有误	`Bad Request: chat not found`, `Bad Request: message text is empty`, `Bad Request: message is not modified: …`, `Bad Request: message to edit not found`, `Bad Request: wrong file identifier/HTTP URL specified`, `Bad Request: query is too old and response timeout expired or query ID is invalid`
`401`	令牌错误	`Unauthorized`
`403`	没有发送权限	`Forbidden: bot can't initiate conversation with a user`, `Forbidden: bot is not a member of the group chat`
`404`	方法或文件不存在	`Not Found: method not found`
`409`	设置了 Webhook 却调用 getUpdates	`Conflict: can't use getUpdates method while webhook is active; use deleteWebhook to delete the webhook first`
`413`	正文超过 12MB	`Request Entity Too Large`
`500`	服务器内部错误	`Internal Server Error`

Pabal 目前还没有请求频率限制（429 Too Many Requests），但将来可能会加上，所以请把程序写成收到 429 时等待 parameters.retry_after 秒后再重试。

接收更新

从以下两种方式中选择一种。两者不能同时使用。

getUpdates

POST/bot<令牌>/getUpdates

获取正在等待的更新（长轮询）。如果设置了 Webhook，则返回 409。

参数	类型	必填	说明
`offset`	Integer	可选	只返回编号大于或等于此值的更新。比它小的更新会作为“已收到”被删除。请传入最后处理的 `update_id + 1`。
`limit`	Integer	可选	1~100，默认 100
`timeout`	Integer	可选	等待的秒数，0~50，默认 0。建议使用 25~30。
`allowed_updates`	Array of String	忽略	会接收但不使用。如需按类型过滤，请在收到后自行过滤。

返回值：Array of Update

setWebhook

POST/bot<令牌>/setWebhook

通过 HTTPS 地址接收更新。详细说明请参阅 Webhook 文档。

参数	类型	必填	说明
`url`	String	是	https:// 公网地址。传入空字符串会删除 Webhook
`secret_token`	String	可选	1~256 个字符，`A-Z a-z 0-9 _ -`。通过请求头 `X-Telegram-Bot-Api-Secret-Token` 发送
`allowed_updates`	Array of String	可选	从 `message`、`edited_message`、`callback_query` 中选择。留空表示全部
`drop_pending_updates`	Boolean	可选	丢弃正在等待的更新
`max_connections`	Integer	可选	1~100，默认 40。只做保存，发送时每个机器人一次只发一个
`certificate`	InputFile	不支持	返回 400——请使用公共证书
`ip_address`	String	忽略

返回值：True

deleteWebhook

POST/bot<令牌>/deleteWebhook

删除 Webhook，回到 getUpdates。即使没有设置 Webhook 也会成功。

参数	类型	必填	说明
`drop_pending_updates`	Boolean	可选	丢弃正在等待的更新

返回值：True

getWebhookInfo

GET/bot<令牌>/getWebhookInfo

Webhook 的状态。没有参数。没有设置 Webhook 时，url 为空字符串。

返回值：WebhookInfo

方法

方法	作用
`getMe`	机器人自身的信息
`sendMessage`	发送文字（可带按钮）
`sendPhoto`	发送照片
`editMessageText`	修改已发送消息的文字和按钮
`editMessageCaption`	修改照片说明
`editMessageReplyMarkup`	只修改按钮
`deleteMessage`	删除消息
`answerCallbackQuery`	回答按钮点击
`sendChatAction`	“正在输入”提示（只接收）
`getChat`	对话信息
`getFile`	收到的照片的下载路径
`setMyCommands` · `getMyCommands` · `deleteMyCommands`	命令菜单
`logOut` · `close`	用于兼容（不执行任何操作）
`getUpdates` · `setWebhook` · `deleteWebhook` · `getWebhookInfo`	接收更新（见上文）

chat_id 可以填什么

一对一对话时填用户的 ID（正数），普通群组时填群组 ID（负数），或者填用户的用户名（"@hana_lee"）。这些都可以从更新的 chat.id 中得知。频道和超级群组的 ID（-100…）目前还不存在（400 chat not found）。

getMe

GET/bot<令牌>/getMe

用于确认令牌是否正确。没有参数。

返回值：User——对于机器人，还会额外带上 can_join_groups（true）、can_read_all_group_messages（true）、supports_inline_queries（false）、can_connect_to_business（false）、has_main_web_app（false）。

sendMessage

POST/bot<令牌>/sendMessage

参数	类型	必填	说明
`chat_id`	Integer 或 String	是	发送到的对话（参见上面的提示框）
`text`	String	是	1~4,096 个字符。按原样发送文字
`reply_markup`	InlineKeyboardMarkup · ReplyKeyboardMarkup · ReplyKeyboardRemove · ForceReply	可选	按钮
`disable_notification`	Boolean	可选	静默发送
`parse_mode`, `entities`, `reply_parameters`, `link_preview_options` …		忽略	会接收但不使用。不会应用任何格式

返回值：发送出去的 Message

要发送给某个用户，该用户必须先与机器人对话过（403 Forbidden: bot can't initiate conversation with a user）。要发送到群组，机器人必须是该群组的成员。

sendPhoto

POST/bot<令牌>/sendPhoto

参数	类型	必填	说明
`chat_id`	Integer 或 String	是	发送到的对话
`photo`	InputFile 或 String	是	用 `multipart/form-data` 上传的文件（最大 10MB，JPEG、PNG、GIF），或者之前收到的照片的 `file_id`。暂不支持 URL
`caption`	String	可选	0~1,024 个字符
`reply_markup`	与 sendMessage 相同	可选
`disable_notification`	Boolean	可选

返回值：发送出去的 Message（photo 中带有新的 file_id）

editMessageText

POST/bot<令牌>/editMessageText

参数	类型	必填	说明
`chat_id`	Integer 或 String	是	消息所在的对话
`message_id`	Integer	是	要修改的消息（机器人发送的）
`text`	String	是	新的文字，1~4,096 个字符
`reply_markup`	InlineKeyboardMarkup	可选	新的按钮。省略时按钮会被移除（与 Telegram 相同）
`inline_message_id`	String	不支持	没有内联模式，因此返回 400

返回值：修改后的 Message。修改会立即反映到应用中；用户修改的消息则会以 edited_message 发给机器人。

文字和按钮与之前完全相同时，返回 400 Bad Request: message is not modified: …；试图修改别人的消息时，返回 400 Bad Request: message can't be edited。

editMessageCaption

POST/bot<令牌>/editMessageCaption

参数为 chat_id、message_id、caption（0~1,024 个字符，省略则删除说明）、reply_markup。返回值：修改后的 Message。

editMessageReplyMarkup

POST/bot<令牌>/editMessageReplyMarkup

保持文字不变，只更换按钮。参数为 chat_id、message_id、reply_markup（省略则删除按钮）。返回值：修改后的 Message。

deleteMessage

POST/bot<令牌>/deleteMessage

参数为 chat_id、message_id。在对话双方那里都删除该消息。消息不存在时返回 400 Bad Request: message to delete not found。返回值：True。

answerCallbackQuery

POST/bot<令牌>/answerCallbackQuery

回答用户点击的按钮（CallbackQuery）。必须在 10 秒内回答，且只能回答一次。

参数	类型	必填	说明
`callback_query_id`	String	是	更新中的 `callback_query.id`
`text`	String	可选	在屏幕上方短暂显示的文字
`show_alert`	Boolean	可选	为 true 时显示为带确认按钮的对话框
`url`	String	可选	让应用打开的地址
`cache_time`	Integer	可选	应用缓存此回答的秒数

返回值：True。如果为时已晚或已经回答过，返回 400 Bad Request: query is too old and response timeout expired or query ID is invalid。

sendChatAction

POST/bot<令牌>/sendChatAction

为了兼容会接收请求并返回 True，但目前还不会在应用中显示“正在输入…”。

getChat

GET/bot<令牌>/getChat?chat_id=…

参数为 chat_id（数字）。如果是用户，就返回该用户；如果是群组，则仅限机器人是其成员的群组。返回值：Chat。不存在或无权查看时，返回 400 Bad Request: chat not found。

getFile

GET/bot<令牌>/getFile?file_id=…

用收到的照片的 file_id 获取下载路径。返回值：File。然后通过下面的地址下载。

https://pabal.me/file/bot<令牌>/<file_path>

file_id 同时也是取得该照片的凭证。值无效时，返回 400 Bad Request: wrong file identifier/HTTP URL specified。

setMyCommands

POST/bot<令牌>/setMyCommands

参数	类型	必填	说明
`commands`	Array of BotCommand	是	最多 100 条
`language_code`	String	可选	保存为该语言的列表。目前应用中只显示未指定语言代码的默认列表
`scope`	BotCommandScope	忽略

返回值：True。不符合命令规则时，返回 400 Bad Request: BOT_COMMAND_INVALID。

getMyCommands

GET/bot<令牌>/getMyCommands

参数为 language_code（可选）。返回值：Array of BotCommand。

deleteMyCommands

POST/bot<令牌>/deleteMyCommands

参数为 language_code（可选）。清空该列表。返回值：True。

logOut · close

在 Telegram 中，这两个方法用于迁移到本地 Bot API 服务器。Pabal 没有可以迁移的目标，因此只会接收请求并返回 True。要让令牌失效，请使用 BotFather 的 /revoke。

对象

字段旁边的可选表示该字段可能不存在。这里没有列出的 Telegram 其他字段，Pabal 不会发送。

Update

一条新的更新。包含 update_id 以及下面三者中的一个。

字段	类型	说明
`update_id`	Integer	逐次加 1 的编号。用于 getUpdates 的 `offset`
`message` 可选	Message	发给机器人的新消息（一对一对话，或机器人所在群组中的所有消息）
`edited_message` 可选	Message	被修改的消息
`callback_query` 可选	CallbackQuery	内联按钮点击

User

字段	类型	说明
`id`	Integer	用户 ID（只在这台服务器内有意义）
`is_bot`	Boolean	机器人为 true
`first_name`	String	名字。已删除的账号为 `Deleted Account`
`last_name` 可选	String	姓氏
`username` 可选	String	用户名（不带 `@`）

Chat

字段	类型	说明
`id`	Integer	用户为该用户的 ID（正数），普通群组为负数
`type`	String	`private` 或 `group`
`title` 可选	String	群组名称（group）
`first_name`, `last_name`, `username` 可选	String	对方的名字和用户名（private）

Message

字段	类型	说明
`message_id`	Integer	该对话中的消息编号
`from` 可选	User	发送者
`chat`	Chat	消息所在的对话
`date`	Integer	发送时间（Unix 秒）
`edit_date` 可选	Integer	最后一次修改的时间
`text` 可选	String	文字（不是照片消息时总会有）
`entities` 可选	Array of MessageEntity	文字中的命令、提及、URL、话题标签
`photo` 可选	Array of PhotoSize	照片（Pabal 只有一张原图）
`caption` 可选	String	照片说明
`caption_entities` 可选	Array of MessageEntity	说明中的命令、提及、URL、话题标签
`reply_markup` 可选	InlineKeyboardMarkup	消息上附带的内联按钮

MessageEntity

字段	类型	说明
`type`	String	`bot_command`, `mention`, `url`, `hashtag`
`offset`	Integer	起始位置（UTF-16 代码单元）
`length`	Integer	长度（UTF-16 代码单元）

由服务器在文字中自动识别并附上。粗体、斜体等格式实体目前还没有。

PhotoSize

字段	类型	说明
`file_id`	String	用于下载（getFile）和再次发送（sendPhoto）的 ID
`file_unique_id`	String	同一张照片即使在不同机器人那里也是相同的值。不能用于下载
`width`, `height`	Integer	像素尺寸
`file_size`	Integer	字节数

File

字段	类型	说明
`file_id`, `file_unique_id`	String	与 PhotoSize 相同
`file_size`	Integer	字节数
`file_path`	String	`photos/<file_id>.jpg` 形式。接在 `/file/bot<令牌>/` 后面即可下载

CallbackQuery

字段	类型	说明
`id`	String	传给 answerCallbackQuery 的 ID
`from`	User	点击按钮的用户
`message` 可选	Message	附带该按钮的消息
`chat_instance`	String	代表该对话的值
`data` 可选	String	按钮的 `callback_data`

InlineKeyboardMarkup

inline_keyboard：Array of Array of InlineKeyboardButton——外层数组是行，内层数组是一行中的按钮。一条消息最多 100 行、100 个按钮。

InlineKeyboardButton

字段	类型	说明
`text`	String	按钮上的文字
`callback_data` 二选一	String	点击后发给机器人的值，1~64 字节
`url` 二选一	String	点击后打开的地址

switch_inline_query、web_app、login_url、pay 等其他类型目前还没有（400）。

ReplyKeyboardMarkup

字段	类型	说明
`keyboard`	Array of Array of KeyboardButton	输入框下方的按钮面板
`resize_keyboard`, `one_time_keyboard`, `is_persistent`, `selective` 可选	Boolean	自动调整大小 · 使用一次后隐藏 · 始终显示 · 只对特定用户显示
`input_field_placeholder` 可选	String	输入框中的提示文字

KeyboardButton

一个字符串，或者一个包含 text 以及可选字段 request_contact（发送我的联系方式）、request_location（发送我的位置，Boolean）的对象。

ReplyKeyboardRemove

{"remove_keyboard": true}——隐藏按钮面板。selective 可选。

ForceReply

{"force_reply": true}——应用会以回复这条消息的状态打开输入框。selective、input_field_placeholder 可选。

BotCommand

字段	类型	说明
`command`	String	1~32 个小写英文字母、数字和下划线（不带 `/`）
`description`	String	1~256 个字符

WebhookInfo

字段	类型	说明
`url`	String	Webhook 地址，没有则为空字符串
`has_custom_certificate`	Boolean	始终为 false
`pending_update_count`	Integer	等待送达的更新数量
`ip_address` 可选	String	最近一次发送的目标 IP
`last_error_date` 可选	Integer	最后一次失败的时间（Unix 秒）
`last_error_message` 可选	String	最后一次失败的原因（列表）
`max_connections` 可选	Integer	在 setWebhook 中传入的值
`allowed_updates` 可选	Array of String	在 setWebhook 中传入的值

与 Telegram Bot API 的不同之处

更新类型：只有 message、edited_message、callback_query。没有频道帖子、内联查询、支付、投票、成员变更（my_chat_member）等。
格式：忽略 parse_mode 和 entities，按原样发送文字。只有命令、提及、URL、话题标签会自动显示。
对话类型：只有一对一对话和普通群组。没有频道、超级群组和论坛话题。
媒体：只有照片。没有文件、视频、语音、贴纸、相册，也不能通过 URL 发送。
群组中的机器人：没有隐私模式，会收到群组中的所有消息。
队列：尚未取走的更新，每个机器人最多在内存中保留最近 1,000 条，服务器重启时会丢失（Telegram 保留 24 小时）。
Webhook：一次发送一个、按顺序发送（max_connections 只做保存），不接受自签名证书，没有端口限制。
ID：用户、消息、文件的 ID 只在这台服务器内有意义。由于没有频道和超级群组，也没有 -100… 形式的 ID。
不存在的方法：上面列表中没有的方法（forwardMessage、copyMessage、sendDocument、sendPoll、getChatMember、banChatMember、answerInlineQuery …）会返回 404 Not Found: method not found。