SMeet Bot API

Организации и доступ

Бот принадлежит одному пространству и подчиняется его правилам. Администраторы организации решают, могут ли участники создавать ботов и могут ли боты работать; люди решают, кто может им писать.

Одно пространство на бота#

Каждый бот принадлежит ровно одному пространству: публичному пространству SMeet или одной организации. Это пространство, в котором владелец открыл BotFather при создании бота, и оно никогда не меняется.

Токен бота действует только в этом пространстве. Он не даёт доступа к чатам, людям и файлам других пространств.
Бот общается только с участниками своего пространства и только в личных чатах, начатых кнопкой Начать.
Бот организации не появляется в публичном пространстве: люди вне организации не могут его найти.

Два разрешения пространства#

У каждого пространства есть два независимых переключателя для ботов:

Разрешение	Что разрешает	По умолчанию
Создание ботов	Участники пространства могут создавать в нём новых ботов.	Выключено
Работа ботов	Боты пространства работают: получают события, отправляют сообщения, и люди могут им писать.	Выключено

В организации оба переключателя меняют её владельцы и администраторы. В публичном пространстве только администраторы платформы.
Боту нужны оба: создание, чтобы его сделать, и работа, чтобы он действовал. Организация, которой нужны боты, включает оба.
Выключение создания запрещает только новых ботов. Существующие боты продолжают работать.
Поверх разрешений пространства у платформы есть свои переключатели: для всех ботов, для создания ботов и для webhook. Если платформа выключила создание, BotFather отвечает, что создавать ботов сейчас нельзя.

Выключение работы ботов#

Выключение работы ботов означает отзыв разрешения, а не паузу. В этот момент:

Bot API отвечает 403 SPACE_BOTS_DISABLED программам всех ботов пространства;
люди в пространстве видят, что боты в этой организации выключены, и их сообщения ботам не отправляются;
все недоставленные события этих ботов отменяются, включая события в FAILED. Они не вернутся, когда работу включат снова, и повторить их нельзя.

Чаты и разрешения Start сохраняются. Когда работу снова включают, люди могут продолжить разговор без повторного нажатия «Начать», а боты получают только то, что происходит с этого момента.

Это отличается от технической паузы платформы, при которой все очереди сохраняются целиком. Сравнение в разделе Эксплуатация.

Кто видит бота#

Бот	Кто может открыть его профиль и писать ему
Публичного пространства	Любой вошедший пользователь SMeet.
Организации	Только активные участники этой организации. Для остальных бот выглядит так, будто его нет.

Бот всегда помечен как Бот. Знак Официальный бот выдаёт только платформа.

Кто может общаться с ботом#

Человек может запустить бота и пользоваться им, только пока он активный участник пространства бота; в публичном пространстве подходит любой аккаунт.

Когда человек выходит из организации или его исключают:

его чаты с ботами организации переходят в статус removed;
ещё не доставленные события этих чатов отменяются;
каждый бот получает chat_access_changed со статусом removed и больше не может писать этому человеку и скачивать файлы из его сообщений.

Если человек вернётся в организацию, чтобы продолжить, он снова нажимает Начать.

Владелец#

У бота один владелец: аккаунт, который его создал. Владелец должен оставаться участником пространства бота.

Что происходит с владельцем	Что происходит с ботом
Выходит из организации или его исключают	Бот сразу останавливается: Bot API отвечает `403 BOT_SUSPENDED`, getMe показывает `suspended_by_admin`, люди видят, что бот недоступен. Ожидающие события отменяются; события в FAILED остаются. Вернуть бота тому же владельцу может поддержка платформы.
Аккаунт отключён	То же самое. Повторное включение аккаунта бота не запускает: это делает поддержка платформы.
Аккаунт удалён	Боты владельца удаляются так, будто их удалил сам владелец.

Передача бота другому владельцу не входит в версию 1. Если из организации исключают сам аккаунт бота, бот приостанавливается так же.

Start, Stop и блокировка#

Только человек решает, может ли бот ему писать. Код бота не может отменить эти решения.

Действие	Что происходит	Какое событие получает бот
Начать	Чат с ботом создаётся при первом нажатии. SMeet также добавляет в чат сообщение человека `/start` или `/start <param>`, если человек пришёл по ссылке с `?start=`.	`chat_access_changed` со `started`, затем `message` с `/start`
Остановить (кнопка или `/stop` в чате)	Бот больше не может писать в этот чат. Ещё не доставленные события этого чата отменяются. Сообщение `/stop` остаётся в истории, но боту не доставляется.	`chat_access_changed` со `stopped`
Заблокировать	То же, что остановка, и бот остаётся заблокированным, пока человек его не разблокирует.	`chat_access_changed` с `blocked`
Разблокировать	Ничего не восстанавливается: чтобы снова общаться, человек нажимает «Начать».	нет
Начать после остановки	Разговор продолжается в том же чате. События, отменённые остановкой, не возвращаются. Сообщение `/start` в остановленном чате работает как кнопка.	`chat_access_changed` со `started`, затем `message`

После stopped, blocked или removed любая попытка бота написать в этот чат получает 403 BOT_STOPPED_OR_BLOCKED. Бот, который рассылает уведомления, должен удалить подписки этого чата, как только получит такое событие; пример в python/status_bot.py.

Что может платформа#

Администраторы платформы рассматривают жалобы на ботов и могут действовать в отношении отдельного бота:

Приостановить его: он останавливается как бот на паузе, а его недоставленные события отменяются (события в FAILED остаются). Владелец не может снять такую приостановку командой /resume.
Отозвать токен, так же как это делает владелец.
Выключить webhook: доставка останавливается, очередь ждёт. Владелец может перевести бота на long polling, но не может снова включить webhook, пока платформа этого не разрешит.
Выдать или снять знак Официальный бот, изменить ограничения частоты для бота или его владельца, изменить число ботов, которое может быть у владельца, или закрыть создание ботов для аккаунта.

Группы и каналы#

В версии 1 бот живёт только в личных чатах. Добавить бота в группу или тему нельзя, кто бы ни пытался. Каналы тоже не поддерживаются.