SMeet Bot API

Справочник API

Справочник после первых разделов собран из машиночитаемого контракта, который можно скачать как openapi.json. Имена методов, поля JSON и коды ошибок одинаковы во всех языках этой документации.

Запросы#

• Базовый адрес: https://messenger.scrile.com/bot-api/v1. Метод вызывается как POST https://messenger.scrile.com/bot-api/v1/<method> с телом в JSON в кодировке UTF-8 и заголовком Content-Type: application/json.
• Методы только для чтения (getMe, getMyCommands, getFile, getDeliveryInfo, getWebhookInfo) принимают и GET с параметрами в строке запроса.
• uploadFile принимает multipart/form-data. Содержимое файла скачивается через GET /files/<file_id>/content.
• Тело запроса может быть не больше 21 МиБ; более крупное отклоняется с 413 PAYLOAD_TOO_LARGE и limit в байтах ещё до чтения.
• Адрес, которому не соответствует ни один метод, отвечает 404 METHOD_NOT_FOUND.

Аутентификация#

Каждый вызов передаёт токен бота в заголовке:

POST /bot-api/v1/getUpdates HTTP/1.1
Host: messenger.scrile.com
Authorization: Bearer sbt1_EXAMPLE_REPLACE_WITH_YOUR_TOKEN
Content-Type: application/json

Отсутствующий, испорченный, неизвестный или отозванный токен, а также токен удалённого бота получают один и тот же ответ: 401 INVALID_TOKEN с заголовком WWW-Authenticate: Bearer. Запрос, который уже был в пути, когда бота удалили, может получить вместо этого 404 BOT_NOT_FOUND; после этого токен тоже не работает. Токен никогда не принимается в URL, и SMeet никуда его не передаёт, в том числе в ваш webhook.

Ответы и ошибки#

Любой ответ приходит в JSON. Успешный:

{"ok": true, "result": {"message_id": "7301", "chat": {"id": "550", "type": "private"}}}

Ошибка приходит с соответствующим HTTP-статусом и в таком виде:

{
  "ok": false,
  "error": {"code": "RATE_LIMITED", "message": "Too many requests; wait retry_after seconds", "retry_after": 2},
  "request_id": "3f1c2a7e-8b1d-4c52-9a55-0c7e1f7a1b90"
}

• error.code стабилен, и именно его проверяет программа. error.message содержит английский текст для людей; не разбирайте его программно.
• retry_after (в секундах) есть, только когда повтор имеет смысл, и тогда то же значение приходит в заголовке Retry-After. SMeet передаёт его с каждым 429 и 503, а также с каждым 409 CONSUMER_CONFLICT и 409 FILE_NOT_READY.
• Некоторые коды добавляют поля в error: field называет неверный параметр при INVALID_REQUEST, confirmed_offset и max_issued_update_id приходят с ошибками offset, reason с FILE_REJECTED, limit (наибольший допустимый размер в байтах) с PAYLOAD_TOO_LARGE.
• request_id, который приходит и в заголовке X-Request-Id, указывает на конкретный запрос. Сообщайте его при обращении в поддержку.
• Прокси перед API отвечает на собственные ограничения в том же виде: 429 RATE_LIMITED с retry_after 1 и 413 PAYLOAD_TOO_LARGE, оба с пустым request_id. 413 от прокси может прийти без limit.

Все коды с HTTP-статусами собраны в таблице кодов ошибок.

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

Все идентификаторы (update_id, chat_id, message_id, epoch, offset) передаются десятичными строками длиной до 20 цифр. Они могут превышать 2^53, поэтому никогда не превращайте их в числа с плавающей точкой; арифметика над ними тоже не нужна, потому что сервер возвращает next_offset с каждым batch. file_id и id нажатия кнопки остаются непрозрачными строками, а event_id является UUID.

Idempotency-Key#

Методы, которые что-то меняют, принимают заголовок Idempotency-Key: от 1 до 128 символов из набора A-Z a-z 0-9 . _ : -.

• Тот же ключ и те же параметры: возвращается результат первого вызова, и ничего не выполняется дважды. Перед ответом SMeet заново проверяет токен и чат, поэтому повтор после того, как пользователь остановил бота, получает BOT_STOPPED_OR_BLOCKED.
• Тот же ключ и другие параметры: 409 IDEMPOTENCY_CONFLICT. Параметры сравниваются как JSON, так что порядок полей и пробелы не важны.
• Ошибка до выполнения действия (FILE_NOT_READY, 429, 503, ошибка проверки параметров) ключ не расходует. Повторите тот же запрос с тем же ключом.
• Повтор, который пришёл, пока первый вызов ещё выполняется, дожидается его не дольше 2 секунд и возвращает его результат; через 2 секунды он получает 503 TEMPORARILY_UNAVAILABLE с retry_after 1.
• Повтор условного запроса с тем же ключом и телом возвращает результат первого успешного выполнения без повторной проверки чата и условий: они были проверены вместе с первым вызовом. Так outbox узнаёт исход в пределах 7 дней даже после Stop. Условный повтор с другим значением условия является другим телом: 409 IDEMPOTENCY_CONFLICT. Отказ, в том числе конфликт, ключ не расходует.
• Ключи принадлежат одному боту и одному методу: один и тот же ключ в sendMessage и в editMessageText считается двумя разными ключами. Ключи uploadFile уникальны в пределах бота. SMeet хранит ключи 7 дней.

Стройте ключ из события, на которое отвечаете, и действия, например <event_id>:reply: тогда повторно доставленное или повторённое владельцем событие даёт тот же ключ, и SMeet возвращает уже отправленный ответ. Ваши собственные побочные эффекты (запись в базе, платёж) требуют такой же защиты на вашей стороне по event_id (Дедупликация).

Возможности сервера#

getMe перечисляет в capabilities, что этот сервер обещает сверх версии 1.1.0. Незнакомые значения пропускайте.

Сервер, который не обещает ничего из этого, отвечает на getMe без capabilities, как версия 1.1.0. Правила для программы:

1. Передавайте условие, только когда его значение есть в capabilities последнего ответа getMe. Сервер без этой возможности условие не проверяет: старый сервер молча пропускает параметр и выполняет действие без условия, а сервер 1.2.0 с выключенными условиями отклоняет вызов с 400 INVALID_REQUEST и именем параметра в field и действие не выполняет.
2. Вызывайте getMe при запуске и не реже раза в 5 минут; сразу после 404 METHOD_NOT_FOUND от getChatContext или setMyConditionsMode, после ответа из правила 3 и после события из правила 5.
3. Каждый успешный ответ сервера 1.2.0 на sendMessage, sendPhoto, sendDocument, editMessageText, deleteMessage, pinChatMessage, unpinChatMessage и restrictChatMember содержит result.chat.access_revision, в том числе ответ на повтор по ключу. Если его нет, условия не проверялись: остановите действия, которые от них зависят, и сообщите оператору.
4. После любого периода без нужной возможности (откат сервера, платформа выключила условия) считайте все сохранённые версии недействительными: старый код мог менять доступ и сообщения, не выдавая новых версий.
5. Свежее событие с chat, но без chat.access_revision, когда access_revisions есть в списке, означает откат сервера: сразу вызовите getMe и примените правило 4. Свежим считается событие с date позже момента, когда вы впервые увидели возможность, с запасом на расхождение часов. Повторы из FAILED и события без chat таким признаком не являются.

Условные запросы#

Изменяющий вызов может нести условия. Сервер проверяет их и выполняет действие в одной транзакции: Stop, новая установка или правка в тот же момент либо ждут вызова, либо уже произошли, и вызов их видит. Предварительная проверка через getChatContext этого не даёт, потому что её ответ сразу устаревает.

• Условие, которого метод не принимает, expected_installation_generation в личном чате, незнакомое поле, имя которого начинается с expected_, и незнакомое поле внутри initiator получают 400 INVALID_REQUEST с field: опечатка в имени условия никогда не превращает вызов в безусловный. answerCallbackQuery, rejectUpdate и setMyCommands условий не принимают.
• Значение является строкой от 1 до 64 символов и сравнивается с сохранённым как строка; null равносилен отсутствию параметра. Значение, которое не строка, получает 400 INVALID_REQUEST.
• Берите каждое значение из события, по которому принято решение, и передавайте его дальше без изменений. Никогда не обновляйте его из более позднего события, результата или getChatContext: так действие ожило бы после Stop и Start или после новой установки бота. Нажатие кнопки несёт версии момента нажатия; если нажатие исполняет решение, принятое при создании карточки, храните вместе с карточкой версии того события (Версии в событиях).

Текущих значений ошибки не содержат, чтобы ни одна библиотека не подставила их в старое задание. После Stop условная отправка получает 403 BOT_STOPPED_OR_BLOCKED, после Stop и нового Start 409 ACCESS_REVISION_CONFLICT; оба ответа окончательны для задания. Ограничение частоты проверяется до блокировок, поэтому 429 может прийти раньше, а повтор после retry_after получит конфликт. Изменяющий вызов ждёт одновременного отзыва не дольше 2 секунд, затем отвечает 503 TEMPORARILY_UNAVAILABLE с retry_after 1; ничего не выполнено, и тот же ключ можно безопасно повторить.

POST /bot-api/v1/deleteMessage HTTP/1.1
Host: messenger.scrile.com
Authorization: Bearer sbt1_EXAMPLE_REPLACE_WITH_YOUR_TOKEN
Idempotency-Key: 0b7c9a52-51f4-4c55-9a55-7e1f0c7a1b90:delete
Content-Type: application/json

{"chat_id": "90020", "message_id": "880123", "expected_message_revision": "2",
 "expected_installation_generation": "184505", "expected_access_revision": "184510"}

Если человек тем временем исправил сообщение:

{
  "ok": false,
  "error": {"code": "MESSAGE_REVISION_CONFLICT", "message": "The message changed after expected_message_revision",
            "field": "expected_message_revision"},
  "request_id": "5d0e7c1a-2f8b-4d6e-9a31-1c2b3d4e5f60"
}

Строгий режим#

setMyConditionsMode с {"mode": "strict"} заставляет сервер отклонять новый изменяющий вызов без нужных ему условий: 400 INVALID_REQUEST с именем недостающего параметра в field; {"mode": "optional"} выключает режим. Режим виден в getMe.conditions_mode и по умолчанию выключен.

initiator никогда не обязателен. Повтор по ключу вызова, сделанного до включения режима, возвращает его результат. Режим действует, только пока в списке есть strict_conditions: сервер без неё ничего не отклоняет, поэтому продолжайте проверять capabilities (правило 1 выше).

Ограничения#

Запросы сверх ограничения получают 429 RATE_LIMITED с retry_after. Короткий всплеск сверх темпа допускается до числа в последнем столбце.

Другие ограничения: текст до 4096 символов и кнопки, как в разделе Сообщения и кнопки; фото до 10 МиБ, документы до 20 МиБ и 200 МиБ загрузок на бота за сутки UTC (Фото и документы); очередь до 10 000 событий или 50 МиБ на бота (Получение событий). Платформа может задать другие ограничения отдельному боту и другой общий темп для всех ботов одного владельца.

Версии и совместимость#

• Основная версия входит в путь: /bot-api/v1. Изменение, которое может сломать работающую программу, получает новый путь; v1 продолжает работать.
• Внутри v1 SMeet добавляет новое: поля в объектах, типы событий, значения reason и status, коды ошибок. Программа должна пропускать незнакомые поля и типы событий, а незнакомые значения считать «прочими».
• Каждое изменение контракта записывается в истории изменений API. Текущая версия 1.2.0; то, что она добавляет, перечисляет capabilities, поэтому программа отличает сервер с ней от более старого.
• Сам контракт опубликован как openapi.json (OpenAPI 3.1); по нему можно сгенерировать клиент или проверять им свои тесты.

Методы#

Каждый метод вызывается как POST https://messenger.scrile.com/bot-api/v1/<method> с телом в JSON; методы только для чтения принимают и GET с параметрами в строке запроса. Аутентификация: Токен бота, который один раз показывается в «Моих ботах» или в SMeet BotFather. Формат sbt1_<key id>_<secret>; считайте его непрозрачной строкой. SMeet хранит только хэш. Отозванный токен сразу на всех серверах получает 401 INVALID_TOKEN.

getMe#

GET POST /getMeBot

Проверить токен и получить публичный профиль бота.

Результат#

В поле result приходит Bot. Бот.

При ошибке приходит объект ошибки с кодом из таблицы кодов ошибок.

getMyCommands#

GET POST /getMyCommandsBot

Прочитать меню команд.

Параметры#

С GET передавайте их в строке запроса, с POST как поля тела в JSON.

Результат#

В поле result приходит массив BotCommand. Команды.

При ошибке приходит объект ошибки с кодом из таблицы кодов ошибок.

setMyCommands#

POST /setMyCommandsBot

Заменить меню команд, которое пользователь видит после ввода «/».

Заголовки#

Тело запроса (JSON)#

Результат#

В поле result приходит true. Сохранено.

При ошибке приходит объект ошибки с кодом из таблицы кодов ошибок.

setMyConditionsMode#

POST /setMyConditionsModeBot

Включить или выключить строгий режим условий.

В режиме strict новый вызов изменяющего метода без нужных ему условий получает 400 INVALID_REQUEST с именем недостающего параметра: expected_access_revision в личном чате; expected_access_revision и expected_installation_generation в группе, теме или канале, а для deleteMessage ещё expected_message_revision. Повтор по ключу вызова, сделанного до включения, по-прежнему возвращает его результат. Режим виден в getMe.conditions_mode. Доступен, когда capabilities содержит strict_conditions; иначе 404 METHOD_NOT_FOUND.

Заголовки#

Тело запроса (JSON)#

Результат#

В поле result приходит true. Сохранено.

При ошибке приходит объект ошибки с кодом из таблицы кодов ошибок.

getUpdates#

POST /getUpdatesUpdates

Получить ожидающие события через long polling.

Возвращает ожидающие события начиная с подтверждённой позиции. Переданный offset подтверждает все события с update_id < offset; подтверждённые события больше не возвращаются. Неподтверждённые события возвращаются снова при следующем вызове (после потерянного ответа или перезапуска), поэтому программа должна спокойно переносить повторы.

Запрос ждёт до timeout секунд и завершается сразу, как только появляется событие, а не в конце тайм-аута. Пустой ответ по тайм-ауту ничего не меняет.

У бота один активный получатель. Первый вызов называет consumer_id и получает аренду с epoch; следующие вызовы передают те же consumer_id и epoch и продлевают аренду (TTL 60 секунд). Второй одновременный вызов, даже с тем же consumer_id, получает CONSUMER_CONFLICT. Вызов с чужой epoch (аренду с тех пор взял другой получатель, владелец её сбросил или сменил режим) получает новую аренду, но ничего не подтверждает: его offset не учитывается, и неподтверждённые события приходят снова. Если истекла ваша собственная аренда и за это время её никто не взял, следующий вызов получает новую аренду, и его offset по-прежнему подтверждает события.

Правила offset (confirmed_offset означает позицию после подтверждённого префикса, max_issued_update_id означает наибольший когда-либо выданный update_id):

• offset = confirmed_offset принимается всегда (подтверждение без изменений).
• confirmed_offset < offset <= max_issued_update_id + 1 подтверждает префикс.
• offset < confirmed_offset получает 409 CURSOR_BEHIND; в ошибке есть текущий confirmed_offset. Ничего не отправляется повторно.
• offset > max_issued_update_id + 1 получает 400 OFFSET_NOT_ISSUED, если только он не равен next_offset, который сервер выдал для текущей аренды.
• Без offset выдача продолжается с позиции, сохранённой на сервере.

Пример: после выдачи события 42 offset=43 подтверждает его; offset=44 отклоняется; когда 43 уже подтверждён, offset=42 получает CURSOR_BEHIND.

События, которые были отменены, истекли или ушли в FAILED до подтверждения, перечисляются в skipped, и next_offset перепрыгивает через них. Подтверждайте всегда полученным next_offset, после того как весь batch надёжно сохранён.

Тело запроса (JSON)#

Результат#

В поле result приходит GetUpdatesResult. Пачка событий (возможно, пустая).

При ошибке приходит объект ошибки с кодом из таблицы кодов ошибок.

rejectUpdate#

POST /rejectUpdateUpdates

Перевести одно выданное и неподтверждённое событие в FAILED.

Нужен, когда программа не может обработать одно конкретное событие и не хочет, чтобы оно задерживало остальной batch. Событие выходит из активной последовательности, хранит данные до конца исходного срока хранения и появляется в списке FAILED у владельца, где его можно повторить или пропустить. Отклонить можно только событие, которое уже выдано текущей аренде и ещё не подтверждено.

Заголовки#

Тело запроса (JSON)#

Результат#

Событие в статусе FAILED. В поле result приходит объект с такими полями.

При ошибке приходит объект ошибки с кодом из таблицы кодов ошибок.

sendMessage#

POST /sendMessageMessages

Отправить текстовое сообщение в разрешённый личный чат, группу, тему или канал.

Отправитель всегда бот, которому принадлежит токен; параметра sender_id нет. Личный чат должен оставаться запущенным. Для группы или темы нужно can_send_messages, для канала: can_post_messages. Принимает условия expected_access_revision, expected_installation_generation (группы, темы и каналы) и initiator. Кнопке mini_app нужен личный чат бота, у которого есть мини-приложение.

Заголовки#

Тело запроса (JSON)#

Результат#

В поле result приходит Message. Отправленное сообщение.

При ошибке приходит объект ошибки с кодом из таблицы кодов ошибок.

editMessageText#

POST /editMessageTextMessages

Изменить текст и кнопки сообщения, которое отправил этот бот.

Изменять можно только сообщения этого бота. Если reply_markup не передан, после правки у сообщения не будет кнопок. Принимает условия sendMessage и expected_message_revision. Кнопке mini_app нужен личный чат бота, у которого есть мини-приложение, как в sendMessage.

Заголовки#

Тело запроса (JSON)#

Результат#

В поле result приходит Message. Изменённое сообщение.

При ошибке приходит объект ошибки с кодом из таблицы кодов ошибок.

deleteMessage#

POST /deleteMessageMessages

Удалить сообщение.

В личном чате бот может удалить только своё сообщение. В группе, теме или канале установке требуется can_delete_messages. Принимает условия expected_access_revision, expected_installation_generation (группы, темы и каналы), expected_message_revision и initiator.

Заголовки#

Тело запроса (JSON)#

Результат#

Идентификатор удалённого сообщения. В поле result приходит объект с такими полями.

При ошибке приходит объект ошибки с кодом из таблицы кодов ошибок.

pinChatMessage#

POST /pinChatMessageMessages

Закрепить сообщение в группе, теме или канале.

Установке требуется can_pin_messages. Принимает условия expected_access_revision, expected_installation_generation, expected_message_revision и initiator.

Заголовки#

Тело запроса (JSON)#

Результат#

Сообщение закреплено. В поле result приходит объект с такими полями.

При ошибке приходит объект ошибки с кодом из таблицы кодов ошибок.

unpinChatMessage#

POST /unpinChatMessageMessages

Открепить сообщение в группе, теме или канале.

Установке требуется can_pin_messages. Принимает условия expected_access_revision, expected_installation_generation, expected_message_revision и initiator.

Заголовки#

Тело запроса (JSON)#

Результат#

Сообщение откреплено. В поле result приходит объект с такими полями.

При ошибке приходит объект ошибки с кодом из таблицы кодов ошибок.

restrictChatMember#

POST /restrictChatMemberMessages

Удалить участника из группы или канала.

Установке требуется can_restrict_members. Этим методом нельзя удалить владельца группы и самого бота. Принимает условия expected_access_revision, expected_installation_generation и initiator.

Заголовки#

Тело запроса (JSON)#

Результат#

Участник удалён. В поле result приходит объект с такими полями.

При ошибке приходит объект ошибки с кодом из таблицы кодов ошибок.

getChatContext#

GET POST /getChatContextMessages

Прочитать текущее состояние одного чата этого бота вместе с его версиями.

Для личного чата: человек и состояние диалога, в том числе когда он остановлен, заблокирован или человек ушёл из пространства. Для группы, темы или канала: владелец группы, права установки и время установки. С user_id: является ли этот человек человеком этого чата, а в группе: известен ли он боту там, участник ли он и владелец ли. Ответ является снимком и устаревает сразу: действие делает безопасным условие изменяющего вызова, а не чтение перед ним. Доступен, когда capabilities содержит chat_context; иначе 404 METHOD_NOT_FOUND. Не больше 5 вызовов в секунду на бота, всплеск до 10.

Параметры#

С GET передавайте их в строке запроса, с POST как поля тела в JSON.

Результат#

В поле result приходит ChatContext. Чат в его нынешнем состоянии.

При ошибке приходит объект ошибки с кодом из таблицы кодов ошибок.

answerCallbackQuery#

POST /answerCallbackQueryMessages

Подтвердить, что нажатие кнопки обработано.

Убирает у пользователя индикатор ожидания и при желании показывает короткое уведомление. Если на нажатие не ответить за 15 секунд, пользователь увидит «Бот не ответил»; бот всё равно может ответить позже и изменить своё сообщение. На нажатие можно ответить один раз и в течение 1 часа; повтор такого же ответа возвращает тот же результат, а другой второй ответ получает 409 IDEMPOTENCY_CONFLICT.

Заголовки#

Тело запроса (JSON)#

Результат#

В поле result приходит true. Ответ принят.

При ошибке приходит объект ошибки с кодом из таблицы кодов ошибок.

uploadFile#

POST /uploadFileFiles

Загрузить фото или документ, чтобы отправить его позже.

Файл сохраняется в карантин и проверяется. Возвращённый file_id имеет статус scanning; отправить файл можно только после того, как getFile сообщит ready. Ограничения: фото до 10 МиБ (JPEG, PNG, WebP, HEIC), документы до 20 МиБ и суточная квота объёма на бота. Один и тот же Idempotency-Key никогда не создаёт второй файл.

Заголовки#

Тело запроса (multipart/form-data)#

Результат#

В поле result приходит File. Сохранённый файл (обычно в статусе scanning).

При ошибке приходит объект ошибки с кодом из таблицы кодов ошибок.

sendPhoto#

POST /sendPhotoFiles

Отправить готовое фото в чат.

Файл должен иметь вид photo (JPEG, PNG, WebP или HEIC по содержимому). Любой другой готовый файл получает 400 INVALID_REQUEST с field: file_id; отправьте его через sendDocument. Принимает условия sendMessage. Кнопке mini_app нужен личный чат бота, у которого есть мини-приложение, как в sendMessage.

Заголовки#

Тело запроса (JSON)#

Результат#

В поле result приходит Message. Отправленное сообщение.

При ошибке приходит объект ошибки с кодом из таблицы кодов ошибок.

sendDocument#

POST /sendDocumentFiles

Отправить готовый документ в чат.

Принимает условия sendMessage. Кнопке mini_app нужен личный чат бота, у которого есть мини-приложение, как в sendMessage.

Заголовки#

Тело запроса (JSON)#

Результат#

В поле result приходит Message. Отправленное сообщение.

При ошибке приходит объект ошибки с кодом из таблицы кодов ошибок.

getFile#

GET POST /getFileFiles

Прочитать сведения о файле и состояние его обработки.

Работает для файлов, которые загрузил бот, и для вложений полученных им сообщений. Поле download_path есть, только пока файл в статусе ready и доступ к нему сохраняется. Для scanning в ответе есть retry_after.

Параметры#

С GET передавайте их в строке запроса, с POST как поля тела в JSON.

Результат#

В поле result приходит File. Файл.

При ошибке приходит объект ошибки с кодом из таблицы кодов ошибок.

downloadFile#

GET /files/{file_id}/contentFiles

Скачать содержимое готового файла.

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

Параметры#

Параметры пути входят в сам адрес.

Результат#

Ответом служит сам файл, а не JSON. Содержимое файла. Заголовки ответа: Content-Disposition.

При ошибке приходит объект ошибки с кодом из таблицы кодов ошибок.

getDeliveryInfo#

GET POST /getDeliveryInfoDelivery

Прочитать режим доставки, размер очередей и последнюю ошибку.

Секрет webhook никогда не возвращается.

Результат#

В поле result приходит DeliveryInfo. Состояние доставки.

При ошибке приходит объект ошибки с кодом из таблицы кодов ошибок.

getWebhookInfo#

GET POST /getWebhookInfoDelivery

Прочитать состояние webhook (часть getDeliveryInfo).

Результат#

В поле result приходит WebhookInfo. Состояние webhook.

При ошибке приходит объект ошибки с кодом из таблицы кодов ошибок.

Запрос webhook#

POST ваш HTTPS-адрес

SMeet доставляет одно событие на HTTPS-адрес владельца.

Отправляется только в режиме доставки webhook. На бота один запрос в полёте; сетевой тайм-аут 10 секунд; перенаправления не выполняются.

Проверьте X-SMeet-Signature, прежде чем доверять телу: t содержит Unix-время, а v1 содержит HMAC-SHA256 от "<t>.<сырое тело запроса>" в шестнадцатеричном виде строчными буквами, с ключом, равным секрету webhook, который один раз показывается в «Моих ботах». Отклоняйте timestamp, который отличается от ваших часов больше чем на 5 минут. API-токен в webhook не передаётся.

Надёжно сохраните событие (уникальность по event_id) и быстро ответьте любым 2xx; долгую бизнес-логику выполняйте после ответа. 2xx подтверждает приём, а не успех бизнес-операции. Потерянные ответы приводят к повторам с тем же update_id и event_id.

Обработка ответа: 2xx подтверждает. 400, 413 или 422 переводит это событие в FAILED, очередь идёт дальше. 401, 403, 404, 410, сертификат, который не проходит проверку, адрес, куда webhook не отправляются, перенаправление и любой другой неподдерживаемый ответ приостанавливают endpoint, пока владелец не исправит настройку и не возобновит доставку в «Моих ботах» (состояние paused, причина в last_error); в это время ничего не повторяется, попытки событий не расходуются, очередь сохраняется. 429 замедляет доставку с учётом Retry-After. Ошибки DNS и соединения, а также тайм-ауты соединения и TLS-рукопожатия до отправки запроса оставляют событие в ожидании и увеличивают паузу (5 секунд с удвоением до 5 минут). 5xx, 408 и сбои после начала отправки расходуют общий бюджет: 5 попыток или 10 минут на событие, после чего оно уходит в FAILED; три таких события подряд открывают circuit breaker, который перед продолжением делает пробную доставку текущего события.

Заголовки#

Тело#

Объект Update в JSON.

Ваш ответ#

Принято. Любой 2xx обрабатывается одинаково; тело ответа не читается.

Типы событий#

Поле type у Update называет ровно одно поле с данными, которое присутствует в событии. Незнакомые значения нужно пропускать.

Типы#

Простые типы#

Строки с заданным форматом. Поля ссылаются на них по имени.

User#

Только то, что нужно для чата. E-mail, телефон, другие чаты, другие аккаунты и сессии не передаются никогда.

Chat#

Space#

Bot#

BotMiniApp#

Мини-приложение бота в описании getMe.

MiniAppButton#

Открывает мини-приложение бота в приложении SMeet человека, только опубликованную версию.

InlineKeyboardButton#

InlineKeyboardMarkup#

Attachment#

Message#

CallbackQuery#

ChatAccess#

GroupBotPermissions#

MyChatMember#

DeliveryGap#

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

DeletedMessage#

FileStatusChange#

Отправляется, когда проверка закончена: для вложений, полученных ботом (с message_id и chat), и для собственных загрузок бота (без них). Никогда не отправляется в чат, где пользователь остановил бота или из которого вышел. scan_failed не всегда окончателен: файл, который сканер не смог проверить (scanner_unavailable, scanner_outdated, scan_timeout), проверяется снова примерно через час, всего до трёх раундов, и после этого приходит ещё один file_status_changed; в это время getFile снова показывает scanning.

Update#

Присутствует ровно одно поле с данными, его выбирает type:

Правка старого сообщения не новая команда: считайте message_edited исправлением. Версии в данных события относятся к моменту, когда оно произошло, и повтор из FAILED передаёт их без изменений; у событий, записанных до 1.2.0, версий нет.

MiniAppSubmission#

Человек отправил боту форму его мини-приложения и подтвердил это в SMeet. Приложение, среду, человека и чат определяет SMeet; страница передаёт только data. Одна отправка даёт одно событие, сколько бы раз страница ни повторяла запрос.

Lease#

SkipRange#

GetUpdatesResult#

BotCommand#

DeliveryError#

DeliveryInfo#

WebhookInfo#

Initiator#

Человек, по решению которого действует бот, и роль, которая у него должна быть сейчас. Проверяется в родительской группе chat_id вместе с действием; если проверка не прошла, ответ 403 INITIATOR_NOT_AUTHORIZED, одинаковый для «не участник», «не владелец» и «неизвестен боту». Незнакомое поле внутри объекта даёт 400 INVALID_REQUEST.

ChatContext#

Один чат в его нынешнем состоянии. Есть ровно одно из полей private и group.

ChatContextPrivate#

ChatContextGroup#

UserCheck#

File#

Ошибки#

Любая ошибка. Значение каждого кода и HTTP-статус, с которым он приходит, указаны в ErrorCode. Заголовок Retry-After ставится всегда, когда в теле есть retry_after (429, 503, а также 409 CONSUMER_CONFLICT и FILE_NOT_READY).

Заголовки ответа с ошибкой: Retry-After, X-Request-Id.

Объект ошибки#

Любой неудачный вызов отвечает этой обёрткой и соответствующим HTTP-статусом.

Поле error:

Коды ошибок#