← Все статьи
Гайд

Webhook исходящих звонков WhatsApp в обычном рабочем пространстве

В обычном рабочем пространстве UnifyPort можно подготовить исходящий звонок WhatsApp один на один. Если конечная точка Webhook подписана только на ["*"], сообщения могут приходить, а обратные вызовы о звонках отсутствовать. Чтобы получать оба события, явно укажите call.answered и call.ended.

Справка по созданию звонка описывает голосовые и видеозвонки, которые человек запускает через неофициальный интерфейс UnifyPort. call.incoming зарезервировано для будущей поддержки входящих звонков.

1. Проверьте правила подписки

Рабочее пространствоПодпискаСобытия исходящих звонков
Обычное["*"], [] или список не указанТолько обычные события
ОбычноеИмена явно указаны в subscribed_eventsПеречисленные события звонков
С допуском к бета-тестированиюЯвный список, wildcard, пустой или отсутствующий списокСовпадающие события звонков

При выполнении условий доставки конечная точка получает событие по указанному имени. В обычном рабочем пространстве можно сохранить * для обычных событий и добавить два имени событий звонка. Явная подписка на зарезервированное call.incoming в обычном рабочем пространстве возвращает 403 beta_feature_not_enabled (41002).

2. Прочитайте настройки перед обновлением

С помощью получения конечной точки Webhook проверьте URL назначения, статус, текущую подписку и политику повторов. Уточните, относится ли точка к рабочему пространству или определённому аккаунту мессенджера. Обновление сохраняет привязку к аккаунту.

Обновление конечной точки Webhook заменяет настройки. Подготовьте полную конфигурацию, сохранив текущие URL, статус и политику повторов. Если подпись включена, возьмите существующий секрет из защищённой конфигурации приложения. Ответ чтения содержит signing_enabled, секрет хранится у приложения. При пропуске или пустом signing_secret подпись отключается. Без политики повторов восстанавливается настройка по умолчанию: три повтора после первой попытки.

3. Добавьте события звонков и сохраните подписку на сообщения

Если точка использует wildcard, отправьте следующее тело в PATCH /v1/webhook-endpoints/{endpoint_id}. Пример предполагает активную конечную точку с подписью и тремя повторами. Подставьте текущие URL, статус, секрет и параметры повторов. API-ключи и секреты подписи храните на сервере.

{
  "url": "https://support.example.com/webhook",
  "status": "active",
  "subscribed_events": ["*", "call.answered", "call.ended"],
  "signing_secret": "<EXISTING_WEBHOOK_SIGNING_SECRET>",
  "retry_policy": { "max_attempts": 3 }
}

При явной подписке скопируйте текущие имена и добавьте два события звонка. Например, для списка только из message.received и message.read получится следующий массив. Укажите его в поле subscribed_events полного тела обновления.

["message.received", "message.read", "call.answered", "call.ended"]

Снова прочитайте настройки и проверьте URL, статус, подписку, состояние подписи и повторы. Убедитесь, что получатель обрабатывает оба события звонка и прежние события сообщений.

4. Проверьте доставку одним новым звонком

  1. Выберите тестовый диалог из того же авторизованного аккаунта WhatsApp. Подготовьте звонок через POST /v1/calls и сохраните полученный call_id вместе с задачей приложения.
  2. Ответ 201 с state: preparing подтверждает готовность ссылки. Оператор открывает закрытую join_url и нажимает Start call до expires_at.
  3. После соединения и завершения тестового звонка найдите событие соединения и событие завершения. Сверьте account_id и data.call.id с сохранённой записью.
  4. Отправьте тестовое сообщение прежним способом и убедитесь, что ожидаемое событие дошло до получателя.

Для точки с подписью проверяйте исходное тело запроса по руководству по доставке и проверке подписи. Устраняйте дубли по id события и учитывайте нарушение порядка. Позднее событие соединения дополняет подтверждение, а звонок остаётся завершённым. Записи о звонках в message.* имеют отдельное назначение.

5. Разберите пропуски и сохраните возможность отката

Если обратный вызов отсутствует, проверьте точные имена событий, область действия и активность точки. Затем проверьте журналы получателя, HTTP-ответы и хранилище приложения. 2xx подтверждает доставку. Сохранение и привязку к задаче проверяйте отдельно. Доставка, повторы и повторная обработка dead letter учитывают действующие допуск и подписку.

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

UnifyPort API

Превратите интеграцию сообщений в стабильный продуктовый pipeline.

Начните с отправки через единый API, затем возвращайте входящие сообщения в бизнес-систему стандартными событиями.