Всё, что происходит в канале, приходит уведомлением: сообщение собеседника, статус отправленного, правка, реакция, звонок, событие группы, смена состояния канала. Забирать уведомления можно тремя способами.
| Очередь | Вебхук | Подписка | |
|---|---|---|---|
| Как | приложение спрашивает receiveNotification и удаляет обработанное | Gratio шлёт POST на webhookUrl |
Gratio шлёт POST на адрес подписки |
| Сколько на канал | одна | один адрес | до 5 |
| Публичный адрес у приложения | не нужен | нужен | нужен |
| Подлинность | ключ канала в запросе | ваш токен в Authorization: Bearer |
подпись HMAC-SHA256 |
| Порядок | по receiptId |
по одному, по порядку | по одному, по порядку |
| Не приняли | приходит снова, пока не удалите | повторы, через час — в отравленные | повторы, отказы 4xx — в отравленные |
| Хранение неподтверждённых | 24 часа | 24 часа | 24 часа |
| Как у Green API | да | да | нет, только в Gratio |
Очередь и вебхук — одна и та же очередь канала. Пока задан вебхук, receiveNotification отвечает 400 webhook_set. Подписки — отдельные копии ленты: они ничего не забирают у очереди и вебхука.
Очередь: получить, обработать, удалить
Приложение само забирает уведомления и подтверждает обработанные:
Приложение Gratio
│ receiveNotification ──────────────►│ ждёт до receiveTimeout
│◄──────── {"receiptId": 41, "body"} │
│ обработать и сохранить │
│ deleteNotification/41 ────────────►│
│◄────────────── {"result": true} │
│ receiveNotification ──────────────►│ следующее уведомление
Пока уведомление не удалено, оно приходит снова — в том числе после перезапуска приложения.
Вебхук: доставка с повторами
Gratio присылает уведомления сам и повторяет, пока не получит 2xx:
Gratio Ваш сервер
│ POST /gratio/hook уведомление 41 ──────►│
│◄───────────────────── 500 или тайм-аут │
│ через 1 с — снова 41 ───────────────────►│
│◄───────────────────────────────── 200 OK │
│ POST /gratio/hook уведомление 42 ──────►│
Следующее уведомление уходит, только когда принято текущее. Расписание повторов и коды ответа — в статье Вебхук.
Что выбрать
- Очередь — для начала, скриптов, ботов за NAT и локальной разработки. Долгий опрос с
receiveTimeoutдо 60 секунд почти не нагружает ни приложение, ни Gratio. - Вебхук — для сервера с публичным HTTPS-адресом: уведомление приходит сразу, опрашивать не нужно.
- Подписка — когда ту же ленту нужно отдать ещё одной системе (CRM, аналитика, архив), не мешая основному приложению, или когда нужна проверяемая подпись.
Очередь или вебхук — для основного приложения, подписки — для остальных систем.
Какие уведомления приходят
Набор задают флаги setSettings. Все флаги по умолчанию включены ("yes"). Флаги действуют на очередь, вебхук и подписки одинаково.
typeWebhook |
Когда | Флаг | Формат |
|---|---|---|---|
incomingMessageReceived |
сообщение собеседника, его правка, удаление, реакция | incomingWebhook |
Текст и другие |
outgoingMessageReceived |
своё сообщение с телефона или другого устройства; своя правка, удаление, реакция | outgoingMessageWebhook |
Свои сообщения |
outgoingAPIMessageReceived |
сообщение, отправленное через API | outgoingAPIMessageWebhook |
Свои сообщения |
outgoingMessageStatus |
статус отправленного: sent, delivered, read, failed |
outgoingWebhook |
outgoingMessageStatus |
stateInstanceChanged |
канал подключился, переподключается или потерял сеанс | stateWebhook |
stateInstanceChanged |
incomingCall, outgoingCall |
звонок: звонит и итог | incomingCallWebhook |
incomingCall и outgoingCall |
callStateChanged |
ход звонка, который ведёт сервер Gratio | incomingCallWebhook |
callStateChanged |
groupEvent |
состав группы, админы, название, фото, удаление, заявки | groupEventsWebhook |
groupEvent |
syncGap |
после простоя дочитана не вся история | всегда | syncGap |
Общее устройство уведомления — в статье Формат уведомления.
Гарантии
- Простой связи не теряет сообщения. Связь с мессенджером оборвалась — при подключении Gratio дочитывает пропущенное и отдаёт обычными уведомлениями в общем порядке времени. Не дочитал всё — присылает syncGap.
- Одно событие — одно уведомление. Повторную доставку мессенджером, переподключение и догон Gratio отсеивает сам.
- Ваши повторы — ваша защита. Вебхук и подписка повторяют уведомление, если не получили
2xx, даже когда вы его уже обработали. Храните обработанныеeventId— см. Вебхук. - Порядок сохраняется. Очередь отдаёт уведомления по
receiptId, вебхук и подписка — по одному и по порядку. - Отравленное не держит очередь. Уведомление, которое вебхук не принимает час, уходит в отдельный список, очередь идёт дальше. См. getDeadNotifications.
- 24 часа на приём. Неподтверждённое уведомление хранится сутки, затем истекает. Сообщения при этом остаются в истории чата — getChatHistory.
Что дальше
- receiveNotification — забрать уведомление из очереди.
- Вебхук — принимать уведомления на свой сервер.
- subscriptions — отдать ленту второй системе.
- Формат уведомления — из чего состоит уведомление.