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, ошибка проверки параметров) ключ не расходует. Повторите тот же запрос с тем же ключом.
• Повтор, который пришёл, пока первый вызов ещё выполняется, дожидается его и возвращает его результат.
• Ключи принадлежат одному боту и одному методу: один и тот же ключ в sendMessage и в editMessageText считается двумя разными ключами. Ключи uploadFile уникальны в пределах бота. SMeet хранит ключи 7 дней.

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

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

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

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

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

• Основная версия входит в путь: /bot-api/v1. Изменение, которое может сломать работающую программу, получает новый путь; v1 продолжает работать.
• Внутри v1 SMeet добавляет новое: поля в объектах, типы событий, значения reason и status, коды ошибок. Программа должна пропускать незнакомые поля и типы событий, а незнакомые значения считать «прочими».
• Каждое изменение контракта записывается в истории изменений API.
• Сам контракт опубликован как 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. Сохранено.

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

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 нет. Чат должен быть личным: пользователь нажал в нём «Начать» и не остановил и не заблокировал бота.

Заголовки#

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

Результат#

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

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

editMessageText#

POST /editMessageTextMessages

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

Изменять можно только сообщения этого бота. Если reply_markup не передан, после правки у сообщения не будет кнопок.

Заголовки#

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

Результат#

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

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

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.

Заголовки#

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

Результат#

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

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

sendDocument#

POST /sendDocumentFiles

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

Заголовки#

Тело запроса (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#

InlineKeyboardButton#

InlineKeyboardMarkup#

Attachment#

Message#

CallbackQuery#

ChatAccess#

DeletedMessage#

FileStatusChange#

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

Update#

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

Правка старого сообщения не новая команда: считайте message_edited исправлением.

Lease#

SkipRange#

GetUpdatesResult#

BotCommand#

DeliveryError#

DeliveryInfo#

WebhookInfo#

File#

Ошибки#

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

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

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

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

Поле error:

Коды ошибок#