ВойтиНачать бесплатный пробный период
Meta Tech Provider

Вебхуки звонков 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, поэтому ваш ИИ и автоматизации отвечают на сообщения и отправляют шаблоны, а звонки продолжают звонить в приложении на вашем телефоне.

Not supported

Голосовые и видеозвонки в Cloud API для номера, подключённого через приложение WhatsApp Business; в приложении они не меняются.

2,000

Минимальный дневной лимит сообщений, в уникальных получателях, который должен быть у номера, чтобы использовать Calling API.

7 days

Сколько времени записи и транскрипции звонков остаются доступными для скачивания после доставки их вебхука.

wacid

Префикс ID звонков, значение, которое связывает вебхуки connect, статуса и terminate одного звонка.

whatsapp_business_messaging

Разрешение, которое приложению нужно для получения вебхуков звонков, такое же, как для сообщений.

Что сообщает поле вебхука calls?

Всё, что происходит со звонком, совершённым или полученным через Calling API, в одном поле с событием на каждом этапе. Звонок, инициированный бизнесом, создаёт событие connect, обновления статуса и событие terminate. Звонки, обрабатываемые через SIP, вместо connect передают call_created, без SDP-сессии. Одно связанное событие находится в другом месте: когда клиент отвечает на запрос разрешения на звонок, ответ приходит в поле messages как интерактивное сообщение типа call_permission_reply.

connectThe call is ready to connect; session carries the SDP to apply to your WebRTC stack.
call_createdA SIP call was attempted, business- or user-initiated.
statuses (type call)RINGING, ACCEPTED or REJECTED for a business-initiated call.
terminateThe call ended: status COMPLETED or FAILED, with times and duration when answered.
call_recording_availableA media id for the finished audio recording.
call_transcription_availableA media id for the transcript, a JSON document.

Как выглядит вебхук звонка?

Тот же конверт, что и у любого вебхука WhatsApp, с массивом calls в value и полем field, равным calls. direction принимает значения BUSINESS_INITIATED или USER_INITIATED, from и to содержат номера телефонов, to_user_id содержит BSUID клиента, и любой из номеров может отсутствовать у клиента, который использует имя пользователя. metadata.phone_number_id определяет ваш номер, как и в любом другом поле. Это пример Call Connect от Meta, с плейсхолдерами в том виде, как их печатает Meta:

Meta's example: the Call Connect webhook
{
  "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 дней после вебхука, затем они пропадают.
Настройка с EasyCoexistence

Каждый номер находится под мониторингом 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 Business на номере CoexistenceЗвонки в приложении WhatsApp Business после Coexistence работают как прежде, но Calling API Meta для таких номеров недоступен. Что это значит для вас.Статусы вебхуков WhatsApp: отправлено, доставлено, прочитано, ошибкаКак WhatsApp сообщает о судьбе отправленного сообщения: массив statuses, значения статусов, поля и сопоставление по wamid.Какие функции WhatsApp отключаются при CoexistenceИсчезающие сообщения, просмотр один раз, геолокация в реальном времени и рассылки отключаются на подключённом номере. Что это значит.Что синхронизируется с API, а что нетКонтакты и история личных чатов синхронизируются. Группы, каталог, метки, быстрые ответы и автоответы не переносятся. Полный список.Перенос номера с Coexistence только на Cloud APIКак перенести номер из приложения WhatsApp Business на Cloud API: порядок шагов, какая история теряется по данным Meta и что меняется.Повторы вебхуков WhatsApp, дубликаты и порядок: как с ними работатьMeta повторяет доставку вебхуков WhatsApp до 7 дней, поэтому дубликаты обычны, а порядок не гарантирован. Ключи дедупликации и безопасный обработчик.

Готовы начать?

Настройте WhatsApp Coexistence за несколько минут, а не месяцев. Приложение продолжит работать на телефоне.

Начать бесплатный пробный период

Проверено по состоянию на