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. Проверьте доставку одним новым звонком
- Выберите тестовый диалог из того же авторизованного аккаунта WhatsApp. Подготовьте звонок через
POST /v1/callsи сохраните полученныйcall_idвместе с задачей приложения. - Ответ
201сstate: preparingподтверждает готовность ссылки. Оператор открывает закрытуюjoin_urlи нажимает Start call доexpires_at. - После соединения и завершения тестового звонка найдите событие соединения и событие завершения. Сверьте
account_idиdata.call.idс сохранённой записью. - Отправьте тестовое сообщение прежним способом и убедитесь, что ожидаемое событие дошло до получателя.
Для точки с подписью проверяйте исходное тело запроса по руководству по доставке и проверке подписи. Устраняйте дубли по id события и учитывайте нарушение порядка. Позднее событие соединения дополняет подтверждение, а звонок остаётся завершённым. Записи о звонках в message.* имеют отдельное назначение.
5. Разберите пропуски и сохраните возможность отката
Если обратный вызов отсутствует, проверьте точные имена событий, область действия и активность точки. Затем проверьте журналы получателя, HTTP-ответы и хранилище приложения. 2xx подтверждает доставку. Сохранение и привязку к задаче проверяйте отдельно. Доставка, повторы и повторная обработка dead letter учитывают действующие допуск и подписку.
Сохраните прежние настройки и ссылку на секрет подписи. Для отката отправьте прежнюю полную конфигурацию и повторно проверьте доставку сообщений. При обращении в техническую поддержку укажите ID конечной точки, аккаунта и звонка, время UTC и результаты получателя без секретов. API-ключи, секреты и полные ссылки звонков храните в закрытом виде.
Превратите интеграцию сообщений в стабильный продуктовый pipeline.
Начните с отправки через единый API, затем возвращайте входящие сообщения в бизнес-систему стандартными событиями.