Вебхуки
Обновлено:
Где: Настройки > Интеграции > Вебхуки
Для чего это нужно:
«Пересылайте входящие события на ваш сервер». SyBox передаёт копию каждого выбранного события на указанный адрес вашего сервера прямо в момент его возникновения. События WhatsApp приходят в собственном формате Meta. Сообщения клиентов из Messenger, Instagram, Telegram, TikTok и онлайн-чата, а также события диалогов (завершение, метки, контакты, сделки, обращения CRM) приходят в собственном формате SyBox. Сообщения электронной почты и SMS не передаются.
Кому доступно: главному администратору и сотрудникам с правом «Управление каналами». Для создания вебхука или повторного включения приостановленного также требуется право «Показывать номер контакта», так как в событиях передаются реальные номера клиентов.
События на выбор:
- «Входящее сообщение»: клиент прислал сообщение.
- «Статус сообщения»: отправленное вами сообщение отправлено, доставлено, прочитано или не удалось доставить.
- «Реакция»: клиент поставил реакцию на сообщение.
- «Диалог отмечен как завершённый»: диалог был отмечен как завершённый сотрудником, автоматизацией или автоматически после молчания клиента.
- «Метка добавлена или удалена»: к диалогу была добавлена или с него была снята метка.
- «Контакт создан или обновлён»: был создан новый контакт либо изменились имя, email или поля контакта. При импорте контактов эти события не отправляются.
- «Сделка закрыта»: в диалоге была зафиксирована сделка.
- «Обращение CRM открыто или закрыто»: обращение CRM было открыто либо закрыто как решённое, нерешённое или отменённое. Обращение не привязано к номеру, поэтому его получает только вебхук, охватывающий все номера, а не ограниченный отдельными номерами.
Последние пять событий приходят в собственном формате SyBox для любого канала. На странице документации для разработчиков приведён пример каждого из них.
- «Расшифровка голоса» (дополнительно): отправка голосового сообщения задерживается на короткое время (до двух минут), чтобы отправить его сразу вместе с расшифрованным текстом. По умолчанию выключено.
- Перейдите в Настройки > Интеграции > Вебхуки.
- Нажмите «Добавить вебхук».
- Укажите «Название».
- Введите «URL назначения». Это должен быть «Публичный https-адрес, доступный для нас». Обычный http, а также локальные и внутренние IP-адреса не принимаются.
- В блоке «События» отметьте хотя бы одно событие. «Входящее сообщение» выбрано по умолчанию.
- Необязательно: включите «Расшифровка голоса», чтобы получать голосовые сообщения вместе с текстом.
- В блоке «Номера» оставьте вариант «Все номера», чтобы отслеживать все линии WhatsApp, либо выключите его и выберите только нужные номера.
- Нажмите Сохранить.
- В окне появится «Ключ подписи». «Скопируйте сейчас — показывается только один раз». Сохраните его на своём сервере.
Как работает доставка:
- Данные передаются в том же формате, что и в стандартных вебхуках WhatsApp от Meta.
- Каждый запрос подписывается вашим секретным ключом точно так же, как это делает Meta. Если на вашем сервере уже настроена проверка подписи вебхуков Meta, достаточно просто подставить секретный ключ от SyBox.
- Если ваш сервер не отвечает успешным кодом, SyBox будет повторять попытки с увеличивающимся интервалом в течение примерно одного часа. После этого попытки прекращаются.
- В редких случаях (например, при сбое связи по таймауту) одно и то же событие может прийти дважды. Сервер должен корректно обрабатывать дубли.
- Убедитесь, что вебхук включён. Если он выключен, появится сообщение «Сначала включите этот вебхук.»
- На его карточке нажмите «Отправить тестовое событие». Вы увидите сообщение «Тестовое событие отправляется. Его результат появится в разделе «Доставки».»
- Через несколько секунд откроется список «Доставки» с ответом вашего сервера. На карточке также отобразится последний ответ вашего сервера и время попытки. Успешный ответ (например, «HTTP 200») подсвечивается зелёным, ошибка — красным. Статус «Последняя доставка: никогда» означает, что событий ещё не было.
Тестовое событие содержит "event": "test" и не передаёт данных клиентов. Отправлять его можно раз в несколько секунд; если нажать раньше, появится сообщение «Тест был отправлен только что. Повторите попытку через несколько секунд.»
- На карточке вебхука нажмите «Доставки».
- В списке отображаются «Последние 50 доставок за прошедшие 7 дней.», начиная с самых новых. Для каждой указаны событие, время попытки и статус:
- «Доставлено»: ваш сервер ответил успешно.
- «Ожидает отправки»: попыток отправки ещё не было.
- «Ошибка, повторная попытка»: ваш сервер не ответил успешно, и SyBox повторит попытку позже.
- «Не доставлено»: SyBox прекратил попытки.
- Также отображаются HTTP-код ответа вашего сервера, время ответа в миллисекундах и «Попыток: [число]», если попыток было несколько. Само сообщение не показывается.
- Чтобы повторить отправку, нажмите «Отправить снова» у доставки со статусом «Доставлено» или «Не доставлено». Вы увидите «Поставлено в очередь на повторную отправку.» Повторная отправка требует права «Показывать номер контакта», так как при этом данные клиента отправляются заново.
Автоматическое отключение:
Если ваш сервер продолжает выдавать ошибки — 20 неудачных попыток подряд на протяжении более чем часа — SyBox отключает вебхук. На карточке красным цветом отображается «Отключён автоматически после [число] неудачных доставок подряд», а главный администратор получает уведомление «Вебхук был отключён». Ожидающие события сохраняются в течение 24 часов. Исправьте адрес или работу сервера, а затем снова включите вебхук: ожидающие события будут отправлены, а счётчик ошибок сбросится на ноль.
- Нажмите Изменить, чтобы скорректировать название, адрес, события или список номеров.
- Чтобы обновить секретный ключ, введите новое значение в поле «Ключ подписи». Чтобы оставить текущий, не заполняйте это поле («Оставьте пустым, чтобы сохранить текущий ключ»).
- Нажмите Включить / Отключить, чтобы поставить отправку на паузу. События, поступившие во время паузы, встанут в очередь. Если включить вебхук вскоре после этого, они будут доставлены.
- Нажмите Удалить и подтвердите: «Удалить этот вебхук?».
Правила и системные сообщения:
- Название и URL назначения обязательны, также должно быть выбрано хотя бы одно событие. Иначе появится сообщение «Неполные данные».
- Если адрес не использует протокол https или недоступен извне, появится ошибка: «Публичный https-адрес, доступный для нас».
Я потерял ключ подписи.
Посмотреть его повторно невозможно. Откройте редактирование вебхука, введите в поле «Ключ подписи» новый ключ, сохраните настройки и укажите этот же ключ на своём сервере.
Мой вебхук отключился, хотя я его не выключал.
SyBox отключил его после того, как ваш сервер выдал ошибку 20 раз подряд на протяжении более чем часа. См. раздел «Автоматическое отключение» выше: исправьте работу сервера и снова включите вебхук в течение 24 часов, чтобы ожидающие события были отправлены.
На вебхук ничего не приходит.
Сначала нажмите «Отправить тестовое событие» на его карточке и загляните в «Доставки». Затем проверьте четыре момента: (1) Вебхук включён. (2) Выбрано хотя бы одно событие. (3) К вебхуку привязан нужный номер WhatsApp или выбрано «Все номера». (4) Канал, по которому пришло сообщение, поддерживается вебхуками (WhatsApp, Messenger, Instagram, Telegram, TikTok или онлайн-чат; не почта и не SMS). Затем посмотрите статус последней доставки на карточке.
На карточке горит красная ошибка (например, HTTP 404 или 500).
SyBox смог связаться с адресом, но сервер вернул код ошибки. Проверьте правильность URL и логи вашего сервера.
Не удаётся создать вебхук, пишет, что недостаточно прав.
Для добавления и включения вебхука нужны сразу два права: «Управление каналами» и «Показывать номер контакта». Обратитесь к администратору.