SMeet Bot API
Organisations and permissions
A bot belongs to one space and follows its rules. Organisation administrators decide whether members may create bots and whether bots may run; people decide who may write to them.
One space per bot#
Every bot belongs to exactly one space: the public SMeet space or one organisation. It is the space where the owner opened BotFather to create it, and it never changes.
- The bot's token works only in that space. It cannot reach chats, people or files of any other space.
- The bot talks only to members of its space, and only in private chats started with Start.
- A bot of an organisation does not appear in the public space: people outside the organisation cannot find it.
Two permissions of a space#
Each space has two independent switches for bots:
| Permission | What it allows | Default |
|---|---|---|
| Creating bots | Members of the space may create new bots in it. | Off |
| Running bots | The bots of the space work: they receive updates, send messages, and people can write to them. | Off |
- In an organisation, its owners and administrators change both. In the public space only the platform administrators do.
- A bot needs both: creation to be made, running to work. An organisation that wants bots switches on both.
- Switching creation off stops new bots only. Existing bots keep working.
- On top of the space's permissions the platform has its own switches: for all bots, for creating bots and for webhooks. When the platform switches creation off, BotFather answers that creating bots is not allowed right now.
Switching running off#
Switching running off is a revocation, not a pause. At that moment:
- the Bot API answers
403 SPACE_BOTS_DISABLEDto the programs of every bot in the space; - people in the space see that bots are turned off in this organisation, and their messages to bots are not sent;
- every undelivered update of these bots is cancelled, FAILED updates included. They do not come back when running is switched on again, and they cannot be replayed.
Chats and Start permissions stay. When running is switched on again, people can continue the conversation without pressing Start again, and the bots receive only what happens from then on.
This is different from the platform's technical pause, which keeps every queue intact. Operations compares the two.
Who sees a bot#
| Bot of | Who can open its profile and chat with it |
|---|---|
| The public space | Every signed-in SMeet user. |
| An organisation | Active members of that organisation only. For everyone else the bot looks as if it did not exist. |
A bot is always marked Bot. The Official bot badge is given only by the platform.
Who can talk to a bot#
A person can start and use a bot only while they are an active member of the bot's space; in the public space every account counts.
When someone leaves an organisation or is removed from it:
- their chats with the organisation's bots change to
removed; - updates of those chats that were not yet delivered are cancelled;
- each bot receives
chat_access_changedwith the statusremoved, and can no longer write to that person or download files from their messages.
If the person comes back to the organisation, they press Start again to continue.
The owner#
A bot has one owner: the account that created it. The owner must stay a member of the bot's space.
| What happens to the owner | What happens to the bot |
|---|---|
| Leaves the organisation or is removed from it | The bot stops at once: the Bot API answers 403 BOT_SUSPENDED, getMe shows suspended_by_admin, people see that the bot is unavailable. Its waiting updates are cancelled; FAILED updates stay. Platform support can give the bot back to the same owner. |
| The account is disabled | The same. Switching the account back on does not restart the bot: platform support does that. |
| The account is deleted | The owner's bots are deleted, as if the owner had deleted them. |
Handing a bot over to another owner is not part of version 1. If the bot's own account is removed from the organisation, the bot is suspended in the same way.
Start, Stop and Block#
Only the person decides whether a bot may write to them. The bot's code cannot undo these decisions.
| Action | What happens | Update the bot receives |
|---|---|---|
| Start | The chat with the bot is created on the first Start. SMeet also puts the person's message /start into the chat, or /start <param> when they came by a link with ?start=. | chat_access_changed with started, then the message /start |
Stop (a button, or /stop typed in the chat) | The bot can no longer write to this chat. Its updates from this chat that were not delivered yet are cancelled. The /stop message stays in the history but is not delivered to the bot. | chat_access_changed with stopped |
| Block | The same as Stop, and the bot stays blocked until the person unblocks it. | chat_access_changed with blocked |
| Unblock | Nothing is restored: the person presses Start to talk again. | none |
| Start after Stop | The conversation continues in the same chat. Updates cancelled by the Stop do not come back. Typing /start in a stopped chat works like the button. | chat_access_changed with started, then the message |
After stopped, blocked or removed, every attempt of the bot to write to that chat gets 403 BOT_STOPPED_OR_BLOCKED. A bot that sends notifications should delete the subscriptions of that chat when it receives such an update; python/status_bot.py shows how.
What the platform can do#
Platform administrators review reports about bots and can act on a single bot:
- Suspend it: it stops like a paused bot, and its undelivered updates are cancelled (FAILED ones stay). The owner cannot lift a suspension with
/resume. - Revoke its token, the same as the owner's revoke.
- Switch its webhook off: delivery stops and the queue waits. The owner may switch the bot to long polling but cannot set a webhook again until the platform allows it.
- Give or take the Official bot badge, change the rate limits of the bot or of its owner, change how many bots an owner may have, or close bot creation for an account.
Groups and channels#
In version 1 a bot lives only in private chats. Adding a bot to a group or a topic is refused, whoever tries it. Channels are not supported either.