Настроить вебхуки
Как передавать сообщения клиентов и статусы доставки на ваш сервер.
Подготовьте адрес
Нужен публичный HTTPS URL на стандартном порту 443 с действительным сертификатом. Локальные и частные адреса не принимаются. Перенаправления не выполняются. Для разработки используйте публичный тестовый endpoint с проверкой подписи.
Настройка
- В кабинете откройте «Вебхуки» и укажите URL.
- Включите «Доставлять события на этот адрес» и отметьте нужные события. Для сообщений с телефона выберите «Отправлено из WhatsApp на телефоне» (message.echo). Для этого номер должен быть подключён с Coexistence.
- Сохраните секрет, показанный при первом создании. Он отличается от API-ключа.
- Отправьте тестовое событие и проверьте журнал доставок.
- Напишите бизнесу с тестового телефона и проверьте реальное событие.
Через API
{
"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; доставку и прочтение проверяйте по вебхукам.
{
"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.