WAIXAPI
API и интеграции

Настроить вебхуки

Как передавать сообщения клиентов и статусы доставки на ваш сервер.

4 мин. чтения9 разделов
Настроить вебхукиВойдите в WAIX, чтобы выполнить эти шаги

Подготовьте адрес

Нужен публичный HTTPS URL на стандартном порту 443 с действительным сертификатом. Локальные и частные адреса не принимаются. Перенаправления не выполняются. Для разработки используйте публичный тестовый endpoint с проверкой подписи.

Настройка

  1. В кабинете откройте «Вебхуки» и укажите URL.
  2. Включите «Доставлять события на этот адрес» и отметьте нужные события. Для сообщений с телефона выберите «Отправлено из WhatsApp на телефоне» (message.echo). Для этого номер должен быть подключён с Coexistence.
  3. Сохраните секрет, показанный при первом создании. Он отличается от API-ключа.
  4. Отправьте тестовое событие и проверьте журнал доставок.
  5. Напишите бизнесу с тестового телефона и проверьте реальное событие.

Через API

json
{
  "url": "https://example.com/hooks/waix",
  "events": ["message.received", "message.status.updated"],
  "active": true
}

PUT /webhook с webhooks:write. Один endpoint на организацию. GET /webhook возвращает настройки и последние доставки. POST /webhook/test отправляет тест. POST /webhook/rotate-secret заменяет секрет; DELETE /webhook удаляет endpoint.

Что остаётся в WAIX

Подключение номера WhatsApp, управление шаблонами Meta, API-ключи, отправка сообщений и доставка событий на ваш HTTPS-адрес. Новые сообщения проходят через WAIX без записи их содержимого в базу, очередь заданий или файловое хранилище.

Кабинет скрывает переписки, CRM, записи, рассылки, сценарии, документы и другие функции, которым нужно хранение клиентских данных. Их API тоже недоступно. Публичная онлайн-запись отключается на время действия режима.

Как включить

  • Откройте «Вебхуки» в разделе интеграций. Сохраните активный HTTPS-адрес и включите message.received, message.echo, message.status.updated и whatsapp.event.
  • Отправьте тестовое событие и проверьте, что ваш сервер проверяет подпись, сохраняет событие и отвечает HTTP 2xx.
  • Остановите сценарии и завершите задания в очереди. Отключите остальные каналы и MCP, если они подключены.
  • В блоке «Где хранится переписка» нажмите «Включить без сохранения истории» и подтвердите. Настройка применяется ко всем сотрудникам и ключам этой компании.

Отправка сообщения

Используйте POST /api/v1/messages с Bearer API-ключом и UUID в заголовке Idempotency-Key. В этом режиме запрос отправляется сразу в Meta. Ответ HTTP 200 содержит технический результат, а не копию сообщения. accepted означает принятие Meta; доставку и прочтение проверяйте по вебхукам.

json
{
  "data": {
    "id": "UUID отправки WAIX",
    "status": "accepted",
    "meta_message_id": "wamid.…",
    "error_code": null,
    "history_saved": false
  }
}

Повторите тот же запрос с тем же Idempotency-Key, чтобы получить сохранённый технический результат без повторной отправки. При outcome_unknown или sending не создавайте новый ключ автоматически: первая отправка могла пройти. При failed поле error_code содержит код Meta. GET /api/v1/messages/{id} возвращает только техническую квитанцию.

Поддерживаются текст, шаблоны, интерактивные сообщения и медиа по HTTPS-ссылке или ID Meta. Для ответа используйте reply_to_meta_message_id. Локальные reply_to_message_id и media_object_id недоступны; реакции через локальную историю тоже недоступны.

Входящие события и файлы

Подпись проверяется обычным способом через X-Waix-Signature. События message.received, message.echo и message.status.updated содержат данные сообщения и исходный объект Meta в raw. Другие события приходят как whatsapp.event. message.echo относится к сообщениям из WhatsApp Business App при Coexistence.

WAIX не хранит журнал этих доставок. Ваш обработчик должен быстро сохранить событие и вернуть HTTP 2xx — быстрее чем за 5 секунд. При ошибке WAIX возвращает Meta HTTP 503. Повторы зависят от Meta; собственной сохранённой очереди здесь нет, поэтому при длительном сбое события могут быть потеряны. Удаляйте дубликаты по id события.

Для входящего файла поле media_download содержит путь, метод POST и временный capability. Вызовите этот путь с вашим API-ключом с правом media:read и JSON {"capability":"значение из события"}. Срок разрешения — 24 часа, доступность самого файла зависит от Meta. WAIX передаёт поток файла до 32 МБ без сохранения на диск. Разрешение привязано к вашей компании, номеру и конкретному файлу.

Какие данные всё же сохраняются

  • Данные аккаунта, подключённых бизнес-номеров, ключей, шаблонов, подписки, оплаты и безопасности.
  • Технические квитанции исходящих запросов: ID, Idempotency-Key, защищённый отпечаток запроса, результат и код ошибки. Текста и номера получателя в квитанции нет.
  • История, которая появилась до переключения. Этот режим не удаляет прежние записи и резервные копии. Для удаления нужен отдельный запрос.
  • Обращения в поддержку WAIX: они относятся к обслуживанию вашего аккаунта и не входят в режим передачи клиентской переписки.

Как вернуть обычный кабинет

В разделе «Вебхуки» нажмите «Вернуть функции WAIX». Будущие сообщения снова будут сохраняться. Историю, прошедшую в режиме без хранения, восстановить в WAIX нельзя. Ранее настроенные сценарии могут возобновить работу — проверьте их перед переключением.

Остался вопрос?

Поможем с подключением и работой WAIX.