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 yet (429 Too Many Requests), but that may come, so 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)

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 a command doesn't follow the rules: 400 Bad Request: BOT_COMMAND_INVALID.

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 three 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

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

Differences from the Telegram Bot API

• Kinds of updates: only message, edited_message and callback_query. 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 only. No documents, videos, audio, stickers or albums, and no sending by URL.
• 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, sendDocument, sendPoll, getChatMember, banChatMember, answerInlineQuery …) returns 404 Not Found: method not found.