Commands and buttons

Description and commands

The bot's description and commands live in its encrypted profile and reach people's apps together with the name and avatar.

PATCH /v1/me
{"about": "Weather forecasts. Send /weather <city>."}

PUT /v1/me/commands
{"commands": [
  {"name": "start", "description": "What this bot does"},
  {"name": "weather", "description": "Forecast for a city", "args": "<city>"}
]}

• Up to 100 commands. name matches [a-z0-9_]{1,32}, description is up to 256 characters, args (a hint shown in the input field) up to 32.
• about is up to 512 characters.
• {"commands": []} removes the list.

How the apps show it:

• An empty chat with a bot shows the description, a Start button (sends /start) and a note that the bot's owner sees the conversation.
• The / Menu button next to the input field, or / typed in an empty field, opens the list of commands, filtered by what follows the slash.
• A command without args is sent when tapped; one with args is put into the field with the hint in grey.
• In a group the menu shows the commands of every bot in it; a command is sent with a mention of the bot.

A command arrives as an ordinary message update with text like /weather Tbilisi. In a group it carries a mention of the bot in mentions.

Buttons

A bot can attach up to six buttons to its message: up to 3 rows of up to 2.

POST /v1/chats/{chat}/messages
{
  "text": "Deploy v1.4 to production?",
  "buttons": [
    [{"text": "Deploy", "data": "deploy:v1.4"}, {"text": "Cancel", "data": "cancel"}],
    [{"text": "Changelog", "url": "https://example.com/changes/v1.4"}]
  ]
}

• text is up to 64 characters.
• A button has either data (up to 64 bytes, sent back to the bot) or url (https only; the app asks for confirmation and shows the full address).
• Buttons are shown only under messages from accounts marked as bots.

Presses

A press of a data button reaches only the bot; nobody else in the chat sees it:

{
  "id": 42, "type": "button", "chat_id": "g3a…",
  "button": {"message_id": "m9…", "from": {"id": "u7f…", "name": "Anna"},
             "data": "deploy:v1.4", "press_id": "p1…"}
}

The app spins the pressed button and disables the others until the bot reacts. Without a reaction in 10 seconds it shows "The bot did not answer" and enables the buttons again. React in any way, or several at once:

• edit the message — PATCH …/messages/{msg} with new text and/or buttons ([] removes them). Messages with buttons can be edited without a time limit; everyone in the chat sees the result;
• send a new message, possibly with reply_to;
• answer the press with a short toast only the presser sees:

POST /v1/presses/{press_id}/answer
{"text": "Deploying…"}

The answer is up to 200 characters and must come within a minute of the press.

In a group any member can press a button, and all see the outcome through the edit.