receiveNotification

Отдаёт самое старое уведомление, которое вы ещё не удалили. Если очередь пуста, ждёт новое до receiveTimeout секунд. Подходит, когда у приложения нет публичного адреса: скрипт, бот за NAT, локальная разработка.

Параметры

Пример запроса

Ждать новое уведомление до 20 секунд:

curl

curl "$GRATIO_URL/waInstance$GRATIO_ID/receiveNotification/$GRATIO_TOKEN?receiveTimeout=20"

Python

import os
import requests

BASE = f"{os.environ['GRATIO_URL']}/waInstance{os.environ['GRATIO_ID']}"
TOKEN = os.environ["GRATIO_TOKEN"]

url = f"{BASE}/receiveNotification/{TOKEN}"
params = {"receiveTimeout": "20"}
response = requests.get(url, params=params, timeout=90)
print(response.status_code, response.json())

Node.js

const { GRATIO_URL, GRATIO_ID, GRATIO_TOKEN } = process.env;
const base = `${GRATIO_URL}/waInstance${GRATIO_ID}`;

const query = new URLSearchParams({ receiveTimeout: "20" });
const url = `${base}/receiveNotification/${GRATIO_TOKEN}?${query}`;
const response = await fetch(url);
console.log(response.status, await response.json());

PHP

<?php
$base = getenv('GRATIO_URL') . '/waInstance' . getenv('GRATIO_ID');
$url = $base . '/receiveNotification/' . getenv('GRATIO_TOKEN');
$url .= '?' . http_build_query(['receiveTimeout' => '20']);

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 90,
]);
$response = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($response);

Тайм-аут HTTP-клиента ставьте больше receiveTimeout: в примерах — 90 секунд.

Пример ответа

Ответ 200 OK:

{
  "receiptId": 41,
  "body": {
    "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": "Здравствуйте! Есть места на субботу?"}
    }
  }
}

За receiveTimeout ничего не пришло — ответ 200 OK с телом null.

Поля ответа

Как работает очередь

• Одно и то же уведомление приходит снова, пока вы его не удалите, — в том числе после перезапуска приложения.
• Следующее уведомление вы получите только после удаления текущего. Порядок — по receiptId.
• Читайте очередь одним процессом: два параллельных опроса одного канала получат одно и то же уведомление.
• Неудалённое уведомление хранится 24 часа, затем истекает и больше не приходит.
• Удаляйте уведомление после того, как обработали его и сохранили результат. Упали посередине — то же уведомление придёт снова.
• Не получается обработать конкретное уведомление (ошибка в вашем коде) — сохраните его у себя и удалите, иначе очередь встанет.
• Сколько уведомлений ждёт — getWebhooksCount.

Цикл приёма

Полный цикл на Python: долгий опрос, обработка, удаление, пауза при сбое сети:

import logging
import os
import time

import requests

BASE = f"{os.environ['GRATIO_URL']}/waInstance{os.environ['GRATIO_ID']}"
TOKEN = os.environ["GRATIO_TOKEN"]


def handle(body: dict) -> None:
    kind = body["typeWebhook"]
    if kind == "incomingMessageReceived":
        print(body["senderData"]["chatId"], body["messageData"]["typeMessage"])
    elif kind == "outgoingMessageStatus":
        print(body["idMessage"], body["status"])


while True:
    try:
        r = requests.get(f"{BASE}/receiveNotification/{TOKEN}", params={"receiveTimeout": 60}, timeout=90)
        r.raise_for_status()
        item = r.json()
    except requests.RequestException as e:
        logging.warning("очередь недоступна: %s", e)
        time.sleep(5)
        continue
    if item is None:
        continue  # за минуту ничего не пришло — спрашиваем снова
    try:
        handle(item["body"])
    except Exception:
        logging.exception("не обработано уведомление %s", item["receiptId"])  # сохраните его у себя
    requests.delete(f"{BASE}/deleteNotification/{TOKEN}/{item['receiptId']}", timeout=30)

Ошибки

Включили вебхук, пока шёл долгий опрос, — опрос сразу отвечает null.

Что дальше

• deleteNotification — удалить обработанное уведомление.
• Вебхук — уведомления сразу на ваш сервер, без опроса.
• Шаг 3. Примите входящие — первый приём по шагам.