SMeet Bot API

Управление ботом

Всё, что владелец делает с ботом, происходит в SMeet BotFather или на экранах «Мои боты» в приложении. Программа бота не может изменить свои настройки, токен или режим доставки.

Где управлять ботом#

• SMeet BotFather работает как чат. Он создаёт ботов, показывает их список, меняет имя, описание и меню команд. Там же бота можно приостановить, возобновить, отозвать его токен и удалить.
• Экран Мои боты находится в приложении: в веб-приложении по адресу messenger.scrile.com/user/bots, в SMeet для iOS и macOS в разделе Настройки → Боты. Там находится всё, что нельзя передавать через чат: токен, подключение (long polling или webhook и возобновление приостановленного webhook), недоставленные события, сброс подключения и экстренный сброс.

BotFather передаёт управление экрану «Мои боты» кнопками, например Получить токен и Подключение; они открывают нужный экран вашего приложения. Карточка бота в BotFather (/mybots, затем бот) показывает статус и два числа: сколько событий ждут в очереди и сколько ошибок доставки. Статусы объяснены в разделе Эксплуатация.

Имя и адрес#

• Адрес выбирается один раз, изменить его потом нельзя.
• Часть адресов зарезервирована для платформы, например smeet_bot, support_bot, help_bot и official_bot.
• Адреса с окончанием _bot бывают только у ботов: люди не могут их занять.
• Адрес удалённого бота не освобождается никогда. Создать с ним бота снова нельзя.

Профиль#

• Описание, до 512 символов. Его читают в профиле бота до нажатия Начать, поэтому напишите, что делает бот и кто за ним стоит. Меняется командой /setdescription.
• О боте, до 120 символов: короткая строка под именем, задаётся на экране «Мои боты».
• Изображение: задаётся на экране «Мои боты».

В профиле также видны автор (имя владельца) и, для бота организации, сама организация. У бота, отмеченного как официальный, есть знак Официальный бот; этот знак выдаёт только платформа.

Команды#

Меню команд появляется, когда человек вводит «/» в чате с ботом. Задать его можно двумя способами:

• В BotFather: /setcommands, затем по одной команде в строке в виде команда - описание, например help - Как пользоваться ботом. Так задаётся список по умолчанию.
• Из программы: setMyCommands с необязательным language_code, прочитать список можно через getMyCommands.

Правила: команда от 1 до 32 символов из a-z, 0-9 и _, без косой черты; описание от 1 до 256 символов; до 100 команд в списке; без повторов. Список для языка (en, ru и так далее) видят люди, у которых приложение на этом языке; остальные видят список по умолчанию. Новый список полностью заменяет прежний список того же языка.

Меню служит подсказкой для людей. Каждую команду бот всё равно получает обычным текстовым сообщением, в том числе команды, которых в меню нет.

Токен#

Токен служит паролем программы бота: sbt1_<key id>_<secret>.

• Он показывается один раз, на защищённом экране токена в «Моих ботах». Команда /token и кнопка Получить токен в BotFather открывают этот экран; в чате токен не появляется никогда.
• SMeet хранит только хэш токена. Потом в «Моих ботах» видны его отпечаток (sbt1_<key id>), дата выпуска и версия, но не сам токен.
• У бота одновременно один токен. Выпуск нового сразу отзывает старый, на всех серверах SMeet одновременно.

Храните токен в переменной окружения или хранилище секретов и передавайте только в заголовке Authorization. Полные правила в разделе Эксплуатация.

Отзыв токена#

/revoke в BotFather (или отзыв в «Моих ботах») прекращает действие текущего токена. BotFather сначала спрашивает: Отозвать токен @support_helper_bot? Программа бота сразу перестанет подключаться, пока вы не выпустите новый токен.

С этого момента каждый вызов со старым токеном получает 401 INVALID_TOKEN, а ожидающий long poll завершается той же ошибкой. Очередь, настройки и чаты остаются как были; чтобы снова подключиться, выпустите новый токен на защищённом экране.

Экстренный сброс#

Используйте его, если токен или секрет webhook могли утечь. Одно действие на экране «Мои боты»:

• выпускает новый токен и показывает его один раз; старый сразу перестаёт работать;
• забирает аренду long polling, чтобы программа со старым токеном ничего не могла подтвердить;
• в режиме webhook создаёт ещё и новый секрет подписи и показывает его один раз.

Впишите новый токен (и новый секрет) в настройки программы и перезапустите её. В режиме webhook ваш endpoint до этого отклоняет доставки с новой подписью, и доставка приостанавливается; после перезапуска нажмите Возобновить доставку (Endpoint на паузе).

Подключение и доставка#

Способ получения событий владелец выбирает на экране Подключение в «Моих ботах»: long polling (по умолчанию) или webhook с HTTPS-адресом. При переключении нужно решить, что делать с ожидающими событиями: сохранить их для нового режима (KEEP) или сбросить (DROP). Программа бота не может сменить режим своим токеном. Переключение подробно описано в разделе Получение событий.

На том же экране есть:

• состояние webhook. Если доставка на паузе, потому что endpoint дал ответ, который можете исправить только вы, экран называет причину, а кнопка Возобновить доставку отправляет ожидающие события, когда вы это исправили (Endpoint на паузе). Повторное сохранение webhook тоже возобновляет доставку, с новым секретом. Пока circuit breaker открыт, экран позволяет запросить следующую пробу сразу;
• Недоставленные события, которые не удалось доставить или обработать, с кнопками Повторить выбранные и Пропустить выбранные (FAILED и повтор);
• Сбросить подключение для программы long polling, которая упала, удерживая аренду (Эксплуатация).

Когда доставка через webhook приостанавливается или событие webhook уходит в FAILED, SMeet BotFather пишет вам в свой чат в пространстве бота, не чаще раза в час для одного бота и одного вида уведомления, с кнопкой Подключение, которая открывает этот экран (Уведомления владельцу). Если вы ни разу не открывали BotFather в этом пространстве, сообщения не будет, а то же состояние покажет карточка бота в «Моих ботах».

Пауза и возобновление#

/pause останавливает бота, ничего не удаляя. BotFather подтверждает: @support_helper_bot приостановлен. Сообщения ему не принимаются, пока вы не возобновите работу.

Пока бот на паузе:

• люди не могут писать ему и нажимать его кнопки; приложение сообщает, что бот недоступен;
• Bot API отвечает 403 BOT_SUSPENDED на getUpdates, sendMessage и другие методы данных; getMe продолжает работать и показывает "status": "paused_by_owner";
• события, которые уже в очереди, сохраняются и доставляются после /resume, если не вышел 7-дневный срок хранения.

/resume снимает только вашу собственную паузу. Приостановку платформой снимает платформа.

Удаление бота#

/deletebot просит подтвердить удаление, отправив адрес бота. Удаление нельзя отменить:

• токен сразу отзывается;
• все ожидающие события и все события в FAILED отменяются;
• аккаунт бота закрывается, а его адрес остаётся занятым навсегда;
• чаты с ботом остаются в истории у людей, но его кнопки больше не работают.

Ограничения для владельцев#

• До 5 ботов на человека, если платформа не разрешила аккаунту другое число. Учитываются активные, приостановленные и заблокированные платформой боты; удалённые не учитываются.
• Подтверждённый адрес e-mail и членство в пространстве, где создаётся бот.
• Платформа может изменить ограничения частоты для отдельного бота или для всех ботов одного владельца и может закрыть создание ботов для аккаунта.

Команды SMeet BotFather#

• Если бот у вас один, команды, которым нужен бот, работают с ним сразу; если ботов несколько, BotFather покажет по кнопке на каждого.
• BotFather отвечает на русском или английском. Он следует языку, на котором вы пишете, а кнопка English или Русский переключает язык явно.
• Шаг, брошенный на 30 минут, начинается заново: BotFather забывает наполовину введённое имя и ждёт новую команду.
• BotFather работает в каждом пространстве, где вам разрешено создавать ботов, и показывает только ботов текущего пространства.