SMeet Bot API

Группы, темы и каналы

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

Установка бота#

Откройте информацию о группе или канале, выберите Боты и добавьте бота по @username. Бот должен принадлежать тому же пространству SMeet. Все участники видят установленных ботов и их разрешения; в текущей модели ролей добавлять, менять и удалять их может только владелец группы.

При установке аккаунт бота становится участником группы, а бот получает событие my_chat_member со статусом member. Удаление отправляет статус left и сразу отменяет все ожидающие и FAILED-события этой группы. Прямое удаление из списка участников действует так же.

Видимость сообщений#

Видеть все новые сообщения (read_all_messages) является отдельной опцией установки. По умолчанию она выключена.

• Когда опция выключена, бот получает сообщение человека, только если оно даёт этому боту команду (@bot_username /help или /help@bot_username), содержит упоминание @bot_username либо является ответом на сообщение бота.
• Когда опция включена, бот получает все новые сообщения людей в группе и её темах, кроме сообщений, явно адресованных другому боту.
• В группе команда называет своего бота. @bot_username /help topics и /help@bot_username topics приходят этому боту как обычный text /help topics, так же как в личном чате. Команда без имени (/help) не приходит ни одному боту, какие бы разрешения у него ни были: иначе в комнате с двумя ботами она будила бы обоих.
• Настройка никогда не открывает старую историю. Сообщения, отправленные до установки или до включения опции, не воспроизводятся.
• Сообщения других ботов и системные события не приходят как обычные события message, поэтому боты не зацикливаются друг на друге.

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

Независимые разрешения#

Разрешения не включают друг друга:

Каждый вызов Bot API повторно проверяет действующие права. Отозванное право даёт GROUP_BOT_PERMISSION_DENIED; удалённая установка считается недоступной, а повтор доставки не возвращает отменённые данные.

Идентификаторы чата и темы#

В событиях группы используется chat.type: "group", канала: "channel". Значение chat.id нужно вернуть как chat_id. У темы собственный идентификатор чата, а также поля group_id и topic_id, поэтому очередь и ответы остаются внутри темы.

{
  "id": "9302",
  "type": "group",
  "group_id": "84",
  "title": "Поддержка",
  "topic_id": "7"
}

В группах работают те же payload сообщений, изменений, удалений, файлов и callback-кнопок, что и в личных чатах. Нажимать кнопки могут текущие участники группы.

Поколение установки#

Групповые и канальные чаты несут installation_generation рядом с access_revision (с версии 1.2.0, возможность access_revisions). Одна установка обслуживает группу и все её темы, поэтому у них общие значения.

• access_revision меняется всякий раз, когда меняется право бота в группе: право отобрали или вернули, группу превратили в канал или обратно (с событием my_chat_member), организация выключила работу ботов, аккаунт бота исключили из пространства.
• installation_generation меняется, только когда бота установили заново после удаления. Настройки и подписки прежней установки не должны сами переходить на новую: спросите владельца ещё раз.

Передавайте их обратно как expected_access_revision и expected_installation_generation; изменение в промежутке даёт 409 ACCESS_REVISION_CONFLICT или 409 INSTALLATION_GENERATION_CONFLICT (Условные запросы). Бот, который публикует в канал по подписке, хранит значения момента, когда владелец её настроил, а не последнего события, поэтому старая подписка останавливается после того, как право отобрали и вернули.

Контекст чата#

getChatContext читает один чат в его нынешнем состоянии вместе с версиями: для группы, темы или канала владельца группы, права установки и installed_at; для личного чата человека и состояние. С user_id метод ещё говорит, известен ли этот человек боту в группе (владелец или тот, от кого бот получал событие после текущей установки), участник ли он и владелец ли.

{
  "chat": {"id": "90012", "type": "group", "group_id": "9001", "title": "Поддержка",
           "topic_id": "31", "access_revision": "184502", "installation_generation": "184499"},
  "space": {"id": "1", "kind": "public"},
  "group": {
    "owner": {"id": "52", "display_name": "SMeet", "username": "smeet_admin", "is_bot": false},
    "permissions": {"read_all_messages": false, "can_send_messages": true, "can_edit_messages": true,
                    "can_delete_messages": false, "can_pin_messages": false,
                    "can_restrict_members": false, "can_post_messages": false},
    "installed_at": "2026-10-01T09:00:00Z"
  },
  "user_check": {"user_id": "5002", "known": true, "is_member": true, "is_owner": false}
}

Он нужен, когда человек в одном чате решает о другом, например владелец настраивает канал из личного чата: прочитайте версии канала до показа подтверждения, сохраните их вместе с подтверждением и передайте с действием. Это чтение без блокировок, и его ответ сразу устаревает; действие делает безопасным условие вызова. Человек, от которого бот ничего не получал, получает "known": false, и больше метод о нём ничего не раскрывает. Ограничение: 5 вызовов в секунду на бота, всплеск до 10.

Действие от имени человека: initiator#

initiator делает изменяющий вызов зависимым от роли человека в группе в момент вызова (возможность initiator_conditions):

{"chat_id": "70051", "text": "Здравствуйте! Мы проверили заявку.",
 "expected_access_revision": "184467",
 "initiator": {"user_id": "5002", "role": "group_member", "chat_id": "90010",
               "expected_installation_generation": "184499"}}

• role равен group_owner (текущий владелец группы) или group_member (участник группы, которого бот там знает). Оба должны быть активными участниками пространства группы.
• chat_id является группой, темой или каналом бота. Если собственный чат вызова в группе, чат инициатора должен быть в той же группе; если вызов идёт в личный чат, подойдёт любая группа бота. expected_installation_generation и expected_access_revision внутри объекта закрепляют установку в этой группе.
• Роль, которая не подтвердилась, даёт 403 INITIATOR_NOT_AUTHORIZED с "field": "initiator.user_id", один и тот же ответ при любой причине, поэтому он ничего не говорит о человеке, которого бот не знает. Незнакомое поле внутри initiator даёт 400 INVALID_REQUEST.

Типичные случаи: ответ оператора helpdesk клиенту, который уходит, только пока оператор состоит в группе поддержки; удаление участника или сообщения по кнопке владельца в карточке модерации, с версиями нарушения и "role": "group_owner".

Каналы#

Для канала используется can_post_messages, а не can_send_messages. Бота никогда не назначают владельцем канала. Для каждой публикации технический автор сохраняется в журнале аудита, а клиенты показывают её по правилам интерфейса канала. Установка бота не раскрывает ему список подписчиков.

Методы модерации#

Во всех изменяющих вызовах нужен Idempotency-Key:

• deleteMessage удаляет сообщение при наличии can_delete_messages; в личном чате бот может удалить только собственное сообщение.
• pinChatMessage и unpinChatMessage требуют can_pin_messages.
• restrictChatMember требует can_restrict_members и удаляет выбранного участника.

Перегрузка и пропуски#

Если бот перестал успевать, SMeet не позволяет одной шумной группе занять всю его очередь. Платформа может перестать добавлять новые групповые сообщения, а затем прислать одно событие delivery_gap с количеством и временным диапазоном пропусков. Тексты пропущенных сообщений в него не входят. Такое событие означает, что нужно восстановить собственное состояние или попросить человека повторить действие; доступ к истории Bot API не выдаёт.