Bot development

Bot API reference

Every method Pabal's HTTP Bot API accepts, the objects it exchanges and its errors, in full. Compatible with the Telegram Bot API.

Pabal's HTTP Bot API uses the same address format, requests, responses and errors as the Telegram Bot API. This reference covers only what Pabal actually accepts. Methods not listed here return 404 Not Found: method not found. If you're new, start with the bot tutorial.

Making requests

https://pabal.me/bot<token>/<method>

• HTTP methods: both GET and POST work.
• Parameters can be sent in four ways — a query string (?chat_id=1&text=hi), application/x-www-form-urlencoded, application/json, and multipart/form-data when uploading files. You can mix them.
• Object parameters (reply_markup, commands, allowed_updates) go in as objects and arrays in a JSON body, and as JSON strings in forms and query strings.
• Method names are case-insensitive (sendMessage = sendmessage).
• Request bodies can be up to 12 MB (beyond that, 413).
• File downloads use a separate address, https://pabal.me/file/bot<token>/<file_path> (see getFile).

Responses and errors

Responses are always JSON. On success you get HTTP 200 and result; on failure, an error_code equal to the HTTP status and a human-readable description.

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

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

Pabal doesn't rate-limit requests as a whole yet, but the voice methods have hourly limits and return 429 Too Many Requests: retry after N (Voice calls). Write your code to wait parameters.retry_after seconds and retry when it gets a 429.

Getting updates

Use one of these two approaches. You can't use both at the same time.

getUpdates

POST/bot<token>/getUpdates

Fetches waiting updates (long polling). Returns 409 if a webhook is set.

Returns: Array of Update

setWebhook

POST/bot<token>/setWebhook

Receive updates at an HTTPS address. The details are in the Webhooks page.

Returns: True

deleteWebhook

POST/bot<token>/deleteWebhook

Removes the webhook and goes back to getUpdates. Succeeds even if there's no webhook.

Returns: True

getWebhookInfo

GET/bot<token>/getWebhookInfo

The webhook's status. No parameters. If there's no webhook, url is an empty string.

Returns: WebhookInfo

Methods

getMe

GET/bot<token>/getMe

Use it to check that the token is right. No parameters.

Returns: User — for bots, it also includes can_join_groups (true), can_read_all_group_messages (true), supports_inline_queries (false), can_connect_to_business (false) and has_main_web_app (false).

sendMessage

POST/bot<token>/sendMessage

Returns: the sent Message

To send to a person, that person must have messaged the bot first (403 Forbidden: bot can't initiate conversation with a user). To send to a group, the bot must be a member of that group.

sendPhoto

POST/bot<token>/sendPhoto

Returns: the sent Message (with a new file_id in photo)

sendDocument

POST/bot<token>/sendDocument

Returns: the sent Message (with a new file_id in document)

The type (mime_type) is worked out from the file name's extension. Files sent from the apps can be up to 2 GB, but what a bot uploads or downloads over HTTP is capped at 20 MB, as on Telegram.

sendLocation

POST/bot<token>/sendLocation

Returns: the sent Message (with a Location in location)

sendVenue

POST/bot<token>/sendVenue

Returns: the sent Message (with a Venue in venue, and the same point in location)

Without title or address you get 400 Bad Request: title and address are required.

sendContact

POST/bot<token>/sendContact

Returns: the sent Message (with a Contact in contact)

A contact card sent by a bot never carries user_id, even when the number belongs to a Pabal account — a bot has no contacts, and filling it in would let a bot find out whose number it is by sending one card per number. Without phone_number or first_name you get 400 Bad Request: phone_number and first_name are required.

editMessageLiveLocation

POST/bot<token>/editMessageLiveLocation

Returns: the edited Message

A live location that has already ended — stopped, or its period run out — can neither be moved nor brought back by extending its period (400 Bad Request: message can't be edited). The same goes for a message that isn't a live location.

A move made less than 10 seconds after the last applied one, or of less than 10 m, is skipped and not stored. Stopping, and a change of period or alert radius, always apply. When a move is skipped, the returned Message shows the last applied position, so sending one every few seconds is fine.

stopMessageLiveLocation

POST/bot<token>/stopMessageLiveLocation

Parameters: chat_id, message_id, reply_markup (optional). Stops the live location where it last was. Its period shrinks to the time that actually passed, so every app draws it as finished. If it has already stopped or ended you get 400 Bad Request: message is not modified: …. Returns: the edited Message.

editMessageText

POST/bot<token>/editMessageText

Returns: the edited Message. The change shows in the app right away, and messages edited by people reach the bot as edited_message.

If the text and buttons are exactly the same as before you get 400 Bad Request: message is not modified: …, and trying to edit someone else's message gives 400 Bad Request: message can't be edited.

editMessageCaption

POST/bot<token>/editMessageCaption

Parameters: chat_id, message_id, caption (0–1,024 characters; leave it out to remove the caption), reply_markup. Returns: the edited Message.

editMessageReplyMarkup

POST/bot<token>/editMessageReplyMarkup

Changes only the buttons and leaves the text as it is. Parameters: chat_id, message_id, reply_markup (leave it out to remove the buttons). Returns: the edited Message.

deleteMessage

POST/bot<token>/deleteMessage

Parameters: chat_id, message_id. Deletes the message for both sides of the chat. If the message doesn't exist: 400 Bad Request: message to delete not found. Returns: True.

answerCallbackQuery

POST/bot<token>/answerCallbackQuery

Answers a button someone pressed (CallbackQuery). You can answer within 10 seconds, and only once.

Returns: True. If it's too late or the query was already answered: 400 Bad Request: query is too old and response timeout expired or query ID is invalid.

sendChatAction

POST/bot<token>/sendChatAction

Accepted for compatibility and returns True, but the app doesn't show "typing…" yet.

getChat

GET/bot<token>/getChat?chat_id=…

Parameter: chat_id (a number). For a person, that person; for a group, only groups the bot is a member of. Returns: Chat. If it doesn't exist or can't be seen: 400 Bad Request: chat not found.

getFile

GET/bot<token>/getFile?file_id=…

Gets a download path from the file_id of a received photo. Returns: File. Then download it from this address.

https://pabal.me/file/bot<token>/<file_path>

A file_id is also the right to fetch that photo. If the value is wrong: 400 Bad Request: wrong file identifier/HTTP URL specified.

setMyCommands

POST/bot<token>/setMyCommands

Returns: True. If the menu breaks the rules, nothing is kept: 400 Bad Request: BOT_COMMAND_INVALID (a command), BOT_COMMAND_DESCRIPTION_INVALID (an empty description or one over 256 characters), BOT_COMMANDS_TOO_MUCH (more than 100).

getMyCommands

GET/bot<token>/getMyCommands

Parameter: language_code (optional). Returns: Array of BotCommand.

deleteMyCommands

POST/bot<token>/deleteMyCommands

Parameter: language_code (optional). Empties that list. Returns: True.

logOut · close

On Telegram, these methods are used when moving to a local Bot API server. Pabal has nowhere to move to, so it just accepts them and returns True. To invalidate a token, use BotFather's /revoke.

Objects

Optional next to a field means it may be absent. Other Telegram fields not listed here are never sent by Pabal.

Update

One new update. Contains update_id and one of the fields below.

User

Chat

Message

MessageEntity

The server finds these in the text and adds them automatically. Formatting entities such as bold and italic don't exist yet.

PhotoSize

Document

Location

A live location a person shares arrives again as edited_message each time the server applies a move.

Venue

Contact

File

CallbackQuery

InlineKeyboardMarkup

inline_keyboard: Array of Array of InlineKeyboardButton — the outer array is the rows, and each inner array is the buttons in one row. Up to 100 rows and 100 buttons per message.

InlineKeyboardButton

Other kinds, such as switch_inline_query, web_app, login_url and pay, don't exist yet (400).

ReplyKeyboardMarkup

KeyboardButton

A single string, or an object with text and the optional fields request_contact (send my contact) and request_location (send my location), both Boolean.

ReplyKeyboardRemove

{"remove_keyboard": true} — hides the panel of buttons. selective is optional.

ForceReply

{"force_reply": true} — the app opens the input field ready to reply to this message. selective and input_field_placeholder are optional.

BotCommand

WebhookInfo

Voice calls

These methods exist only in Pabal. A voice bot is a bot that people can call from the app and that an AI voice model answers; these methods configure that model and handle calls. What has to be turned on, how to turn it on and examples are in the Voice bots guide. The methods exist even on servers with voice off, so you can read the settings, but a bot on a server with voice off, or one the operator has not allowed yet, cannot change its settings except to turn things off and delete them (403 VOICE_NOT_AVAILABLE).

setVoiceCallSettings

POST/bot<token>/setVoiceCallSettings

Changes the bot's voice settings. Only what you send changes; everything is checked first and then written at once, or all of it is rejected. 30 times an hour per bot (together with @BotFather).

Returns: True

getVoiceCallSettings

GET/bot<token>/getVoiceCallSettings

No parameters. The current settings; whether the bot can take calls right now (available, unavailable_reason); the server's limits; the lists of voices and languages; where tool queries and transcripts go; and the state of the own key, stream mode and MCP servers. Keys and secrets are never shown, only fingerprints. The fields are listed in Voice bots — Current settings.

Returns: VoiceCallSettings (an object)

endVoiceCall

POST/bot<token>/endVoiceCall

Returns: True. If it is not a live call of this bot, 400 VOICE_CALL_NOT_FOUND.

sendVoiceCallContext

POST/bot<token>/sendVoiceCallContext

Returns: True. Errors: VOICE_CALL_NOT_ACTIVE before the call connects, VOICE_CONTEXT_NOT_SUPPORTED for a stream call, VOICE_CONTEXT_TOO_LONG if the text is too long, and 429 for more than 10 per minute per call.

getVoiceCallUsage

GET/bot<token>/getVoiceCallUsage

Returns: period, from_date, to_date, calls, seconds, missed, refused (busy·budget·unavailable), platform_seconds, own_key_seconds, remaining_seconds_today (bot·owner), and outbound (today·limits) for a bot that has ever turned calling on — day boundaries follow the server's time zone

startVoiceCall

POST/bot<token>/startVoiceCall

The bot calls a person. Only a bot whose owner turned this on in @BotFather and whom the operator reviewed can call, and only people who allowed that bot to call them. The answers and how requests are judged are in Voice bots — Calling.

Returns: {"voice_call_id": "…"} — it only means the request was taken; whether it rang and whether it was answered come as voice_call updates. Refusals: 403 VOICE_OUTBOUND_OFF: <reason>, 403 USER_UNAVAILABLE (always the same body), 429, 503 VOICE_UNAVAILABLE. It cannot be called from a webhook answer.

answerVoiceCallToolQuery

POST/bot<token>/answerVoiceCallToolQuery

Returns: True. The first answer is final. Late answers get 400 TOOL_QUERY_EXPIRED: answered|timeout|cancelled|call_ended|unreachable, an unknown id TOOL_QUERY_ID_INVALID, and refused answers TOOL_RESULT_EMPTY·TOOL_RESULT_INVALID·TOOL_RESULT_TOO_LONG·TOOL_ERROR_TOO_LONG·TOOL_RESULT_REFUSED: <code>. A tool-query POST to a webhook can also be answered in the response body.

setVoiceCallApiKey · deleteVoiceCallApiKey

POST/bot<token>/setVoiceCallApiKey

Returns: True — the key is kept only after passing a test session on the gateway. API_KEY_INVALID, API_KEY_NO_REALTIME_ACCESS, 503 API_KEY_CHECK_UNAVAILABLE (not kept), 403 VOICE_OWN_KEY_NOT_AVAILABLE (this server does not accept own keys). deleteVoiceCallApiKey takes no parameters and always returns True. Neither method can be called with bots.sendCustomRequest, and setVoiceCallApiKey cannot be called in a webhook response either. Details in Own model key.

MCP server methods

Send auth and secrets only in the request body. On a server with MCP off: 403 VOICE_NOT_AVAILABLE: MCP tools are not available on this server. Details in Voice bots — MCP servers.

Receiving voice updates

voice_call, voice_call_tool_query and voice_call_transcript arrive only if asked for by name — list them in allowed_updates of getUpdates or setWebhook. They do not arrive with an empty list, and what happened before you asked is not kept. Tool queries come as separate POSTs if there is a webhook, or at the front of the next getUpdates if getUpdates was called within the last 15 seconds.

VoiceCall

VoiceCall has no field that tells you whether the caller chose to keep the conversation. This is on purpose — that text belongs to the caller and does not go to the bot. That's why, on a server with conversation keeping on, ended waits the same amount for every call that isn't in stream mode, and the number of the message after a call record is at least 31 more than the record's in every call (the numbers are reserved in advance).

VoiceCallToolQuery

VoiceCallTranscript

Arrives only through the HTTP Bot API. The whole call is in the transcript of the ended voice_call.

Stream mode (mode=stream)

In stream mode, the call's audio goes to the bot owner's server instead of Pabal's AI model. Send mode=stream, stream_url=wss://… and stream_secret=… (32–128 printable ASCII characters, only in the request body) to setVoiceCallSettings, and Pabal's gateway connects to that address once (a probe); if that works, stream mode turns on. It needs the bot owner terms and an app build with the stream confirmation sheet. Setup, probe results and an example are in Voice bots — Stream mode.

• Connection: TLS 1.2 or later, a public certificate matching the name in the URL, the subprotocol pabal.voice.v1, no compression, messages up to 64 KiB and text up to 4 KiB, no redirects.
• Signature: 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 is the host of the URL you gave. Check the 300 seconds, each nonce once, byte-by-byte comparison, and that start.call_id equals call (details).
• Audio: text messages are JSON events; binary is PCM16 little-endian, mono, 24 kHz. The caller's audio comes in 20 ms (960-byte) chunks.
• Pabal → bot: start (once) · live (the AI notice has finished) · audio · mark · cleared · buffer_full · stop (→ close 1000).
• Bot → Pabal: ready (within 3 seconds after start, before anything else) · audio (after live) · clear · mark · hangup.

The shape of each message is in the table in Voice bots — Wire format.

Errors from the voice methods

The voice methods' error codes and their meanings are collected in Voice bots — Errors. 403 has the form Forbidden: <code>: <description> (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) — except USER_UNAVAILABLE, which is always exactly Forbidden: USER_UNAVAILABLE, with no description — and going over an hourly limit gives 429 with retry_after.

Differences from the Telegram Bot API

• Kinds of updates: only message, edited_message and callback_query, plus the voice-bot kinds that exist only in Pabal (voice_call, voice_call_tool_query, voice_call_transcript). There are no channel posts, inline queries, payments, polls, membership changes (my_chat_member) and so on.
• Formatting: parse_mode and entities are ignored and text is sent as is. Only commands, mentions, URLs and hashtags are highlighted automatically.
• Kinds of chats: one-to-one and basic groups only. No channels, supergroups or forum topics.
• Media: photos, files (sendDocument), locations, live locations, places and contacts only. No messages that play as video or audio, no stickers, no albums (sendMediaGroup), no polls and no sending by URL. Uploads and downloads over HTTP are capped at 20 MB.
• Locations: a live location's proximity alert (proximity_alert_radius) is only stored, never sent. Moves within 10 seconds or 10 m are skipped, and a contact card sent by a bot carries no user_id.
• Bots in groups: there's no privacy mode, so bots receive every message in the group.
• Queue: unfetched updates are kept in memory, up to the most recent 1,000 per bot, and are lost when the server restarts (Telegram keeps them for 24 hours).
• Webhooks: updates are sent one at a time, in order (max_connections is only stored), self-signed certificates aren't accepted, and there's no restriction on the port.
• IDs: user, message and file IDs are meaningful only within this server. With no channels or supergroups, there are no IDs of the form -100… either.
• Missing methods: anything not in the list above (forwardMessage, copyMessage, sendVideo, sendPoll, getChatMember, banChatMember, answerInlineQuery …) returns 404 Not Found: method not found.