Как проходят сообщения и уведомления

Каждое действие в канале порождает уведомление. Если знать, какое уведомление приходит на каждом шаге, интеграция становится предсказуемой: вы знаете, чего ждать и в каком порядке.

Входящее сообщение

Собеседник пишет на номер канала:

Собеседник     Мессенджер        Gratio                       Ваша система
    │ сообщение ──►│                 │                              │
    │              │── событие ─────►│ забирает файлы к себе        │
    │              │                 │ пишет уведомление в очередь  │
    │              │                 │── incomingMessageReceived ──►│ очередь
    │              │                 │                              │ или вебхук
    │              │                 │◄── подтверждение ────────────│

• Уведомление — incomingMessageReceived, вид сообщения — в messageData.typeMessage: текст, цитата, файл, геопозиция и т. д. Все виды — в разделе «Форматы уведомлений», начните с Текст.
• Файлы Gratio скачивает сразу: ссылки мессенджеров временные. В уведомлении — постоянная ссылка downloadUrl.
• Отвечать — на senderData.chatId.

Отправка и статусы

Ваша система            Gratio                         Мессенджер
    │ sendMessage ───────►│ ждёт очереди в темпе канала     │
    │                     │ MAX: отмечает входящие          │
    │                     │ прочитанными ──────────────────►│
    │                     │── сообщение ───────────────────►│
    │◄── 200 {idMessage} ─│                                 │
    │◄── outgoingAPIMessageReceived                         │
    │◄── outgoingMessageStatus: sent                        │
    │                     │◄────────────── доставлено ──────│ только WhatsApp
    │◄── outgoingMessageStatus: delivered                   │
    │                     │◄────────────── прочитано ───────│
    │◄── outgoingMessageStatus: read                        │

• Ответ на запрос приходит, когда мессенджер принял сообщение: отправка синхронная, очереди исходящих нет.
• idMessage из ответа связывает сообщение с его статусами в outgoingMessageStatus.
• Статус только растёт: после read опоздавшее delivered не придёт.

Если связь оборвалась посреди отправки

Ваша система            Gratio                         Мессенджер
    │ sendMessage ───────►│── сообщение ─────────────X     │  связь оборвалась
    │                     │ ждёт до 15 с, повторяет        │
    │◄── 503 outcome_unknown                               │
    │ повтор с тем же                                      │
    │ clientMessageId ───►│ итог по ключу: то же сообщение │
    │◄── 200 {idMessage} ─│                                │
    │                     │                                │
    │   …или Gratio сам найдёт исход в истории чата:       │
    │◄── outgoingMessageStatus: sent  (нашлось)            │
    │◄── outgoingMessageStatus: failed (не нашлось за 10 мин)

Подробно — в статье Надёжная отправка без дублей.

Сообщение с телефона

Сотрудник ответил клиенту прямо с телефона, на котором номер:

Телефон номера    Мессенджер        Gratio                    Ваша система
    │ сообщение ─────►│                 │                           │
    │                 │── событие ─────►│── outgoingMessageReceived►│

Так ваша система видит всю переписку, а не только то, что ушло через API. Отличить сообщения — по виду уведомления или по sendByApi в статусах; см. Свои сообщения.

Правка, удаление, реакция

Приходят тем же incomingMessageReceived (сделал собеседник) или outgoingMessageReceived (сделано с номера). Исходное сообщение — в stanzaId:

Собеседник исправил сообщение 1174…903
    → incomingMessageReceived  typeMessage: editedMessage   stanzaId: 1174…903
Собеседник поставил 👍 на ваше сообщение 1174…912
    → incomingMessageReceived  typeMessage: reactionMessage stanzaId: 1174…912

Подробно — Правка, Удаление, Реакция.

Обрыв связи и догон

Канал:  authorized ──► starting ──────────────► authorized
                         │  связь с мессенджером      │
                         │  восстанавливается         │ догон пропущенного
                         ▼                            ▼
Уведомления:  stateInstanceChanged          пропущенные сообщения
              (starting)                    по порядку времени,
                                            затем живые
                                            syncGap — если дочитать
                                            всё не удалось

• Пропущенное приходит обычными уведомлениями в общем порядке времени, без дублей.
• Если за простой сообщений было слишком много, придёт syncGap — дочитайте эти чаты историей. Так бывает в MAX, Telegram и почте; у WhatsApp этого уведомления нет.
• Если сеанс номера потерян совсем — notAuthorized и stateInstanceChanged: номер нужно привязать заново в кабинете.

Кто получает уведомления

                         ┌──► очередь  receiveNotification   ┐ одна на канал:
 события канала ─────────┤    или вебхук  webhookUrl         ┘ либо то, либо другое
                         │
                         └──► подписки (до 5)  ──► CRM, аналитика, аудит
                              своя очередь, подпись и повторы у каждой

• Очередь и вебхук — это одна лента: пока задан вебхук, receiveNotification отвечает 400 webhook_set.
• Подписка получает копию всех уведомлений и ничего не забирает у основной ленты.

Сравнение и выбор — в статье Как получать уведомления.

Что дальше

• Ответы и ошибки — что делать, если запрос не прошёл.
• Формат уведомления — поля, общие для всех уведомлений.