Hidesay Bot API (1.0.0)

The bot's own card as the server holds it, plus the limits this server enforces. This works while the bot is paused, so a programme can find out why nothing else does.

Returns the updates waiting for the bot, oldest first, up to limit. With timeout the call hangs until something arrives or the clock runs out, and answers an empty list on the clock.

offset confirms: every update with an updateId below it is deleted and never shown again. Send the highest updateId you handled plus one. Without offset you get everything still in the queue, which is what a bot asks on its very first call.

Only one poll per bot at a time. A second call ends the first one at once with an empty answer, so two copies of the same programme polling one bot will starve each other: run one.

Not available while a webhook is set: delete the webhook first.

Works while paused.

From now on every update is POSTed as JSON to url, one update per request, in order, with the header User-Agent: Hidesay-Bot-Api/1. If you give a secret, every delivery carries it in the header X-Hidesay-Bot-Api-Secret-Token: check it and refuse anything without it.

Answer with any 2xx within 10 seconds and the update is considered delivered. Anything else, a timeout or a redirect counts as a failure: the server backs off (one second, then doubling, up to an hour) and tries that same update again, so delivery is at least once and never out of order. After ten failures in a row the owner is told in the app. Updates still queue while the webhook is failing and are kept for 72 hours.

The URL must be https, carry no credentials or fragment, and resolve to a public address. Setting a webhook ends any poll in progress; GET /updates refuses while one is set.

Back to polling. Updates that queued while the webhook was set are still there. Works while paused.

Into a chat the bot is in. Send text into a readable chat and armored into an encrypted one; the wrong kind is refused with wrong_body_kind and expected says which. A markup adds rows of buttons under the message. replyTo quotes a message of the same chat (a wrong id is silently dropped). silent only matters in a channel: the post goes out without a notification.

sendId makes the call safe to repeat: a UUID of your choosing, and a second call with the same one hands back the message already written instead of writing it twice. Use it whenever you retry after a timeout.

In an encrypted chat, seal the message to every key GET /chats/{id}/keys returns and to the bot's own key, sign it with the bot's key, and send the armoured result.

New words, new buttons, or both. Only the bot's own ordinary messages, at any age: a scoreboard that changes for a week is the normal use. Service notices the bot caused ("left the group") are not its to edit. Leave markup out to keep the buttons, send markup: null to remove them. People in the chat see the edit live. Edits are counted against the same numbers as sends, in a window of their own: one a second in a private chat, twenty a minute in a group, and the thirty a second overall is shared.

The bot's own messages anywhere; anybody's in a group or channel where the bot holds the delete messages right. Secret messages and service notices cannot be deleted by a bot. chatId goes in the JSON body or in the query.

When somebody presses a button with callbackData, the bot gets a callback_query update and the button spins on their phone. Answer within 60 seconds: with text a short line flashes over the chat; with alert: true the text is shown in a box they have to dismiss; with url their phone shows the address and offers to open it. An empty answer just stops the spinner. The message itself changes only if you edit it (PATCH /messages/{id}).

Each press is answered once. A second press on the same message while the first is open is the same press.

Its kind, its mode (which body to send), and for a group the bot's own seat. A private chat carries the other person and whether they blocked the bot.

For an encrypted chat: the public keys of everybody in it, ids and keys only, no names. Seal your message to all of them and to the bot's own key. Other bots that only receive what is addressed to them are left out, as they are for the app. A readable chat has no keys to give and answers chat_is_open.

Who is in it and with which seat, as a member in the bot's seat would see it: where the roster is hidden a bot that is not an admin sees the admins only, and a channel that keeps its admins to itself leaves them out. Names and handles only, never phone numbers. memberCount counts the list as returned.

The room is told, the way it would be about a person. A bot cannot leave a private chat; the person can block it.

The same indicator a person's phone sends. It clears on its own after a few seconds or when a message lands; send typing: false to clear it early. Only where the bot may write: a restricted bot, or a channel subscriber, gets 403 forbidden. One goes out per chat every 3 seconds at most; calls in between answer sent: false and show nothing.

Only for somebody the bot shares a chat with; anybody else is user_not_found, whether or not they exist.

For the handle a person types at your bot - "paga @anna", "segui @notizie" - when no message has handed you that id. People, groups and channels share one pool of names, so a handle is held by exactly one of the three and kind says which.

The answer carries id at the top, and the same thing again under user or chat with what little goes with it. username is the name that account or chat actually goes by, which is not always the one you asked with: a person can answer to several handles.

It finds anybody with a public handle, which is no more than the short link already tells a stranger with a browser (hidesay.me/anna). The id on its own grants nothing: sending still needs the bot to be in the chat, and a key still needs a chat in common. Out of reach: a chat with no public name (a private group is not in the pool at all), an account that has been closed, and the server's own service account.

Harder limit than the rest of the API: 60 a minute, and a handle nobody holds counts as five, so about a dozen blind guesses spend the minute. Over it you get 429 flood_wait with retryAfter.

Every scope with its commands, or one scope's list when scope is given.

The whole list of that scope, replaced. Up to 100 commands; a command is 1 to 32 lowercase letters, digits and underscores (a leading slash is dropped), its description 1 to 256 characters. Duplicates are folded to the first.

Scopes resolve the way Telegram's do, narrowest first: in a private chat private then default; in a group chat:<id>, then groupAdmins for administrators, then groups, then default. An empty scope does not hide a wider one. The owner can edit the same lists in the console; whichever wrote last wins.

Turns the bot protected: from now on its private chats are end-to-end encrypted, people's phones seal every message to this key, and the bot must send armored into those chats. Calling it again with a new key is a rotation; every phone learns the new fingerprint at once.

There is no way to remove the key from the API on purpose: downgrading a bot from protected to open is a decision for its owner, in the console.

For a programme that notices its token leaked. Nothing works again, this call included, until the owner issues a new token in the console; the owner is told at once. Works while paused.

One update per request, in order. Answer any 2xx within 10 seconds. The header X-Hidesay-Bot-Api-Secret-Token carries the secret you set, if any; User-Agent is Hidesay-Bot-Api/1. Deliveries are at least once: a slow 2xx can be retried, so treat updateId as the thing that makes a delivery new.