Звонки, инициированные бизнесом | Документация для разработчиков
Звонки, инициированные бизнесом
Обновлено: 13 ноября 2025 г
Обзор
API для звонков позволяет совершать звонки пользователям WhatsApp из вашего бизнеса.
Пользователь определяет, когда можно принимать звонки, предоставляя права на совершение звонков рабочему номеру телефона.
Диаграмма последовательности вызовов
Примечание:
ACCEPTED обычно приходит после установления соединения. Облачный API отправляет его в основном для аудита событий вызова.Предварительные требования
Прежде чем начать совершать звонки по инициативе компании, убедитесь в следующем:
Подпишитесь на поле веб-перехватчика «вызовы».API для звонков включены для вашего рабочего телефонного номера
И наконец, прежде чем позвонить пользователю WhatsApp, вы должны получить его разрешение.
Схема обработки звонков, инициированных бизнесом
Часть 1: Получение разрешения на звонок пользователю WhatsApp
Получить разрешение на совершение звонков от пользователя WhatsApp можно одним из следующих способов:
Отправить сообщение с запросом на разрешение вызова
Вы можете запросить разрешение на звонок, отправив пользователю WhatsApp запрос на разрешение. Отправьте его в виде сообщения в свободной форме во время работы службы поддержки клиентов или используйте шаблон сообщения.
Узнайте, как отправить в свободной форме. запрос на разрешение на звонокУзнайте, как отправить шаблона. запрос на разрешение для вызова
Включите параметр callback_permission_status в настройках вызова.
Если
параметр callback_permission_status включен, пользователь автоматически предоставляет вашей компании разрешение на совершение звонков при обращении к вам.Пользователь WhatsApp предоставил постоянные разрешения
Пользователь также может в любое время предоставить компании постоянные права доступа через свой бизнес-профиль.
Часть 2: Ваша компания инициирует новый звонок пользователю WhatsApp
Теперь, когда у вас есть разрешение пользователя, вы можете инициировать новый звонок нужному пользователю WhatsApp.
Если ошибок нет, вы получите успешный ответ:
Примечание: Ответ с кодом ошибки
138006 указывает на отсутствие у пользователя WhatsApp разрешения на запрос вызова для этого номера компании.Часть 3: Установление соединения с помощью сигнализации веб-перехватчика
После успешного инициирования нового вызова вы получите ответ веб-перехватчика Call Connect, содержащий
ответ SDP от Cloud API. Затем ваша компания применит ответ SDP из этого веб-перехватчика к вашему стеку WebRTC для инициирования медиасоединения.После этого вы получаете соответствующий веб-хук статуса, указывающий на то, что вызов
проходит успешно, принятили отклонен:Конечные точки для звонков, инициированных бизнесом
Инициировать звонок
Используйте этот конечный пункт для инициирования звонка пользователю WhatsApp, указав номер телефона и предложение WebRTC-звонка. Существует ограничение в 10000 инициированных новых звонков в течение 24 часов с одного корпоративного номера телефона.
Параметры тела
Ответ об успехе
Ответ с ошибкой
Возможные ошибки, которые могут возникнуть:
Неверный номер телефонаОшибки доступа/авторизацииОшибки проверки формата запроса, например, информация о соединении, SDP, ICEОшибки проверки SDPОшибки ограничения вызовов
Завершить вызов
Используйте эту конечную точку для завершения активного вызова.
присутствует
RTCP BYE в медиатрактеКогда пользователь WhatsApp завершает вызов, вам не нужно звонить на эту конечную точку. После успешного завершения вызова вы получите веб-перехватчик завершения вызова.
Параметры тела
| Параметр | Описание | Пример значения |
|---|---|---|
call_idНить |
Необходимый
Идентификатор телефонного звонка. При входящих звонках вы получаете идентификатор вызова от веб-перехватчика Call Connect, когда звонок инициирует пользователь WhatsApp. |
“wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh” |
действиеНить |
Необходимый
Действие, выполняемое в отношении указанного идентификатора вызова. Значения могут быть связаны | предварительное принятие | принятие | отклонение | завершение |
«прекратить» |
Ответ об успехе
Ответ с ошибкой
Возможные ошибки, которые могут возникнуть:
Неверный идентификатор вызоваНеверный номер телефонаПользователь WhatsApp уже завершил звонокВызов с отклонением уже выполняетсяОшибки доступа/авторизации
Веб-хуки для инициированных бизнес-звонков
находится
"calls" внутри "value" ответа вебхука "calls" содержит метаданные о звонке, которые используются для обработки каждого звонка, совершенного или принятого вашей компанией.Чтобы получать веб-хуки Calling API, подпишитесь на поле веб-хука «calls».
веб-перехватчик статуса вызова
Этот веб-перехватчик отправляется при следующих событиях вызова:
Звонок: Когда устройство пользователя WhatsApp начинает звонитьПринято: Когда пользователь WhatsApp принимает звонокОтклонено: Когда пользователь WhatsApp отклоняет звонок. В этом случае вы также получаете веб-хук завершения вызова
Здесь используется структура веб-хуков, аналогичная структуре веб-хуков статуса, применяемых для сообщений Cloud API.
Значения веб-хуков для "статусов"
| Заполнитель | Описание |
|---|---|
идентификаторНить |
Уникальный идентификатор для вызова |
метка времениЦелое число |
Временная метка UNIX события веб-перехватчика |
recipient_idЦелое число |
Номер телефона пользователя WhatsApp, принимающего звонок |
статусЦелое число |
Текущий статус вызова.
Возможные значения:
ЗВОНОК: Инициированный компанией звонок поступает на абонента.ПРИНЯТО: Звонок, инициированный компанией, принят пользователем.ОТКЛОНЕНО: Звонок, инициированный представителем компании, отклонен пользователем. |
biz_opaque_callback_dataНить |
Произвольная строка, которую ваша компания передает в вызов для отслеживания и регистрации данных.
Возвращается только в том случае, если предоставлено через запросы API Initiate New Call. |
Вызов завершения веб-перехватчика
Уведомление через веб-перехватчик отправляется всякий раз, когда вызов завершается по какой-либо причине, например, когда пользователь WhatsApp кладет трубку или когда компания вызывает конечную точку с действием «
завершить» или «отклонить».Значения веб-хука для "вызовов"
| Заполнитель | Описание |
|---|---|
идентификаторНить |
Уникальный идентификатор для вызова |
кЦелое число |
Вызываемый номер (звонящий) |
отЦелое число |
Номер звонящего |
событиеЦелое число |
Событие вызова, о котором этот веб-перехватчик уведомляет подписчика |
метка времениЦелое число |
Временная метка UNIX события веб-перехватчика |
направлениеНить |
Направление совершаемого звонка.
Может содержать либо:
BUSINESS_INITIATED —для звонков, инициированных вашей компанией.USER_INITIATED —для звонков, инициированных пользователем WhatsApp. |
время началаЦелое число |
Временная метка UNIX, указывающая на начало звонка.
Присутствует только тогда, когда на звонок ответил другой абонент. |
конец_времениЦелое число |
Временная метка UNIX, отражающая момент завершения звонка.
Присутствует только тогда, когда на звонок ответил другой абонент. |
продолжительностьЦелое число |
Продолжительность разговора в секундах.
Присутствует только тогда, когда на звонок ответил другой абонент. |
biz_opaque_callback_dataНить |
Произвольная строка, которую ваша компания передает в вызов для отслеживания и регистрации данных.
Возвращается только в том случае, если предоставлено через запрос API Initiate Call или запрос Accept Call. |
ошибки.кодЦелое число |
Объект errors присутствует только для неудачных вызовов, если доступна информация об ошибке. Code — это один из кодов ошибок вызова. |
Обзор SDP и примеры структур
Протокол описания сеанса (SDP) — это текстовый формат, используемый для описания характеристик мультимедийных сеансов, таких как голосовые и видеозвонки, в приложениях для связи в реальном времени. SDP предоставляет стандартизированный способ описания медиапотоков сеанса. Это включает тип медиафайлов, кодеки, протоколы и параметры для установления и управления сеансом.
В контексте WebRTC протокол SDP используется для согласования параметров передачи данных между отправителем и получателем, позволяя им согласовать специфику обмена данными.