Что это такое
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 подготовьте следующее:- Ключ API учетной записи YCloud. Передавайте его в заголовке
X-API-Key. См. раздел Authentication. - WhatsApp Business Account и бизнес-номер телефона, зарегистрированный в YCloud.
- Включенная функция Calling для этого номера телефона.
- Реализация WebRTC аудио, способная создавать и применять предложения и ответы SDP (offers and answers).
- Эндпоинт Webhook YCloud, подписанный на события Calling, используемые вашей интеграцией. См. раздел Configure webhooks.
- Разрешение пользователя на вызовы, если оно требуется для звонка, инициированного бизнесом.
Принцип работы
Начните с настройки бизнес-номера телефона. Затем выполните обмен 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
3. Примите звонок
Когда оператор отвечает, отправьте те жеphoneId, wacid, тип SDP и SDP answer на эндпоинт принятия.
Эндпоинт: POST /whatsapp/calls/accept
whatsapp.call.terminate для получения окончательного результата звонка.
Задокументированное окно принятия входящего звонка составляет приблизительно 30–60 секунд после вебхука подключения. Принимайте звонок незамедлительно: неотвеченный звонок завершается на стороне пользователя с уведомлением Not Answered и отправкой вебхука terminate.
Даже если подключение WebRTC уже установлено, запускайте аудио только после того, как запрос на принятие вернет HTTP 200. Более ранний запуск может обрезать первые слова, а слишком поздний — привести к тишине.
Отклонение звонка вместо принятия
Если оператор не может принять входящий звонок, отклоните его вместо создания активной сессии. Эндпоинт:POST /whatsapp/calls/reject
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
Ответ
Все пять сигнальных конечных точек возвращают ответ одинаковой структуры: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
Подпишите вашу конечную точку на события, необходимые для вашей интеграции:- Сохраняйте исходное тело запроса и проверяйте
YCloud-Signature, прежде чем доверять событию. - Сохраняйте событие или ставьте надежную задачу в очередь.
- Своевременно возвращайте успешный ответ
2xx. - Выполняйте дедупликацию по
idверхнего уровня события. - Сопоставляйте данные вызова по
wacid; сохраняйтеphoneIdвместе с ними для дальнейших операций. - Обрабатывайте связанные события, поступающие с небольшим интервалом, и учитывайте возможность повторной доставки.
Обработка ошибок и восстановление
Эндпоинты для вызовов используют стандартный формат ответа об ошибке API YCloud. Информацию о структуре ответа и рекомендации по повторным попыткам см. в разделе Обработка ошибок. Используйте следующие проверки при типичных сбоях сервиса вызовов:
Тайм-аут запроса не означает, что действие сигнализации завершилось сбоем. Перед повторной попыткой сопоставьте запрос с событиями Webhook и текущим локальным состоянием вызова. Действие могло уже дойти до WhatsApp.
Контрольный список интеграции
- Включите функцию вызовов на нужном рабочем номере телефона.
- Настройте и протестируйте все обязательные подписки Webhook для вызовов.
- Проверяйте подписи Webhook и выполняйте дедупликацию событий.
- Сохраняйте
wacid,phoneId, направление и текущее состояние вместе. - Рассматривайте ответ API
successкак подтверждение принятия операции, а не как финальный результат вызова. - Используйте
preAcceptтолько для подготовки; для ответа вызывайтеaccept. - Завершайте вызовы из
whatsapp.call.terminate. - Загружайте записанные медиафайлы только после события
AVAILABLEи в течение 30 дней. - Освобождайте ресурсы WebRTC при отклонении, завершении, сбое и локальном тайм-ауте.
- Избегайте записи ключей API, полных данных SDP или идентификаторов участников в общие журналы приложения.
Справочник по API вызовов
Ознакомьтесь с точными схемами запросов и ответов для каждого эндпоинта вызовов.
Примеры полезной нагрузки Webhook
Изучите полные примеры событий вызовов, сгенерированные на основе спецификации Webhook.

