SMeet Bot API

Managing your bot

Everything the owner does with a bot happens in SMeet BotFather or on the My bots screens of the app. The bot's program cannot change its own settings, token or delivery mode.

Where you manage a bot#

• SMeet BotFather is a chat. It creates bots, lists them and changes the name, the description and the command menu. It also pauses, resumes, revokes the token and deletes.
• My bots is a screen of the app: in the web app at messenger.scrile.com/user/bots, in SMeet for iOS and macOS under Settings → Bots. It holds everything that must not pass through a chat: the token, the connection (long polling or webhook, and resuming a paused webhook), the failed updates, the connection reset and the emergency reset.

BotFather hands over to My bots with buttons such as Get the token and Connection; they open the matching screen of your own app. The card of a bot in BotFather (/mybots, then the bot) shows its status and two numbers: updates waiting in the queue and delivery errors. The statuses are explained in Operations.

Name and address#

• The address is chosen once and cannot be changed later.
• Some addresses are reserved for the platform, for example smeet_bot, support_bot, help_bot and official_bot.
• Only bots may have addresses that end with _bot: people cannot take them.
• A deleted bot's address is never released. Nobody can create a bot with it again.

Profile#

• Description, up to 512 characters. People read it on the bot's profile before they press Start, so say what the bot does and who runs it. Change it with /setdescription.
• About, up to 120 characters: a short line under the name, set on the My bots screen.
• Picture: set on the My bots screen.

The profile also shows the author (the owner's name) and, for a bot of an organisation, the organisation. A bot marked as official carries an Official bot badge; only the platform gives that badge.

Commands#

The command menu is the list people see when they type "/" in the chat with the bot. It is set in either of two ways:

• In BotFather: /setcommands, then one command per line in the form command - description, for example help - How to use this bot. This sets the default list.
• From the program: setMyCommands with an optional language_code, and getMyCommands to read it back.

Rules: a command is 1 to 32 characters of a-z, 0-9 and _, without the slash; a description is 1 to 256 characters; up to 100 commands per list; no duplicates. A list for a language (en, ru and so on) is shown to people whose app uses that language; everyone else sees the default list. Setting a list replaces the whole previous list of that language.

The menu is a hint for people. The bot still receives every command as an ordinary text message, including commands that are not in the menu.

The token#

The token is the password of the bot's program: sbt1_<key id>_<secret>.

• It is shown once, on the protected token screen of My bots. BotFather's /token and its Get the token button open that screen; the token never appears in a chat.
• SMeet stores only a hash of it. Afterwards My bots shows its fingerprint (sbt1_<key id>), the issue date and the version, never the token itself.
• A bot has one token at a time. Issuing a new one revokes the old one in the same step, on every SMeet server at once.

Keep it in an environment variable or a secret store and send it only in the Authorization header. Operations has the full rules.

Revoking the token#

/revoke in BotFather (or the revoke action in My bots) ends the current token. BotFather asks first: Revoke the token of @support_helper_bot? The bot's program stops connecting at once, until you issue a new token.

From that moment every call with the old token gets 401 INVALID_TOKEN, and a long poll that was waiting ends with the same error. The queue, the settings and the chats stay as they are; issue a new token on the protected screen to connect again.

Emergency reset#

Use it when the token or the webhook secret may have leaked. One action on the My bots screen:

• issues a new token and shows it once; the old one stops working at once;
• takes the long polling lease away, so a program that still holds the old token cannot confirm anything;
• in webhook mode, also creates a new webhook signing secret and shows it once.

Put the new token (and the new secret) into your program's configuration and restart it. In webhook mode your endpoint refuses deliveries signed with the new secret until then, and delivery pauses; after the restart press Resume delivery (A paused endpoint).

Connection and delivery#

The owner chooses how the bot receives updates on the Connection screen of My bots: long polling (the default) or a webhook with an HTTPS address. Switching asks what to do with the updates still waiting: keep them for the new mode (KEEP) or drop them (DROP). A bot's program cannot change the mode with its token. Receiving updates describes the switch in detail.

The same screen shows:

• the state of a webhook. When delivery is paused because your endpoint gave an answer only you can fix, the screen names the cause, and Resume delivery sends the waiting updates once you have fixed it (A paused endpoint). Saving the webhook again resumes delivery too, with a new secret. While the circuit breaker is open, the screen can ask for the next probe at once;
• Failed updates, the updates that could not be delivered or processed, with Retry selected and Skip selected (FAILED updates and replay);
• Reset the connection for a long polling program that died while holding the lease (Operations).

When webhook delivery pauses, or a webhook update goes to FAILED, SMeet BotFather writes to you in its chat in the bot's space, at most once an hour per bot and kind, with a Connection button that opens this screen (Notices to the owner). If you have never opened BotFather in that space, you get no message, and the bot's card in My bots shows the same state.

Pause and resume#

/pause stops the bot without deleting anything. BotFather confirms: @support_helper_bot is paused. Messages to it are refused until you resume it.

While the bot is paused:

• people cannot send it messages or press its buttons; their app says the bot is unavailable;
• the Bot API answers 403 BOT_SUSPENDED to getUpdates, sendMessage and the other data methods; getMe still works and shows "status": "paused_by_owner";
• updates already in the queue are kept and delivered after /resume, as long as they are within the 7-day retention window.

/resume lifts only your own pause. A suspension by the platform is lifted by the platform.

Deleting a bot#

/deletebot asks you to confirm by sending the bot's address. Deletion cannot be undone:

• the token is revoked at once;
• every update still waiting, and every FAILED update, is cancelled;
• the bot's account is closed, and its address stays taken for good;
• chats with the bot stay in people's history, but its buttons no longer work.

Limits for owners#

• Up to 5 bots per person, unless the platform allows an account a different number. Active, paused and suspended bots count; deleted ones do not.
• A confirmed e-mail address, and membership in the space where the bot is created.
• The platform may change the rate limits of a single bot or of all bots of one owner, and may close bot creation for an account.

SMeet BotFather commands#

• When you have one bot, commands that need a bot use it directly; with several, BotFather shows a button per bot.
• BotFather answers in Russian or English. It follows the language you write in, and the English or Русский button switches it.
• A step left unfinished for 30 minutes starts over: BotFather forgets the half-entered name and waits for a new command.
• BotFather works in every space where you may create bots, and lists only the bots of the space you are in.