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

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

Обновлено: 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.

Теперь вы можете позвонить на почту. /calls со следующим телом запроса:

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 можете в любой момент завершить звонок.

Вы звоните на почту Для завершения вызова используйте конечную точку /calls

ПОЧТА<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 должен соответствовать RFC 8866 . Узнайте больше о протоколе описания сессии (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 можно посмотреть здесь

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

внутри "value" ответа вебхука находится "calls" "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" , "to" : "16315553601" , "from" : "16315553602" , "event" : "connect" , "timestamp" : "1671644824" , "direction" : "BUSINESS_INITIATED" , "session" : { "sdp_type" : "answer" , "sdp" : "< >" } } ] }, "field" : "calls" } ] } ] }

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

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

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