/devices/{device_id}/webhook.
Как работает доставка
Каждый целевой URL доставляется самостоятельно, с собственным секретом и извлечением.Настроить
--webhook, --webhook-secret, --webhook-events, --webhook-ignore-jids, --webhook-insecure-skip-verify, и --webhook-all-device-receipts.
Явно задайте закрытый ключ подписи. Если ключ не задан или используется старое опубликованное значение secret, GOWA генерирует случайный ключ, который меняется при перезапуске, и записывает предупреждение в журнал. Получателям нужен явно заданный общий ключ, чтобы проверять подписи и после перезапусков. Сертификаты HTTPS проверяются по умолчанию.
События
Имена событий в списке allowList не чувствительны к регистру.
Нагрузка
Каждый запрос имеет одинаковый конверт:
Ответы добавляют
replied_to_id и quoted_body. Квитанции используют ids (массив) и receipt_type. События участников группы содержат chat_id, type и jids. В имени группы используется отдельная форма group.info.
sender_display_name появляется только тогда, когда from является непустой строкой. Для другого отправителя GOWA предпочитает сохраненное имя контакта, проталкивание живого события, сохраненное имя проталкивания, а затем имя пользователя JID. Для активного аккаунта, он предпочитает push-имя аккаунта, а затем его JID идентификатор. Прекрасное решение. Старая версия from_name остается именем проталкивающего сообщения события.
Входящие сообщения могут включать в себя is_business: true, verified_name и verified_level когда WhatsApp выдаёт сертификат верифицированного имени. Иначе эти поля отсутствуют. Отсутствие не определяет, является ли отправитель бизнесом, а verified_level - это необработанная верхняя ценность, а не гарантия официального значения.
Медиа
С помощьюWHATSAPP_AUTO_DOWNLOAD_MEDIA=true (по умолчанию), медиа-файлы сохраняются в папке statics/media/, а медиа-поле задерживает путь:
{"path": "...", "caption": "..."}, а сама подпись также содержится в body. Если автоматическое скачивание отключено, поле имеет вид {"url": "https://mmg.whatsapp.net/...", "caption": "..."}; файл можно скачать позже с помощью GET /message/{message_id}/download?phone=<chat>.
Полный каталог полезных нагрузок (опросы, местонахождения, контакты, просмотр одного раза, рефералы объявлений и многое другое) находится в верхней части ссылка на загрузку webhook приложения.
Альбомы и структурированные сообщения
Альбом поступает в виде нескольких событийmessage. Заголовок не содержит тела сообщения и передаёт ожидаемое количество элементов:
album_id: "ALBUM_HEADER_ID". Группировать элементы по этому ID. Заголовок не является носителем для скачивания и не пересылается в Чатвут.
Опросы, голосования, правки и добавленные опции также используют message. Проверяйте структурированный объект poll, а не полагайтесь на body. Опционные хэши являются хешами нижнего регистра hexadecimal SHA-256 с точными именами опций. Существующие подсказки WHATSAPP_WEBHOOK_EVENTS=message получают эти взаимодействия.
Онлайн и оффлайн присутствие
Подпишитесь на каждый отдельный контакт, используя одно и то же устройство, которое принимает события:results.subscribed: true и results.jid. Подписка не переопределяет настройки присутствия вашего устройства. Для непрерывных обновлений запустите GOWA с:
state является available или unavailable. last_seen пропускается, когда неизвестно или скрыто в настройках конфиденциальности контакта. from_lid включен, когда применимо. Ввод и запись остаются отдельными событиями chat_presence и не используйте эту подписку.
Изменение имени группы
name_set_by с LID на телефон JID, когда это возможно, и пропускается, когда WhatsApp не идентифицирует действующего лица. Подписаться на group.info явно если ваш список событий исключает другие события.
Счетчик новостей
newsletter.message представляет счетчики живых сообщений, а не гарантированный новый пост. Записи всегда включают в себя server_id. message_id, type и timestamp пропускаются, когда WhatsApp их не предоставляет. Нулевые или отсутствующие счетчики могут быть опущены.
reaction_counts содержит количество реакций WhatsApp. Использовать обновления по ID рассылки и ID сервера. Не используйте пропущенный счетчик как сброс к нулю.
Ограничения аккаунта и выход
События на устройстве всегда содержатsession_id, поэтому слоты с одним и тем же номером WhatsApp остаются отличимыми. Событие использует конфигурацию webhook слота. Удаленный выход хранит ячейку для восстановления и сообщает о личности перед выходом. Настройки слота webhook могут быть переремонтированы. Эти события не отправляются в Чатвут.
Коды переадресованы без изменений и по причине из whatsmeow. Неизвестные коды все еще поступают. Только коды выхода
403 и 406 не устанавливают точную причину. Временная длительность бана 0 означает, что WhatsApp не дала срока действия. Таймер достижения ограничивает запуск новых чатов и может вызвать ошибку отправки 463.
Проверить подписи
Каждый запрос носитX-Hub-Signature-256: sha256=<hex>, HMAC-SHA256 из raw тела запроса с ключом секрета webhook. Рассчитывает его над полученными байтами перед парсингом JSON.
Поставки и повторы
- Каждая попытка повторится через 10 секунд.
- Любая не-2xx ответ или сетевая ошибка получена. GOWA состоит из 5 попыток, ожидая между ними 1 s, 2 s, 4 и 8 сек. Обработчик событий может остановить доставку до завершения всех попыток.
- После последнего сбоя событие удаляется и регистрируется. Не существует постоянная очередь или временная буква.
- Несколько URL-адресов доставляются самостоятельно.
2xx после принятия события в вашу очередь прочной обработки. Сделайте идеальные обработчики, потому что проверенное событие может прибыть более одного раза.
Квитанции на связанном устройстве
По умолчанию GOWA пересылает подтверждения от контактов только с основных устройств, чтобы сократить число дубликатов. Подтвержденияread и read-self самой текущей учётной записи поступают со всех её устройств. В этих подтверждениях payload.from содержит JID учётной записи, а payload.ids указывает прочитанные входящие сообщения.
Задайте WHATSAPP_WEBHOOK_ALL_DEVICE_RECEIPTS=true или --webhook-all-device-receipts=true, чтобы также получать подтверждения от контактов с привязанных устройств, в том числе когда телефон контакта не в сети. Флаг CLI имеет приоритет над переменной окружения, в том числе при явном значении false.
Этот отказ может генерировать повторяющиеся или устаревшие подтверждения заказа. Примените обновления idempotently на аккаунт, чат и идентификатор сообщения. ID сообщений и JID отправителя сохраняют свою каноническую форму без суффиксов устройства.
Фильтр событий
По типу:WHATSAPP_WEBHOOK_EVENTS=message,message.ack передает только эти события.
В чате или отправители: WHATSAPP_WEBHOOK_IGNORE_JIDS соответствует chat_id, from, chat_lid и from_lid. Записи, начинающиеся с @, являются шаблонами для всего адресного пространства (@g.us, @s.whatsapp.net, @lid); все остальное — точное JID.
@s.whatsapp.net также совпадает с групповыми сообщениями, потому что их from является пользователем JID. Используйте @g.us, чтобы игнорировать группы. Комбинация двух фильтров: событие отправляется только если его тип разрешён и его JID не игнорируется.
Webhooks на устройство
Дайте слот своему собственному вебхуку, секретному списку и списку событий:POST /devices. Прочитайте текущий параметр GET /devices/{device_id}/webhook. Отправьте "webhook_url": "" чтобы очистить его.
Пустое устройство webhook_secret или webhook_events возвращается к соответствующим глобальным настройкам. Храняхранимое устройство webhook_insecure_skip_verify boolean заменяет глобальные настройки TLS. В частности, false сохраняет проверку сертификата включенной, даже если глобальный байпасс включен.
По умолчанию URL на каждую консоль заменяет глобальный слот WHATSAPP_WEBHOOK. С помощью WHATSAPP_WEBHOOK_DEVICE_MERGE_GLOBAL=true он добавлен к глобальным URL: URL-адрес устройства использует секретный и allowlist, глобальные URL-адреса сохраняют глобальные, и присутствующий в обоих случаях URL получает событие один раз. Правила Ignore-JID применяются к обоим.
Тестирование локально
Выделите локальный приемник туннелем (например,ngrok http 8080) и установите WHATSAPP_WEBHOOK URL туннеля. С --debug=true GOWA записывает каждую попытку доставки и неудачу.
Другие способы получения событий
- WebSocket в
/ws?device_id=<id>выкладывает события сопряжения и состояния в рабочие столы. Используйте вебхуки для доставки сообщений. - Опрос:
GET /chatsиGET /chat/{chat_jid}/messagesчитать GOWA в локальном хранилище. См. Получение сообщений.
