Вебхуки звонков WhatsApp: события Calling API и звонки на номере Coexistence
Поле вебхука calls передаёт события WhatsApp Business Calling API: connect с SDP answer или offer, статусы звонка RINGING, ACCEPTED и REJECTED, terminate со статусом COMPLETED или FAILED и продолжительностью, а также call_recording_available или call_transcription_available. Руководство Meta по Coexistence указывает, что голосовые и видеозвонки в приложении WhatsApp Business не меняются и не поддерживаются в Cloud API, поэтому такие звонки остаются на телефоне.
easyCoexistence подключает ваш номер приложения WhatsApp Business к Cloud API Meta через Coexistence, поэтому ваш ИИ и автоматизации отвечают на сообщения и отправляют шаблоны, а звонки продолжают звонить в приложении на вашем телефоне.
Голосовые и видеозвонки в Cloud API для номера, подключённого через приложение WhatsApp Business; в приложении они не меняются.
Минимальный дневной лимит сообщений, в уникальных получателях, который должен быть у номера, чтобы использовать Calling API.
Сколько времени записи и транскрипции звонков остаются доступными для скачивания после доставки их вебхука.
Префикс ID звонков, значение, которое связывает вебхуки connect, статуса и terminate одного звонка.
Разрешение, которое приложению нужно для получения вебхуков звонков, такое же, как для сообщений.
Что сообщает поле вебхука calls?
Всё, что происходит со звонком, совершённым или полученным через Calling API, в одном поле с событием на каждом этапе. Звонок, инициированный бизнесом, создаёт событие connect, обновления статуса и событие terminate. Звонки, обрабатываемые через SIP, вместо connect передают call_created, без SDP-сессии. Одно связанное событие находится в другом месте: когда клиент отвечает на запрос разрешения на звонок, ответ приходит в поле messages как интерактивное сообщение типа call_permission_reply.
Как выглядит вебхук звонка?
Тот же конверт, что и у любого вебхука WhatsApp, с массивом calls в value и полем field, равным calls. direction принимает значения BUSINESS_INITIATED или USER_INITIATED, from и to содержат номера телефонов, to_user_id содержит BSUID клиента, и любой из номеров может отсутствовать у клиента, который использует имя пользователя. metadata.phone_number_id определяет ваш номер, как и в любом другом поле. Это пример Call Connect от Meta, с плейсхолдерами в том виде, как их печатает Meta:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "16315553601",
"phone_number_id": "<PHONE_NUMBER_ID>"
},
"contacts": [
{
"profile": {
"name": "<CALLEE_NAME>",
"username": "<USERNAME>"
},
"wa_id": "16315553602",
"user_id": "<BSUID>",
"parent_user_id": "<PARENT_BSUID>"
}
],
"calls": [
{
"id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh",
"to": "16315553601",
"to_user_id": "<BSUID>",
"to_parent_user_id": "<PARENT_BSUID>",
"from": "16315553602",
"event": "connect",
"timestamp": "1671644824",
"direction": "BUSINESS_INITIATED",
"session": {
"sdp_type": "answer",
"sdp": "<<RFC 8866 SDP>>"
}
}
]
},
"field": "calls"
}
]
}
]
}Какие поля добавляет событие terminate?
Событие terminate чаще всего сохраняют системы, потому что оно закрывает звонок. Его поля по справочнику Meta:
- status: COMPLETED, когда звонок завершился без неожиданных ошибок, включая неотвеченные звонки; FAILED, когда он не соединился или прервался.
start_time,end_timeи duration в секундах: присутствуют, только если собеседник ответил.- errors: code, message, href и
error_data.details для звонка со статусом FAILED. biz_opaque_callback_data: ваша собственная строка отслеживания, если вы передали её при начале или принятии звонка.
Работают ли вебхуки звонков на номере Coexistence?
Руководство Meta по Coexistence отвечает на это в таблице возможностей: голосовые и видеозвонки в приложении WhatsApp Business не меняются, а для номера, подключённого таким образом, не поддерживаются в Cloud API. Собственные предварительные условия Calling API говорят то же самое с другой стороны: бизнес-номер должен использоваться с Cloud API, а не с приложением WhatsApp Business. Поэтому на номере Coexistence клиенты звонят как прежде, звонок поступает в приложение на телефоне, а поле calls ничего не сообщает. Бизнесу, которому нужны звонки в своих системах, нужен номер только на Cloud API.
Как события одного звонка связаны между собой?
По ID звонка, который начинается с wacid и повторяется в каждом событии этого звонка. Звонок, инициированный бизнесом, передаёт connect с SDP answer, статусы RINGING, затем ACCEPTED или REJECTED, и наконец terminate. Звонок, инициированный пользователем, передаёт connect с SDP offer, на который ваш стек должен ответить, затем terminate. События записей и транскрипций, если они включены, приходят после terminate. Сохраняйте события на основе id и event, так как повторные попытки их дублируют, а порядок поступления не гарантирован. Полный список предварительных условий Calling API находится на странице о звонках на номере Coexistence.
Что может сделать ваш ИИ со звонками на номере Coexistence?
Работать в чате, а звонки остаются за человеком у телефона. easyCoexistence не подписывается на поле calls и не имеет инструментов для звонков; его коннектор и автоматизации охватывают сообщения и шаблоны. На практике это значит, что ответ ИИ может сообщить клиенту, когда кто-то доступен для разговора и на какой номер позвонить, автоматизация по ключевому слову может отвечать на «call» или «phone» этой информацией, а владелец принимает звонок в приложении WhatsApp Business, как и раньше.
Распространённые ошибки
- Подписка на calls для номера Coexistence и ожидание событий. Meta указывает, что звонки для этих номеров не поддерживаются в Cloud API.
- Ожидание start_time и duration в каждом terminate. Они появляются только когда звонок был принят; неотвеченный звонок всё равно завершается со статусом COMPLETED.
- Поиск ответов на разрешение в поле calls. Они приходят в messages, как интерактивное call_permission_reply.
- Оставление записей и транскрипций у Meta. Их можно скачать в течение 7 дней после вебхука, затем они пропадают.
Каждый номер находится под мониторингом 24/7, включая правило 14 дней, по которому номер отключается, если приложение не открывается. От US$ 9 до US$ 0,75 за номер в месяц, снижаясь по мере добавления номеров, первые 3 дня бесплатно.
Часто задаваемые вопросы
Теряют ли клиенты кнопку звонка, когда номер подключается к API через Coexistence?
Руководство Meta по Coexistence указывает, что голосовые и видеозвонки в приложении WhatsApp Business не меняются. Клиенты звонят на тот же номер, а владелец отвечает в приложении на телефоне.
Calling API тарифицируется так же, как сообщения?
Нет. На странице цен Meta сказано, что Calling API имеет другие тарифы, и указан отдельный документ с тарифами на звонки, поэтому плата за звонки не появляется в объекте pricing в статусах сообщений.
Можно ли записать или транскрибировать звонок через Calling API?
Да, если включена запись или транскрипция. После звонка Meta отправляет call_recording_available с audio media id или call_transcription_available с id JSON-документа, обычно в течение минуты.
Может ли вебхук звонков уходить на другой эндпоинт, а не на эндпоинт приложения?
Да. calls входит в число полей, которые Meta позволяет направить на альтернативный URL обратного вызова для аккаунта WhatsApp Business или номера телефона, наряду с messages и полями Coexistence.
Читайте дальше
Готовы начать?
Настройте WhatsApp Coexistence за несколько минут, а не месяцев. Приложение продолжит работать на телефоне.
Начать бесплатный пробный периодПроверено по состоянию на