Перейти к основному содержанию
GOWA отсылает JSON документ на ваш URL для каждого события WhatsApp, которое он получает: сообщения, квитанции, реакции, редактирование, удаление, набор показателей, изменение группы, ярлыки, рассылка и звонки. Конечная дата регистрации веб-хука отсутствует. Настройте веб-хуки при запуске или на каждое устройство через /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 с:
Индикатор присутствия по умолчанию заканчивается отметкой устройства недоступным, что останавливает обновление контактного присутствия. Отметьте устройство доступным для подавления уведомлений WhatsApp во время запуска. Аккаунт для этого трейд-офф перед включением непрерывного отслеживания.
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 в локальном хранилище. См. Получение сообщений.