Входящие

Всё, что происходит в чатах бота, приходит как Update: новое сообщение, правка, реакция, нажатие кнопки. О своих сообщениях бот не получает событий.

Входящие ждут в очереди в томе бота, пока вы их не подтвердите. Получать их можно двумя способами: long-poll (по умолчанию) или webhook.

Типы событий

type	Поле	Когда
message	message	Новое сообщение: текст, файл (содержимое — GET …/file), опрос.
edited	message	Собеседник изменил своё сообщение.
deleted	deleted	Сообщение удалено у всех.
reaction	reaction	Поставлена реакция; пустой emoji — убрана.
poll	message	Изменились голоса опроса или он закрыт.
chat	chat	Новый чат, запрос на переписку, приглашение в группу; сменились название, состав или таймер исчезающих сообщений.
notice	notice	Системная строка чата, см. коды.
expired	expired	Исчезающие сообщения стёрты по сроку (массив id).
button	button	Нажата кнопка с data. См. кнопки.

Команды — обычные события message, текст которых начинается с /.

Long-poll

GET /v1/updates?offset=<id последнего + 1>&timeout=30&limit=100

• timeout — ждать до стольких секунд (не больше 60), если очередь пуста.
• offset — подтверждает и удаляет все события с меньшим id. Передавайте id последнего обработанного плюс один.
• limit — не больше стольких событий (1–100, по умолчанию 100).

Ответ — JSON-массив, возможно пустой. Если вы упали до подтверждения, те же события придут снова: делайте обработку идемпотентной по id.

Webhook

Задайте WEBHOOK_URL (и WEBHOOK_SECRET), и gateway будет отправлять каждое событие POST-ом, по одному Update в запросе, строго по порядку. GET /v1/updates тогда отвечает 409.

• Ответ 2xx — доставлено.
• Иначе или без ответа — повтор через 1 с, 2 с, 4 с … до 5 минут между попытками. Следующее событие ждёт, пока не доставлено это.
• Заголовок X-Mailbees-Signature — sha256=<hex HMAC-SHA256 тела ключом WEBHOOK_SECRET>. Проверяйте его, прежде чем верить телу.

Python

import hashlib, hmac

def verify(body: bytes, header: str, secret: str) -> bool:
    want = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(want, header or "")

Node.js

import { createHmac, timingSafeEqual } from 'node:crypto'

function verify(body, header, secret) {
  const want = Buffer.from('sha256=' + createHmac('sha256', secret).update(body).digest('hex'))
  const got = Buffer.from(header ?? '')
  return got.length === want.length && timingSafeEqual(got, want)
}

Go

func verify(body []byte, header, secret string) bool {
	m := hmac.New(sha256.New, []byte(secret))
	m.Write(body)
	return hmac.Equal([]byte(header), []byte("sha256="+hex.EncodeToString(m.Sum(nil))))
}

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

Отметки о прочтении

Пока бот не отметил сообщения прочитанными, собеседник видит «доставлено». Отмечайте через POST /v1/chats/{chat}/read. С этого же момента для бота начинается отсчёт исчезающих сообщений.