机器人开发

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"}

Pabal 目前还没有针对全部请求的频率限制，但语音方法有每小时限额，超过时返回 429 Too Many Requests: retry after N（语音通话）。请把程序写成收到 429 时等待 parameters.retry_after 秒后再重试。

接收更新

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

getUpdates

POST/bot<令牌>/getUpdates

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

返回值：Array of Update

setWebhook

POST/bot<令牌>/setWebhook

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

返回值：True

deleteWebhook

POST/bot<令牌>/deleteWebhook

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

返回值：True

getWebhookInfo

GET/bot<令牌>/getWebhookInfo

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

返回值：WebhookInfo

方法

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

返回值：发送出去的 Message

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

sendPhoto

POST/bot<令牌>/sendPhoto

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

sendDocument

POST/bot<令牌>/sendDocument

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

格式（mime_type）根据文件名的扩展名确定。从应用发送的文件最大 2GB，但机器人通过 HTTP 上传和下载的上限与 Telegram 一样，为 20MB。

sendLocation

POST/bot<令牌>/sendLocation

返回值：发送出去的 Message（location 中带有 Location）

sendVenue

POST/bot<令牌>/sendVenue

返回值：发送出去的 Message（venue 中带有 Venue，location 中也有同一位置）

缺少 title 或 address 时返回 400 Bad Request: title and address are required。

sendContact

POST/bot<令牌>/sendContact

返回值：发送出去的 Message（contact 中带有 Contact）

机器人发送的联系人名片不会带 user_id，即使该号码属于某个 Pabal 账号也是如此——机器人没有联系人；如果填上，机器人只要每个号码发一张名片，就能查出号码属于谁。缺少 phone_number 或 first_name 时返回 400 Bad Request: phone_number and first_name are required。

editMessageLiveLocation

POST/bot<令牌>/editMessageLiveLocation

返回值：修改后的 Message

已经结束的实时位置——已停止或时长已到——既不能移动，也不能通过延长时长使其恢复（400 Bad Request: message can't be edited）。不是实时位置的消息也一样。

距上一次生效的移动不足 10 秒，或移动距离不足 10 米的移动，服务器不会保存，直接略过。停止以及时长、提醒半径的变更则总会生效。被略过时，返回的 Message 显示最后一次生效的位置，因此每隔几秒发送一次也没有问题。

stopMessageLiveLocation

POST/bot<令牌>/stopMessageLiveLocation

参数为 chat_id、message_id、reply_markup（可选）。让实时位置停在最后的位置。共享时长会缩短为实际经过的时间，因此所有应用都会把它显示为已结束。如果已经停止或结束，返回 400 Bad Request: message is not modified: …。返回值：修改后的 Message。

editMessageText

POST/bot<令牌>/editMessageText

返回值：修改后的 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 秒内回答，且只能回答一次。

返回值：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

返回值：True。不符合规则时什么也不保存，返回 400 Bad Request: BOT_COMMAND_INVALID（命令）、BOT_COMMAND_DESCRIPTION_INVALID（说明为空或超过 256 个字符）、BOT_COMMANDS_TOO_MUCH（超过 100 个）。

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 以及下面各项中的一个。

User

Chat

Message

MessageEntity

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

PhotoSize

Document

Location

用户共享的实时位置，每当服务器应用一次移动，都会以 edited_message 再次送达。

Venue

Contact

File

CallbackQuery

InlineKeyboardMarkup

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

InlineKeyboardButton

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

ReplyKeyboardMarkup

KeyboardButton

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

ReplyKeyboardRemove

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

ForceReply

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

BotCommand

WebhookInfo

语音通话

这些方法只有 Pabal 才有。语音机器人是指有人在应用中给它打电话时由 AI 语音模型接听的机器人，这些方法用来设定该模型的设置并处理通话。需要开启哪些条件、如何开启以及示例，请参阅语音机器人指南。即使服务器上关闭了语音，这些方法也依然存在，可以读取设置；但语音已关闭或尚未获得运营方允许的机器人，除了关闭和删除之外不能修改设置（403 VOICE_NOT_AVAILABLE）。

setVoiceCallSettings

POST/bot<令牌>/setVoiceCallSettings

修改机器人的语音设置。只修改所发送的字段；先检查全部内容，然后一次写入，或者全部拒绝。每个机器人每小时 30 次（与 @BotFather 合计）。

返回值：True

getVoiceCallSettings

GET/bot<令牌>/getVoiceCallSettings

没有参数。返回当前设置、机器人现在能否接听电话（available、unavailable_reason）、服务器的限额、音色和语言列表、工具查询和文字记录的去向，以及自有密钥、音频流模式和 MCP 服务器的状态。不显示密钥和机密值，只显示指纹。字段见语音机器人——查看当前设置。

返回值：VoiceCallSettings（对象）

endVoiceCall

POST/bot<令牌>/endVoiceCall

返回值：True。如果不是这个机器人正在进行的通话，返回 400 VOICE_CALL_NOT_FOUND。

sendVoiceCallContext

POST/bot<令牌>/sendVoiceCallContext

返回值：True。接通前返回 VOICE_CALL_NOT_ACTIVE，音频流通话返回 VOICE_CONTEXT_NOT_SUPPORTED，过长返回 VOICE_CONTEXT_TOO_LONG，每通电话每分钟超过 10 条返回 429。

getVoiceCallUsage

GET/bot<令牌>/getVoiceCallUsage

返回值：period、from_date、to_date、calls、seconds、missed、refused（busy·budget·unavailable）、platform_seconds、own_key_seconds、remaining_seconds_today（bot·owner），曾开启过外呼的机器人还有 outbound（today·limits）——日期分界以服务器的时区为准

startVoiceCall

POST/bot<令牌>/startVoiceCall

机器人给人打电话。只有机器人所有者在 @BotFather 中开启、并经运营方审核的机器人，才能打给许可了该机器人的人。回答和判定见语音机器人——拨打。

返回值：{"voice_call_id": "…"}——只表示已受理，是否响铃、是否接听以 voice_call 更新告知。拒绝：403 VOICE_OUTBOUND_OFF: <原因>、403 USER_UNAVAILABLE（响应体始终相同）、429、503 VOICE_UNAVAILABLE。不能通过 Webhook 响应调用。

answerVoiceCallToolQuery

POST/bot<令牌>/answerVoiceCallToolQuery

返回值：True。第一次回答就是最终回答。太晚时返回 400 TOOL_QUERY_EXPIRED: answered|timeout|cancelled|call_ended|unreachable，未知的 id 返回 TOOL_QUERY_ID_INVALID，回答被拒绝时返回 TOOL_RESULT_EMPTY·TOOL_RESULT_INVALID·TOOL_RESULT_TOO_LONG·TOOL_ERROR_TOO_LONG·TOOL_RESULT_REFUSED: <代码>。对 Webhook 的工具查询 POST，也可以用响应体回答。

setVoiceCallApiKey · deleteVoiceCallApiKey

POST/bot<令牌>/setVoiceCallApiKey

返回值：True——只有通过网关的测试会话后才会保存。API_KEY_INVALID、API_KEY_NO_REALTIME_ACCESS、503 API_KEY_CHECK_UNAVAILABLE（不保存）、403 VOICE_OWN_KEY_NOT_AVAILABLE（这台服务器不接受自有密钥）。deleteVoiceCallApiKey 没有参数，始终返回 True。这两个方法都不能用 bots.sendCustomRequest 调用，setVoiceCallApiKey 也不能在 Webhook 响应中调用。详见自有模型密钥。

MCP 服务器方法

auth 和机密值只能放在请求体中发送。在关闭了 MCP 的服务器上返回 403 VOICE_NOT_AVAILABLE: MCP tools are not available on this server。详见语音机器人——MCP 服务器。

如何接收语音更新

voice_call、voice_call_tool_query、voice_call_transcript 只有按名称请求才会送达——请把它们写进 getUpdates 或 setWebhook 的 allowed_updates。传空列表收不到，请求之前发生的也不会保留。有 Webhook 时，工具查询以单独的 POST 送达；最近 15 秒内调用过 getUpdates 时，则放在下一次 getUpdates 的最前面。

VoiceCall

VoiceCall 中没有告诉你来电者是否选择了保存对话的字段。这是有意为之——那些文字属于来电者本人，不会发给机器人。因此，在开启了保存对话的服务器上，所有非音频流模式通话的 ended 都会等待同样的时间，而且在所有通话中，通话记录之后那条消息的编号都比记录大 31 以上（编号会预先占用）。

VoiceCallToolQuery

VoiceCallTranscript

只通过 HTTP Bot API 送达。整通电话的内容在已结束的 voice_call 的 transcript 中。

音频流模式（mode=stream）

在音频流模式下，通话声音不是发给 Pabal 的 AI 模型，而是发给机器人所有者的服务器。向 setVoiceCallSettings 发送 mode=stream、stream_url=wss://…、stream_secret=…（32~128 个可打印 ASCII 字符，只能放在请求体中）后，Pabal 的网关会试着连接一次该地址（探测），成功后开启。需要机器人所有者条款，以及包含音频流确认窗口的应用版本。设置、探测结果和示例见语音机器人——音频流模式。

• 连接：TLS 1.2 及以上，与 URL 中名称相符的公共证书，子协议 pabal.voice.v1，不压缩，每条消息最多 64KiB、文本最多 4KiB，不重定向。
• 签名：X-Pabal-Voice-Signature: t=…,nonce=…,call=…,v1=HMAC-SHA256(stream_secret, "pabal-voice-stream/1\n<t>\n<nonce>\n<call>\n<host>\n<path?query>")。host 是你提供的 URL 的主机。需检查 300 秒、nonce 只用一次、逐字节比较，以及 start.call_id 是否与 call 相同（详见）。
• 声音：文本消息是 JSON 事件，二进制是 PCM16 小端序、单声道、24 kHz。来电者的声音为 20 ms（960 字节）的分片。
• Pabal → 机器人：start（一次） · live（AI 提示已结束） · 声音 · mark · cleared · buffer_full · stop（→ 以 1000 关闭）。
• 机器人 → Pabal：ready（start 之后 3 秒内，最先发送） · 声音（live 之后） · clear · mark · hangup。

每条消息的具体格式见语音机器人——规范中的表格。

语音方法的错误

语音方法的错误代码及含义汇总在语音机器人——错误中。403 的形式为 Forbidden: <代码>: <说明>（VOICE_RULES_NOT_ACCEPTED、VOICE_NOT_AVAILABLE、VOICE_SUSPENDED、VOICE_OWNER_TERMS_NOT_ACCEPTED、VOICE_OWN_KEY_NOT_AVAILABLE、VOICE_STREAM_NOT_AVAILABLE、VOICE_OUTBOUND_OFF），只有 USER_UNAVAILABLE 不带说明，始终是 Forbidden: USER_UNAVAILABLE；超过每小时限额时返回 429 和 retry_after。

与 Telegram Bot API 的不同之处

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