Формат уведомления

Уведомление — один объект JSON. Он одинаковый в очереди (поле body ответа receiveNotification), в теле вебхука и в доставке подписки. Формат — как у Green API, с полями сверх него: channel, eventId и новые виды уведомлений.

Пример

Мария пишет в личный чат MAX:

{
  "typeWebhook": "incomingMessageReceived",
  "instanceData": {"idInstance": 7100000001, "wid": "79990000001@c.us", "typeInstance": "v3", "channel": "max"},
  "timestamp": 1791823658,
  "idMessage": "117428955282341903",
  "eventId": "msg:8695836:117428955282341903",
  "senderData": {
    "chatId": "8695836", "chatName": "Мария", "chatType": "user",
    "sender": "8695836", "senderName": "Мария", "senderType": "user",
    "senderContactName": "", "senderPhoneNumber": 0
  },
  "messageData": {
    "typeMessage": "textMessage",
    "textMessageData": {"textMessage": "Здравствуйте! Есть места на субботу?"}
  }
}

Общие поля

Все id — строки, даже если выглядят как числа: id сообщений MAX 64-битные и в JavaScript и PHP числом теряют точность. Числа — только idInstance, timestamp и счётчики.

instanceData

Ветвитесь по channel: typeInstance нужен для совместимости с Green API.

Виды уведомлений

senderData

chatId — куда отвечать: передайте его в sendMessage. Как выглядят адреса в каждой площадке — в статье Идентификаторы чатов и сообщений.

В своих сообщениях (outgoingMessageReceived, outgoingAPIMessageReceived) chatId — получатель, sender — аккаунт канала.

messageData

Вид содержимого — в messageData.typeMessage:

У писем рядом с содержимым — emailMessageData: тема, цепочка, адресаты. См. Письмо.

Если сообщение отвечает на другое, в messageData есть quotedMessage — и у файла, и у геопозиции. Сообщение вида, который Gratio не разбирает, и служебные сообщения площадки (закреп, вход в чат) уведомлением не приходят. Изменения состава групп — отдельным groupEvent.

idMessage

У правки, удаления и реакции сообщение, к которому относится событие, — в stanzaId внутри messageData.

eventId

eventId — ключ события в Gratio. Одно событие площадки — одно уведомление с одним eventId. Если ваше приложение может получить уведомление дважды (повтор вебхука после тайм-аута, падение до deleteNotification), храните обработанные ключи и пропускайте повторы.

Разбирать eventId не нужно — сравнивайте строку целиком: внутри адрес чата во внутренней форме, без суффиксов WhatsApp.

У outgoingAPIMessageReceived, outgoingMessageStatus и stateInstanceChanged поля eventId нет. Ключ для них — idMessage, пара idMessage + status или хеш тела: повторная доставка приходит тем же телом.

Как разбирать

• Ветвитесь по typeWebhook, затем по messageData.typeMessage.
• Незнакомый typeWebhook или typeMessage — пропустите и подтвердите уведомление. Gratio добавляет новые виды и поля, старые не меняет.
• Поля, которых у площадки нет, приходят пустыми ("", 0, null) или не приходят вовсе. Не полагайтесь на их наличие.

Пример разбора:

def on_notification(body: dict) -> None:
    kind = body["typeWebhook"]
    if kind in ("incomingMessageReceived", "outgoingMessageReceived", "outgoingAPIMessageReceived"):
        data = body["messageData"]
        handlers = {"textMessage": on_text, "editedMessage": on_edit, "reactionMessage": on_reaction}
        handler = handlers.get(data["typeMessage"])
        if handler is not None:
            handler(body)
    elif kind == "outgoingMessageStatus":
        on_status(body["idMessage"], body["status"])
    # остальные виды — пропустить, уведомление всё равно подтвердить

Что дальше

• Текст — самое частое уведомление целиком.
• Как получать уведомления — очередь, вебхук и подписки.
• Идентификаторы чатов и сообщений — адреса чатов в каждой площадке.