Перейти к основному содержанию

Что это такое

API WhatsApp Calling от YCloud управляет сигнализацией голосовых вызовов между пользователем WhatsApp и бизнес-номером телефона. Ваше приложение обменивается SDP через YCloud, в то время как ваша реализация WebRTC обрабатывает аудиосоединение. Звонки могут инициироваться в любом направлении:
  • Инициированные пользователем: Пользователь WhatsApp звонит вашему бизнесу. Ваше приложение получает предложение (offer) и принимает или отклоняет звонок.
  • Инициированные бизнесом: Ваше приложение создает предложение (offer) и запрашивает у YCloud звонок пользователю WhatsApp.
Calling API обрабатывает сигнализацию вызовов, а не медиастек WebRTC. Ваше приложение отвечает за установку peer connection, захват и воспроизведение аудио, генерацию SDP и очистку ресурсов WebRTC.

Карта API

Calling API и события Webhook следуют одному и тому же жизненному циклу, но не образуют единую последовательность, применимую к каждому звонку. Выполните общую настройку, затем следуйте сценарию для звонков, инициированных пользователем или бизнесом. Используйте идентификатор звонка, wacid, для сопоставления всех операций и событий.

Общая настройка

Звонки, инициированные пользователем

Звонки, инициированные бизнесом

Общее завершение звонка

Необязательная обработка медиа

В этих таблицах описан рабочий процесс приложения. Они не гарантируют, что вебхуки будут доставлены в том же порядке, что и строки. Сопоставляйте события по wacid и обрабатывайте повторную доставку идемпотентно.

Перед началом работы

Перед отправкой запроса к Calling подготовьте следующее:
  1. Ключ API учетной записи YCloud. Передавайте его в заголовке X-API-Key. См. раздел Authentication.
  2. WhatsApp Business Account и бизнес-номер телефона, зарегистрированный в YCloud.
  3. Включенная функция Calling для этого номера телефона.
  4. Реализация WebRTC аудио, способная создавать и применять предложения и ответы SDP (offers and answers).
  5. Эндпоинт Webhook YCloud, подписанный на события Calling, используемые вашей интеграцией. См. раздел Configure webhooks.
  6. Разрешение пользователя на вызовы, если оно требуется для звонка, инициированного бизнесом.
Свяжитесь со своим представителем YCloud, чтобы включить доступ к Calling API. Чтобы соответствовать критериям для исходящих вызовов, следуйте текущим требованиям Calling, включая уровень обмена сообщениями Business Portfolio на 2000 клиентов и список поддерживаемых стран для бизнес-номеров. Прежний порог в 1000 переписок заменен текущими требованиями. В приведенных ниже примерах используются следующие переменные окружения:
Храните API-ключ на своем сервере. Не помещайте его в код браузера или мобильного приложения.

Принцип работы

Начните с настройки бизнес-номера телефона. Затем выполните обмен SDP в зависимости от направления вызова. Ответы API подтверждают отдельные операции сигнализации, а события webhook сообщают об изменениях состояния и окончательном результате. Если захват включен, отдельные события уведомляют о готовности записи или расшифровки к скачиванию.

Запрос

Настройка бизнес-номера телефона

Параметры Calling и захвата относятся к конкретному бизнес-номеру телефона WhatsApp. Настройте их перед обработкой вызовов.

Чтение настроек Calling

Используйте GET /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/settings, чтобы проверить, включена ли функция Calling и отображается ли значок Calling:
Если опустить type, YCloud возвращает ответ с настройками Calling.

Включение Calling

Сохраните настройки Calling с помощью POST /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/settings, прежде чем начинать принимать или совершать вызовы:
Ответ содержит сохраненный объект calling. Перед обработкой реальных вызовов завершите настройку webhooks и сессий WebRTC.

Настройка записи и расшифровки

Параметры захвата применяются к новым вызовам, созданным через API. Можно включить запись, расшифровку или обе функции.
Чтобы прочитать настройки захвата, используйте type=capture:
Вы можете включить calling и capture в один запрос POST. После проверки доступа к номеру телефона YCloud пытается сохранить каждый раздел независимо. В случае сбоя при сохранении одного из них второй раздел уже может быть сохранен. Прочитайте обе настройки после ошибки, а затем повторите попытку только для того раздела, который все еще требует обновления.

Обработка звонка, инициированного пользователем

Последовательность вызова, инициированного пользователем При звонке, инициированном пользователем, WhatsApp отправляет SDP-предложение (offer). Ваше приложение отвечает на это предложение, а затем принимает или отклоняет вызов.

1. Получение события connect

Подпишитесь на whatsapp.call.connect. В событии, инициированном пользователем, для direction установлено значение USER_INITIATED, и оно содержит SDP offer.
Сохраните callingConnect.wacid и callingConnect.phoneId вместе. Примените полученное SDP-предложение к пир-соединению WebRTC и создайте SDP-ответ (answer).

2. Предварительный прием вызова (pre-accept)

Вызовите pre-accept после создания SDP-ответа, но до того, как оператор примет вызов. Это подготавливает медиатракт и может уменьшить прерывание звука при ответе на вызов. Эндпоинт: POST /whatsapp/calls/preAccept
После успешного предварительного принятия удерживайте звонок в состоянии вызова (ringing) или готовности. Предварительное принятие не означает ответ на звонок для пользователя.

3. Примите звонок

Когда оператор отвечает, отправьте те же phoneId, wacid, тип SDP и SDP answer на эндпоинт принятия. Эндпоинт: POST /whatsapp/calls/accept
Поля запроса и структура ответа такие же, как и при предварительном принятии. После успешного ответа используйте состояние подключения WebRTC для проверки готовности медиа и дождитесь whatsapp.call.terminate для получения окончательного результата звонка. Задокументированное окно принятия входящего звонка составляет приблизительно 30–60 секунд после вебхука подключения. Принимайте звонок незамедлительно: неотвеченный звонок завершается на стороне пользователя с уведомлением Not Answered и отправкой вебхука terminate. Даже если подключение WebRTC уже установлено, запускайте аудио только после того, как запрос на принятие вернет HTTP 200. Более ранний запуск может обрезать первые слова, а слишком поздний — привести к тишине.

Отклонение звонка вместо принятия

Если оператор не может принять входящий звонок, отклоните его вместо создания активной сессии. Эндпоинт: POST /whatsapp/calls/reject
В ответе используется стандартный формат ответа Calling. Освободите локальное peer connection после запроса и примите последующее событие завершения для этого wacid, если оно поступит.

Инициирование звонка со стороны бизнеса

При звонке, инициированном бизнесом, ваше приложение создает SDP offer и отправляет его в YCloud.

Получение разрешения на звонок

Перед совершением звонка получите разрешение пользователя на звонок. Интерактивный запрос разрешения можно отправить в рамках подходящего окна обслуживания клиентов:
Отправьте это тело запроса на POST /v2/whatsapp/messages/sendDirectly или поставьте в очередь с помощью POST /v2/whatsapp/messages. Вы также можете создать шаблон с разрешением на звонок. Например, отправьте это тело запроса на POST /v2/whatsapp/templates, а затем дождитесь одобрения:
Отправьте одобренный шаблон с соответствующим параметром тела:
Когда в настройках звонков для номера телефона включена опция callback_permission_status, звонок, инициированный пользователем, может предоставить разрешение на обратный звонок. Пользователь также может предоставить постоянное разрешение на звонки в профиле компании. Ответы с разрешениями приходят как события whatsapp.inbound_message.received. Проверяйте объект interactive.call_permission_reply, а не только факт доставки сообщения с запросом разрешения:
Не инициируйте звонок после отклонения запроса или при истекшем сроке разрешения. Ошибка Meta 138006 означает, что у бизнес-номера нет необходимого разрешения на звонок. Подробнее об ошибках провайдера см. в разделе Ошибки Calling в Meta.

1. Создайте SDP offer

Создайте локальное peer connection WebRTC и подключите аудиотрек. Сгенерируйте SDP offer, установите его в качестве локального описания и дождитесь завершения этой операции, прежде чем отправлять offer в YCloud.

2. Подключите звонок

Эндпоинт: POST /whatsapp/calls/connect Укажите хотя бы одно из полей: to или recipient. Если передать оба, YCloud будет использовать to и проигнорирует recipient.
Немедленно сохраните возвращенный wacid. success: true означает, что операция подключения была принята; это не означает, что пользователь ответил.

3. Примените ответ и отслеживайте попытку

YCloud отправляет whatsapp.call.connect для вызова. Для исходящего вызова, инициированного бизнесом, событие имеет значение direction: BUSINESS_INITIATED и передает удаленный SDP answer. Примените этот ответ (answer) в качестве удаленного описания (remote description) для того же peer connection. Подпишитесь на whatsapp.call.status.updated, чтобы отслеживать попытку:
Сделайте обработку событий идемпотентной, чтобы повторная доставка не дублировала действия операторов, списание средств или очистку данных.

Завершение активного вызова

Вызывайте terminate, когда вашему приложению необходимо завершить активный входящий или исходящий вызов. Конечная точка: POST /whatsapp/calls/terminate
Поля запроса совпадают с запросом reject. Успешный ответ подтверждает, что YCloud обработал операцию terminate. Держите запись вызова открытой до тех пор, пока вы не получите окончательное событие завершения или пока ее не закроет ваша собственная политика восстановления.

Ответ

Все пять сигнальных конечных точек возвращают ответ одинаковой структуры:
wacid идентифицирует вызов, связанный с операцией. success: true подтверждает успешное выполнение операции сигналинга; он не подтверждает, что другой участник ответил или что вызов завершен. Для этих результатов используйте состояние WebRTC и webhook-события Calling.

Обработка финального события вызова

whatsapp.call.terminate — это финальное событие жизненного цикла вызова.
При получении этого события финализируйте запись вызова и освободите все оставшиеся ресурсы WebRTC. Более ранний ответ API не подтверждает факт завершения вызова.

Получение записей и транскрипций

Если захват включен, обработка медиа продолжается после завершения жизненного цикла вызова. Для записи и транскрипции предусмотрены отдельные финальные события: В следующем примере показана доступная запись:
Оба свойства полезной нагрузки используют одинаковые поля:

Скачивание доступного ресурса

Вызывайте медиа-конечную точку только после того, как соответствующее событие сообщит о статусе AVAILABLE. Конечная точка: GET /whatsapp/calls/media/{mediaAssetId}
Конечная точка возвращает файл целиком в виде вложения и не поддерживает загрузку по диапазонам байтов. Для записей используется .ogg; для транскрипций — .json. Только клиент-владелец (tenant) в YCloud может скачать ресурс. Ресурс остается доступным в течение 30 дней с момента его создания. При запросе отсутствующих, недоступных, истекших или не принадлежащих вам ресурсов возвращается ошибка HTTP 404.

Создание надежного приемника webhook

Подпишите вашу конечную точку на события, необходимые для вашей интеграции:
Для каждого запроса:
  1. Сохраняйте исходное тело запроса и проверяйте YCloud-Signature, прежде чем доверять событию.
  2. Сохраняйте событие или ставьте надежную задачу в очередь.
  3. Своевременно возвращайте успешный ответ 2xx.
  4. Выполняйте дедупликацию по id верхнего уровня события.
  5. Сопоставляйте данные вызова по wacid; сохраняйте phoneId вместе с ними для дальнейших операций.
  6. Обрабатывайте связанные события, поступающие с небольшим интервалом, и учитывайте возможность повторной доставки.
См. раздел Настройка вебхуков для получения сведений о создании эндпоинта, проверке подписи и механизме доставки. На странице Примеры полезной нагрузки Webhook представлены полные сгенерированные примеры.

Обработка ошибок и восстановление

Эндпоинты для вызовов используют стандартный формат ответа об ошибке API YCloud. Информацию о структуре ответа и рекомендации по повторным попыткам см. в разделе Обработка ошибок. Используйте следующие проверки при типичных сбоях сервиса вызовов: Тайм-аут запроса не означает, что действие сигнализации завершилось сбоем. Перед повторной попыткой сопоставьте запрос с событиями Webhook и текущим локальным состоянием вызова. Действие могло уже дойти до WhatsApp.

Контрольный список интеграции

  • Включите функцию вызовов на нужном рабочем номере телефона.
  • Настройте и протестируйте все обязательные подписки Webhook для вызовов.
  • Проверяйте подписи Webhook и выполняйте дедупликацию событий.
  • Сохраняйте wacid, phoneId, направление и текущее состояние вместе.
  • Рассматривайте ответ API success как подтверждение принятия операции, а не как финальный результат вызова.
  • Используйте preAccept только для подготовки; для ответа вызывайте accept.
  • Завершайте вызовы из whatsapp.call.terminate.
  • Загружайте записанные медиафайлы только после события AVAILABLE и в течение 30 дней.
  • Освобождайте ресурсы WebRTC при отклонении, завершении, сбое и локальном тайм-ауте.
  • Избегайте записи ключей API, полных данных SDP или идентификаторов участников в общие журналы приложения.

Справочник по API вызовов

Ознакомьтесь с точными схемами запросов и ответов для каждого эндпоинта вызовов.

Примеры полезной нагрузки Webhook

Изучите полные примеры событий вызовов, сгенерированные на основе спецификации Webhook.