Получение сообщений

Каждое сообщение, которое бот должен получить, становится обновлением. Бот забирает обновления сам (длинный опрос) или получает их на свой адрес (вебхук) — одно из двух.

Длинный опрос

Бот вызывает GET /updates в цикле:

Первый запрос — offset=0&timeout=30.
Если обновления есть, ответ приходит сразу. Если нет — сервер держит запрос до 30 секунд и отвечает, как только обновление появится, или пустым массивом [] по истечении времени.
Обработав обновления, бот передаёт в следующем запросе offset = наибольший полученный update_id + 1. Обновления с меньшими номерами сервер удаляет.

Пока бот не передал offset больше номера обновления, оно приходит в каждом ответе снова: упавший бот после перезапуска получит то, что не успел обработать. Обновления хранятся 24 часа. Номера update_id у бота растут без пропусков в порядке появления сообщений.

Держите один опрос на бота. Клиент HTTP должен ждать ответа дольше timeout: при timeout=30 — не меньше 40 секунд.

Вебхук

После POST /webhook Marx отправляет каждое обновление запросом на заданный адрес:

POST /marx HTTP/1.1
Host: bot.example.org
Content-Type: application/json
User-Agent: marx-bot-webhook
X-Marx-Bot-Secret: Zr4q-8NnYtV2

{"update_id": 7, "chat": {"id": 812, "type": "group", "title": "Дача"}, "message": {…}}

Тело — одно обновление, такое же, как элемент ответа GET /updates.
Сравните X-Marx-Bot-Secret с секретом, заданным в POST /webhook, и отвечайте 403 на чужие запросы.
Ответ 2xx — обновление доставлено и удаляется. Любой другой код, тишина дольше 10 секунд или ошибка соединения — повтор того же обновления через 1 секунду, затем через 2, 4 и так далее, не реже раза в 60 секунд.
Обновления одного бота идут по одному и по порядку: следующее не отправляется, пока не принято предыдущее.
Адрес — только https:// с действительным сертификатом и публичным IP-адресом; перенаправления не выполняются.
Повтор возможен и после того, как бот уже обработал обновление (например, ответ не дошёл), поэтому отвечайте через POST /messages с client_id, построенным из update_id.

DELETE /webhook возвращает бота к длинному опросу; неотправленные обновления остаются и приходят через GET /updates.

Обновление

Поле	Что это
`update_id`	Номер обновления у этого бота
`chat.id`	Номер чата — `chat_id` для ответа
`chat.type`	`direct` или `group`
`chat.title`	Название группы
`message`	Сообщение

Сообщение

Тот же объект, что приложение получает о новом сообщении. Полный пример — в ответе GET /updates. Поля, которые нужны боту:

Поле	Что это
`id`	Номер сообщения — `message_id` для `POST /reactions`
`chat_id`	Номер чата
`sender_id`	Номер аккаунта отправителя
`author`	Отправитель: `id`, `display_name`, `username` (может быть `null`), `avatar_url`, `is_bot`
`type`	`text`, `image`, `video`, `file`, `voice`, `poll` и другие
`body`	Текст сообщения; у опроса — его описание в JSON
`caption`	Подпись к картинке, видео или файлу
`created_at`	Время отправки, ISO 8601 в UTC
`media_url`, `media`, `attachments`	Вложения: адрес и описание файла
`file_name`, `file_size`, `duration_ms`	Имя и размер файла, длительность видео или голосового
`reply_to_message_id`, `quote`	Сообщение, на которое это — ответ, и его цитата
`poll`	Опрос: вопрос, варианты, голоса
`forwarded_from_user_id`, `forwarded_from_chat_id`, `forwarded_from_name`	Откуда переслано

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

Что видит бот

Чат	Что приходит боту
Личный с человеком	Все сообщения человека
Группа	Сообщения, которые начинаются с команды: `/команда` или `/команда@имя_этого_бота` (но не `/команда@другой_бот`); сообщения с упоминанием бота `@имя_бота`; ответы на сообщения этого бота
Канал	Ничего: в канале бот только публикует

Не приходят никогда: собственные сообщения бота, сообщения других ботов, служебные строки чата (вход участника, переименование). Обычную переписку группы бот не видит.

Команды

Команда — сообщение, которое начинается с /: /today, /today@dacha_weather_bot, /today Москва. В группе, где несколько ботов, имя после @ указывает, какому боту она адресована.

Список команд с описаниями приложение показывает в меню чата с ботом. Его задают через PUT /commands или у @marxbot командой /setcommands.

До 100 команд.
Команда — от 1 до 32 символов из a-z, 0-9, _, без /; команды не повторяются.
Описание — не пустое, до 256 символов.

Разбор команды — дело программы бота: в обновлении приходит текст сообщения как есть.