Звонки, инициированные бизнесом | Документация для разработчиков

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

Обновлено: 13 ноября 2025 г

Обзор

API для звонков позволяет совершать звонки пользователям WhatsApp из вашего бизнеса.

Пользователь определяет, когда можно принимать звонки, предоставляя права на совершение звонков рабочему номеру телефона.

Диаграмма последовательности вызовов

Диаграмма последовательности звонков, инициированных бизнесом, показывающая взаимодействие между бизнесом, облачным API и пользователем WhatsApp

Примечание: ACCEPTED обычно приходит после установления соединения. Облачный API отправляет его в основном для аудита событий вызова.

Предварительные требования

Прежде чем начать совершать звонки по инициативе компании, убедитесь в следующем:

Подпишитесь на поле веб-перехватчика «вызовы».API для звонков включены для вашего рабочего телефонного номера

И наконец, прежде чем позвонить пользователю WhatsApp, вы должны получить его разрешение.

Узнайте, как получить разрешение на звонки для пользователей WhatsApp здесь

Схема обработки звонков, инициированных бизнесом

Часть 1: Получение разрешения на звонок пользователю WhatsApp

Получить разрешение на совершение звонков от пользователя WhatsApp можно одним из следующих способов:

Отправить сообщение с запросом на разрешение вызова

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

Узнайте, как отправить в свободной форме. запрос на разрешение на звонокУзнайте, как отправить шаблона. запрос на разрешение для вызова

Включите `параметр callback_permission_status` в настройках вызова.

Если параметр callback_permission_status включен, пользователь автоматически предоставляет вашей компании разрешение на совершение звонков при обращении к вам.

Узнайте, как включить функцию callback_permission_status.

Пользователь WhatsApp предоставил постоянные разрешения

Пользователь также может в любое время предоставить компании постоянные права доступа через свой бизнес-профиль.

Часть 2: Ваша компания инициирует новый звонок пользователю WhatsApp

Теперь, когда у вас есть разрешение пользователя, вы можете инициировать новый звонок нужному пользователю WhatsApp.

Теперь вы можете позвонить на почту. Для инициирования нового вызова необходимо передать в тело запроса следующую конечную точку:

POST <PHONE_NUMBER_ID>/calls
{"messaging_product":"whatsapp","to":"12185552828",// Номер телефона пользователя WhatsApp (звонящего)"action":"connect","session":{"sdp_type":"offer","sdp":"<}}

Если ошибок нет, вы получите успешный ответ:

{"messaging_product":"whatsapp","calls":["id":"wacid.HBgLMTIxODU1NTI4MjgVAgARGCAyODRQIAFRoA",// Идентификатор вызова WhatsApp]}

Примечание: Ответ с кодом ошибки 138006 указывает на отсутствие у пользователя WhatsApp разрешения на запрос вызова для этого номера компании.

Часть 3: Установление соединения с помощью сигнализации веб-перехватчика

После успешного инициирования нового вызова вы получите ответ веб-перехватчика Call Connect, содержащий ответ SDP от Cloud API. Затем ваша компания применит ответ SDP из этого веб-перехватчика к вашему стеку WebRTC для инициирования медиасоединения.

{"entry":[{"changes":[{"field":"calls","value":{"calls":[{"biz_opaque_callback_data":"TRx334DUDFTI4Mj",// Произвольная строка, передаваемая бизнесом для целей отслеживания"session":{"sdp_type":"answer","sdp":"},"from":"13175551399",// Номер телефона компании, с которой совершается звонок (вызывающий абонент)"connection":{"webrtc":{"sdp":"}},"id":"wacid.HBgLMTIxODU1NTI4MjgVAgARGCAyODRQIAFRoA",// Идентификатор вызова WhatsApp"to":"12185552828",// Номер телефона пользователя WhatsApp (звонящего)"event":"connect","timestamp":"1749196895","direction":"BUSINESS_INITIATED"}],"metadata":{// Идентификатор и отображаемый номер телефона компании, совершающей звонок (звонящего)"phone_number_id":"436666719526789","display_phone_number":"13175551399"},"messaging_product":"whatsapp"}}],"id":"366634483210360"// Идентификатор бизнес-аккаунта WhatsApp, связанный с номером телефона компании}],"object":"whatsapp_business_account"},

После этого вы получаете соответствующий веб-хук статуса, указывающий на то, что вызов проходит успешно, принятили отклонен:

{"entry":[{"changes":[{"field":"calls","value":{"statuses":[{"id":"wacid.HBgLMTIxODU1NTI4MjgVAgARGCAyODRQIAFRoA",// Идентификатор вызова WhatsApp"type":"call","status":"[ЗВОНОК|ПРИНЯТО|ОТКЛОНЕНО]",// Текущий статус вызова"timestamp":"1749197000","recipient_id":"12185552828"// Номер телефона пользователя WhatsApp (звонящий)}],"metadata":{// Идентификатор и отображаемый номер рабочего телефона, с которого совершается звонок (звонящий)"phone_number_id":"436666719526789","display_phone_number":"13175551399"},"messaging_product":"whatsapp"}}],"id":"366634483210360"// Идентификатор бизнес-аккаунта WhatsApp, связанный с номером телефона компании}],"object":"whatsapp_business_account"}

Часть 4: Ваша компания или пользователь WhatsApp завершает звонок

Вы или пользователь WhatsApp можете в любой момент завершить звонок.

Вы звоните на почту Для завершения вызова необходимо отправить следующий запрос в конечную точку:

ПОЧТА<PHONE_NUMBER_ID> /calls { "messaging_product": "whatsapp", "call_id": "wacid.HBgLMTIxODU1NTI4MjgVAgARGCAyODRQIAFRoA", // Идентификатор вызова WhatsApp "action" : "terminate" }

Если ошибок не обнаружено, вы получите подтверждение об успешном завершении операции:

{"success":true}

Когда компания или пользователь WhatsApp завершают вызов, вы получаете веб-хук "Завершение вызова":

{"object":"whatsapp_business_account","entry":[{"id":"366634483210360",// Идентификатор бизнес-аккаунта WhatsApp, связанный с номером телефона компании"changes":[{"value":{"messaging_product":"whatsapp","metadata":{// Идентификатор и отображаемый номер телефона компании, совершающей звонок (звонящий)"phone_number_id":"436666719526789","display_phone_number":"13175551399",},"calls":[{"id":"wacid.HBgLMTIxODU1NTI4MjgVAgARGCAyODRQIAFRoA","to":"12185552828",// The Номер телефона пользователя WhatsApp (звонящий)"от":"13175551399",// Рабочий номер телефона, с которого совершается звонок (звонящий)"событие":"завершение","направление":"BUSINESS_INITIATED","временная метка":"1749197480","статус":["Неудачно","Завершено"],"время начала":"1671644824",// Временная метка начала вызова в формате UNIX"время окончания":"1671644944",// Временная метка окончания вызова в формате UNIX"длительность":480// Длительность вызова в секундах}]},"поле":"звонки"}]}]}

Конечные точки для звонков, инициированных бизнесом

Инициировать звонок

Используйте этот конечный пункт для инициирования звонка пользователю WhatsApp, указав номер телефона и предложение WebRTC-звонка. Существует ограничение в 10000 инициированных новых звонков в течение 24 часов с одного корпоративного номера телефона.

Синтаксис запроса

POST <PHONE_NUMBER_ID>/calls

Заполнитель	Описание	Пример значения
`<PHONE_NUMBER_ID>` Целое число	Необходимый Идентификатор номера телефона компании, с которого вы инициируете новый звонок.	`106540352242922`

Текст запроса

{"messaging_product":"whatsapp","to":"14085551234","action":"connect","session":{"sdp_type":"offer","sdp":"<},"biz_opaque_callback_data":"0fS5cePMok"}

Параметры тела

Параметр	Описание	Пример значения
`к` Целое число	Необходимый Вызываемый номер (звонящий) Узнайте больше о форматировании телефонных номеров в Cloud API	`“17863476655”`
`действие` Нить	Необходимый Действие, выполняемое в отношении указанного идентификатора вызова. Значения могут быть `связаны` \| `предварительное принятие` \| `принятие` \| `отклонение` \| `завершение`	`"соединять"`
`сессия` JSON-объект	Необязательный Содержит тип протокола описания сессии (SDP) и язык описания. Требуется два значения: `sdp_type` — (Строка) Обязательный параметр «Предложение» обозначает предложение SDP `sdp` — (Строка) Обязательный параметр Информация SDP устройства на другом конце вызова. SDP должен соответствовать 8866.RFC Узнайте больше о протоколе описания сессии (SDP)⁠ Посмотреть примеры структур SDP	`"session":{"sdp_type":"offer","sdp":"<}`
`biz_opaque_callback_data` Нить	Необязательный Произвольная строка, которую можно передать в качестве параметра для целей отслеживания и регистрации. Любое приложение, подписанное на поле веб-перехватчика «звонки» в вашем аккаунте WhatsApp Business, может получить эту строку, поскольку она включена в `«звонки»` в последующей веб-перехватчика «Завершение вызова» . Облачный API не обрабатывает это поле. Максимальное количество символов: 512	`“0fS5cePMok”`

Ответ об успехе

{"messaging_product":"whatsapp","calls":[{"id":"wacid.ABGGFjFVU2AfAgo6V",}]}

Ответ с ошибкой

Возможные ошибки, которые могут возникнуть:

Неверный номер телефонаОшибки доступа/авторизацииОшибки проверки формата запроса, например, информация о соединении, SDP, ICEОшибки проверки SDPОшибки ограничения вызовов

Для получения дополнительной информации ознакомьтесь с кодами ошибок и рекомендациями по устранению неполадок при вызове API

Общие коды ошибок Cloud API можно посмотреть здесь

Завершить вызов

Используйте эту конечную точку для завершения активного вызова.

присутствует RTCP BYE в медиатракте

Когда пользователь WhatsApp завершает вызов, вам не нужно звонить на эту конечную точку. После успешного завершения вызова вы получите веб-перехватчик завершения вызова.

Синтаксис запроса

POST <PHONE_NUMBER_ID>/calls

Параметр	Описание	Пример значения
`<PHONE_NUMBER_ID>` Целое число	Необходимый Рабочий телефонный номер, с которого вы завершаете звонок. Узнайте больше о форматировании телефонных номеров в Cloud API	`18274459827`

Текст запроса

{"messaging_product":"whatsapp","call_id":"wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh","action":"terminate"}

Параметры тела

Параметр	Описание	Пример значения
`call_id` Нить	Необходимый Идентификатор телефонного звонка. При входящих звонках вы получаете идентификатор вызова от веб-перехватчика Call Connect, когда звонок инициирует пользователь WhatsApp.	`“wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh”`
`действие` Нить	Необходимый Действие, выполняемое в отношении указанного идентификатора вызова. Значения могут быть `связаны` \| `предварительное принятие` \| `принятие` \| `отклонение` \| `завершение`	`«прекратить»`

Ответ об успехе

{"messaging_product":"whatsapp","success":true}

Ответ с ошибкой

Возможные ошибки, которые могут возникнуть:

Неверный идентификатор вызоваНеверный номер телефонаПользователь WhatsApp уже завершил звонокВызов с отклонением уже выполняетсяОшибки доступа/авторизации

Общие коды ошибок Cloud API можно посмотреть здесь

Веб-хуки для инициированных бизнес-звонков

находится "calls" внутри "value" ответа вебхука "calls" содержит метаданные о звонке, которые используются для обработки каждого звонка, совершенного или принятого вашей компанией.

Чтобы получать веб-хуки Calling API, подпишитесь на поле веб-хука «calls».

Подробнее о веб-хуках Cloud API можно узнать здесь

Вызов веб-перехватчика

Вы получаете уведомление через веб-хук практически в режиме реального времени, когда звонок, инициированный вашей компанией, готов к соединению с пользователем WhatsApp ( ответ SDP).

Крайне важно, что веб-перехватчик содержит информацию, необходимую для установления соединения через WebRTC.

После получения веб-перехватчика Call Connect вы можете применить ответ SDP к вашему стеку WebRTC для инициирования медиасоединения.

{"object":"whatsapp_business_account","entry":[{"id":","changes":[{"value":{"messaging_product":"whatsapp","metadata":{"display_phone_number":"16315553601","phone_number_id":"},"контакты":[{"wa_id":"16315553602"}],"звонки":[{"id":"wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh","кому":"16315553601","от":"16315553602","событие":"подключение","временная метка":"1671644824","направление":"BUSINESS_INITIATED","сессия":{"sdp_type":"ответ","sdp":"<}}]},"field":"calls"}]}]}

Значения веб-хука для `"вызовов"`

Заполнитель	Описание
`идентификатор` Нить	Уникальный идентификатор для вызова
`к` Целое число	Вызываемый номер (звонящий)
`от` Целое число	Номер звонящего
`событие` Целое число	Событие вызова, о котором этот веб-перехватчик уведомляет подписчика
`метка времени` Целое число	Временная метка UNIX события веб-перехватчика
`направление` Нить	Направление совершаемого звонка. Может содержать либо: `BUSINESS_INITIATED —`для звонков, инициированных вашей компанией. `USER_INITIATED —`для звонков, инициированных пользователем WhatsApp.
`сессия` JSON-объект	Необязательный Содержит тип протокола описания сессии (SDP) и язык описания. Требуется два значения: `sdp_type` — (Строка) Обязательный параметр «Предложение» обозначает предложение SDP `sdp` — (Строка) Обязательный параметр Информация SDP устройства на другом конце вызова. SDP должен соответствовать 8866.RFC Узнайте больше о протоколе описания сессии (SDP)⁠ Посмотреть примеры структур SDP
`контакты` JSON-объект	`wa_id` — идентификатор вызываемого абонента в WhatsApp.

веб-перехватчик статуса вызова

Этот веб-перехватчик отправляется при следующих событиях вызова:

Звонок: Когда устройство пользователя WhatsApp начинает звонитьПринято: Когда пользователь WhatsApp принимает звонокОтклонено: Когда пользователь WhatsApp отклоняет звонок. В этом случае вы также получаете веб-хук завершения вызова

Здесь используется структура веб-хуков, аналогичная структуре веб-хуков статуса, применяемых для сообщений Cloud API.

{"object":"whatsapp_business_account","entry":[{"id":","changes":[{"value":{"messaging_product":"whatsapp","metadata":{"display_phone_number":"16315553601","phone_number_id":",},"statuses":[{"id":"wacid.ABGGFjFVU2AfAgo6V","timestamp":"1671644824","type":"call""status":"[RINGING|ACCEPTED|REJECTED]","recipient_id":"163155536021","biz_opaque_callback_data":"random_string",}]},"field":"calls"}]}]}

Узнайте больше о веб-хуках состояния Cloud API

Значения веб-хуков для `"статусов"`

Заполнитель	Описание
`идентификатор` Нить	Уникальный идентификатор для вызова
`метка времени` Целое число	Временная метка UNIX события веб-перехватчика
`recipient_id` Целое число	Номер телефона пользователя WhatsApp, принимающего звонок
`статус` Целое число	Текущий статус вызова. Возможные значения: `ЗВОНОК`: Инициированный компанией звонок поступает на абонента. `ПРИНЯТО`: Звонок, инициированный компанией, принят пользователем. `ОТКЛОНЕНО`: Звонок, инициированный представителем компании, отклонен пользователем.
`biz_opaque_callback_data` Нить	Произвольная строка, которую ваша компания передает в вызов для отслеживания и регистрации данных. Возвращается только в том случае, если предоставлено через запросы API Initiate New Call.

Вызов завершения веб-перехватчика

Уведомление через веб-хук отправляется всякий раз, когда вызов завершается по какой-либо причине, например, когда пользователь WhatsApp кладёт трубку или когда компания вызывает POST-запрос. конечная точка с действием завершения или отклонения.

{"object":"whatsapp_business_account","entry":[{"id":","changes":[{"value":{"messaging_product":"whatsapp","metadata":{"display_phone_number":"16505553602","phone_number_id":",},"calls":[{"id":"wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh","to":"16315553601","from":"16315553602","event":"terminate""direction":"BUSINESS_INITIATED","biz_opaque_callback_data":"random_string","timestamp":"1671644824","status":[FAILED | ЗАВЕРШЕНО],"start_time":"1671644824","end_time":"1671644944","duration":120}],"errors":[{"code": INT_CODE,"message":"ERROR_TITLE","href":"ERROR_HREF","error_data":{"details":"ERROR_DETAILS"}}]},"field":"calls"}]}]}

Значения веб-хука для `"вызовов"`

Заполнитель	Описание
`идентификатор` Нить	Уникальный идентификатор для вызова
`к` Целое число	Вызываемый номер (звонящий)
`от` Целое число	Номер звонящего
`событие` Целое число	Событие вызова, о котором этот веб-перехватчик уведомляет подписчика
`метка времени` Целое число	Временная метка UNIX события веб-перехватчика
`направление` Нить	Направление совершаемого звонка. Может содержать либо: `BUSINESS_INITIATED —`для звонков, инициированных вашей компанией. `USER_INITIATED —`для звонков, инициированных пользователем WhatsApp.
`время начала` Целое число	Временная метка UNIX, указывающая на начало звонка. Присутствует только тогда, когда на звонок ответил другой абонент.
`конец_времени` Целое число	Временная метка UNIX, отражающая момент завершения звонка. Присутствует только тогда, когда на звонок ответил другой абонент.
`продолжительность` Целое число	Продолжительность разговора в секундах. Присутствует только тогда, когда на звонок ответил другой абонент.
`biz_opaque_callback_data` Нить	Произвольная строка, которую ваша компания передает в вызов для отслеживания и регистрации данных. Возвращается только в том случае, если предоставлено через запрос API Initiate Call или запрос Accept Call.
`ошибки.код` Целое число	Объект `errors` присутствует только для неудачных вызовов, если доступна информация об ошибке. Code — это один из кодов ошибок вызова.

Обзор SDP и примеры структур

Протокол описания сеанса (SDP) — это текстовый формат, используемый для описания характеристик мультимедийных сеансов, таких как голосовые и видеозвонки, в приложениях для связи в реальном времени. SDP предоставляет стандартизированный способ описания медиапотоков сеанса. Это включает тип медиафайлов, кодеки, протоколы и параметры для установления и управления сеансом.

В контексте WebRTC протокол SDP используется для согласования параметров передачи данных между отправителем и получателем, позволяя им согласовать специфику обмена данными.

Ознакомьтесь с примерами структур SDP для звонков, инициируемых бизнесом

Звонки, инициированные бизнесом | Документация для разработчиков