Вызовы, инициированные пользователем | Документация для разработчиков
Звонки, инициированные пользователем
Обновлено: 13 ноября 2025 г
Обзор
API для звонков поддерживает прием звонков, совершаемых пользователями WhatsApp на ваш бизнес.
Ваша компания сама определяет время приема звонков, устанавливая рабочие часы и исключая возможность приема звонков в праздничные дни .
Соответствие потребительских устройств критериям
В настоящее время API для бизнес-звонков WhatsApp позволяет принимать звонки как с основного, так и с дополнительных телефонов iPhone или Android пользователя.
Основное устройство — это главное устройство пользователя, как правило, мобильный телефон, которое хранит авторитетное состояние учетной записи пользователя. Оно имеет полный доступ к истории сообщений и основным функциям. В любой момент времени на одну учетную запись пользователя приходится ровно одно основное устройство.
Вспомогательные устройства — это дополнительные устройства, зарегистрированные в учетной записи пользователя, которые могут работать параллельно с основным устройством. Примеры включают веб-клиенты, настольные приложения, планшеты и умные очки. Вспомогательные устройства имеют доступ к части или всей истории сообщений и основным функциям, но их возможности ограничены по сравнению с основным устройством. Для вызовов через Cloud API поддерживаются только вспомогательные устройства iPhone и Android для инициированных пользователем вызовов .
Функциональность разрешения обратного вызова на сопутствующих устройствах
Для компаний, у которых функция обратного вызова , эта функциональность пока не поддерживается на сопутствующих устройствах.
Предварительные требования
Прежде чем начать совершать звонки по инициативе пользователя, убедитесь в следующем:
Диаграмма последовательности вызовов

Процесс инициированного пользователем вызова
Часть 1: Пользователь WhatsApp звонит в вашу компанию со своего клиентского приложения
Когда пользователь WhatsApp звонит в вашу компанию, срабатывает веб-перехватчик Call Connect с
предложением SDP :{ "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.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh", // Идентификатор звонка WhatsApp "to": "16315553601", // Номер телефона пользователя WhatsApp (звонящий) "from": "13175551399", "event": "connect", "timestamp": "1671644824", "session": { "sdp_type": "offer", "sdp": "<<RFC 8866 SDP> >" } } ] }, "field": "calls" } ] } ] }
Часть 2: Ваша компания предварительно принимает звонок (рекомендуется)
При предварительном принятии входящего вызова вы позволяете установить медиасоединение с вызывающим абонентом, прежде чем пытаться передать медиаконтент через это соединение.
Рекомендуется предварительно принимать звонки, поскольку это способствует более быстрому установлению соединения и позволяет избежать проблем с искажением звука .
Для предварительного подтверждения необходимо позвонить в
почтовое отделение (POST). /вызывает конечную точку с call_id из предыдущего веб-хука, действием pre -accept и SDP-ответом :ПОЧТА<PHONE_NUMBER_ID> /calls { "messaging_product": "whatsapp", "call_id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh", "action": "pre_accept", "session": { "sdp_type": "answer" "sdp": "<<RFC 8866 SDP> >" } }
Если ошибок не обнаружено, вы получите подтверждение об успешном завершении
{ "success" : true }
Часть 3: Ваша компания принимает вызов после установления соединения WebRTC
После установления WebRTC-соединения на вашей стороне вы можете принять вызов.
После принятия вызова дождитесь получения
200 OK от конечной точки. Передача медиаконтента начнется немедленно, поскольку соединение было установлено до установления связи.Теперь вы можете позвонить на
почту. Для принятия вызова используйте конечную точку /calls ПОЧТА<PHONE_NUMBER_ID> /calls { "messaging_product": "whatsapp", "call_id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh", "action": "accept", "session" : { "sdp_type" : "answer", "sdp" : "<<RFC 8866 SDP> >" }, }
Часть 4: Ваша компания или пользователь WhatsApp завершает звонок
И компания, и пользователь WhatsApp могут в любой момент завершить звонок.
Вы звоните на
почту Для завершения вызова используйте конечную точку /calls ПОЧТА<PHONE_NUMBER_ID> /calls { "messaging_product": "whatsapp", "call_id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh", "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.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh", "to": "16315553601", // Номер телефона пользователя WhatsApp (звонящий) "from": "13175551399", // Рабочий номер телефона, с которого совершается звонок (звонящий) "event": "terminate", "direction": "USER_INITIATED", "timestamp": "1749197480", "status": ["Failed", "Completed"], "start_time": "1671644824", // Временная метка начала вызова в UNIX "end_time": "1671644944", // Временная метка окончания вызова в UNIX "duration": 480 // Длительность вызова в секундах } ] }, "field": "calls" } ] } ] }
Конечные точки для инициированных пользователем звонков
Предварительное принятие звонка
При предварительном принятии входящего вызова вы позволяете установить медиасоединение с вызывающим абонентом, прежде чем пытаться передать медиаконтент через это соединение.
При последующем вызове конечной точки приема вызова передача медиаконтента начинается немедленно, поскольку соединение уже установлено.
Рекомендуется предварительно принимать звонки, поскольку это способствует более быстрому установлению соединения и позволяет избежать проблем с искажением звука .
веб-хука Call Connect есть примерно от 30 до 60 секунд, чтобы принять телефонный звонок. Если компания не отвечает, звонок завершается на стороне пользователя WhatsApp с уведомлением «Не отвечено», и вам отправляется веб-хук завершения вызова
Примечание: Поскольку соединение WebRTC устанавливается до вызова конечной точки Accept Call , убедитесь, что передача медиаданных происходит только после получения ответа 200 OK.
Если передача медиаконтента начинается слишком рано, звонящий пропустит первые несколько слов разговора. Если передача медиаконтента начинается слишком поздно, звонящий услышит тишину.
Синтаксис запроса
ПОЧТА
| Заполнитель | Описание | Пример значения |
|---|---|---|
<PHONE_NUMBER_ID>Целое число | Необходимый Номер телефона компании, с которого вы используете функции Calling API. | +12784358810 |
Текст запроса
{ "messaging_product": "whatsapp", "call_id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh", "action": "pre_accept", "session" : { "sdp_type" : "answer", "sdp" : "<<RFC 8866 SDP> >" } }
Параметры тела
| Параметр | Описание | Пример значения |
|---|---|---|
call_idНить | Необходимый Идентификатор телефонного звонка. При входящих звонках вы получаете идентификатор вызова от веб-перехватчика Call Connect, когда звонок инициирует пользователь WhatsApp. | “wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh” |
действиеНить | Необязательный Действие, выполняемое в отношении указанного идентификатора вызова. Значения могут быть связаны | предварительное принятие | принятие | отклонение | завершение | “предварительное_принятие” |
сессияJSON-объект | Необязательный Содержит тип протокола описания сессии (SDP) и язык описания. Требуется два значения: sdp_type — ( Строка ) Обязательный параметр«Предложение» обозначает предложение SDP sdp — ( Строка ) Обязательный параметр | |
Ответ об успехе
{ "messaging_product": "whatsapp", "success" : true }
Ответ с ошибкой
Возможные ошибки, которые могут возникнуть:
идентификатор вызоваНеверный номер телефонаОшибка, связанная с вашим способом оплатыНеверные данные соединения, например, SDP или ICEПринять/отклонить уже находящийся в процессе/завершенный/неудачный вызовОшибки доступа/авторизацииПринять звонок
Используйте эту конечную точку для подключения к вызову, указав SDP оператора колл-центра.
веб-хука Call Connect у вас есть примерно от 30 до 60 секунд, чтобы принять телефонный звонок. Если ваша компания не отвечает, звонок завершается на стороне пользователя WhatsApp с уведомлением «Не отвечено», и вам отправляется веб-хук Terminate
Синтаксис запроса
ПОЧТА
| Заполнитель | Описание | Пример значения |
|---|---|---|
<PHONE_NUMBER_ID>Целое число | Необходимый Номер телефона компании, с которого вы используете функции Calling API. | +12784358810 |
Текст запроса
{ "messaging_product": "whatsapp", "call_id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh", "action": "accept", "session" : { "sdp_type" : "answer", "sdp" : "<<RFC 8866 SDP> >" }, "biz_opaque_callback_data": "random_string" }
Параметры тела
| Параметр | Описание | Пример значения |
|---|---|---|
call_idНить | Необходимый Идентификатор телефонного звонка. При входящих звонках вы получаете идентификатор вызова от веб-перехватчика Call Connect, когда звонок инициирует пользователь WhatsApp. | “wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh” |
действиеНить | Необязательный Действие, выполняемое в отношении указанного идентификатора вызова. Значения могут быть связаны | предварительное принятие | принятие | отклонение | завершение | "принимать" |
сессияJSON-объект | Необязательный Содержит тип протокола описания сессии (SDP) и язык описания. Требуется два значения: sdp_type — ( Строка ) Обязательный параметр«Предложение» обозначает предложение SDP sdp — ( Строка ) Обязательный параметр | |
biz_opaque_callback_dataНить | Необязательный Произвольная строка, которую можно передать в качестве параметра для целей отслеживания и регистрации. Любое приложение, подписанное на поле веб-перехватчика «звонки» в вашем аккаунте WhatsApp Business, может получить эту строку, поскольку она включена в calls в последующей веб-перехватчика Terminate .Cloud API не обрабатывает это поле, а просто возвращает его в составе веб-перехватчика Terminate . Максимальное количество символов: 512 | “8huas8d80nn” |
Ответ об успехе
{ "messaging_product": "whatsapp", "success" : true }
Ответ с ошибкой
Возможные ошибки, которые могут возникнуть:
идентификатор вызоваНеверный номер телефонаОшибка, связанная с вашим способом оплатыНеверные данные соединения, например, SDP или ICEПринять/отклонить уже находящийся в процессе/завершенный/неудачный вызовОшибки доступа/авторизацииОтвет SDP, предоставленный в запросе accept, не совпадает с ответом SDP, предоставленным в конечной точке pre-Accept для того же идентификатора вызова.Отклонить вызов
Используйте этот адрес электронной почты, чтобы отклонить вызов.
веб-хука Call Connect у вас есть примерно от 30 до 60 секунд, чтобы принять телефонный звонок. Если компания не отвечает, звонок завершается на стороне пользователя WhatsApp с уведомлением «Не отвечено», и вам отправляется веб-хук завершения вызова
Синтаксис запроса
ПОЧТА
| Заполнитель | Описание | Пример значения |
|---|---|---|
<PHONE_NUMBER_ID>Целое число | Необходимый Номер телефона компании, с которого вы используете функции Calling API. | +12784358810 |
Текст запроса
{ "messaging_product": "whatsapp", "call_id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh", "action": "reject" }
Параметры тела
| Параметр | Описание | Пример значения |
|---|---|---|
call_idНить | Необходимый Идентификатор телефонного звонка. При входящих звонках вы получаете идентификатор вызова от веб-перехватчика Call Connect, когда звонок инициирует пользователь WhatsApp. | “wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh” |
действиеНить | Необязательный Действие, выполняемое в отношении указанного идентификатора вызова. Значения могут быть связаны | предварительное принятие | принятие | отклонение | завершение | "отклонять" |
Ответ об успехе
{ "messaging_product": "whatsapp", "success" : true }
Ответ с ошибкой
Возможные ошибки, которые могут возникнуть:
идентификатор вызоваНеверный номер телефонаПринять/отклонить уже находящийся в процессе/завершенный/неудачный вызовОшибки доступа/авторизацииЗавершить вызов
Используйте эту конечную точку для завершения активного вызова.
в медиатракте присутствует
RTCP BYE Когда пользователь WhatsApp завершает вызов, вам не нужно звонить на эту конечную точку. После успешного завершения вызова вам будет отправлен веб-хук завершения вызова
Синтаксис запроса
ПОЧТА
| Заполнитель | Описание | Пример значения |
|---|---|---|
<PHONE_NUMBER_ID>Целое число | Необходимый Номер телефона компании, с которого вы используете функции Calling API. | +12784358810 |
Текст запроса
{ "messaging_product": "whatsapp", "call_id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh", "action": "terminate" }
Параметры тела
| Параметр | Описание | Пример значения |
|---|---|---|
call_idНить | Необходимый Идентификатор телефонного звонка. При входящих звонках вы получаете идентификатор вызова от веб-перехватчика Call Connect, когда звонок инициирует пользователь WhatsApp. | “wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh” |
действиеНить | Необязательный Действие, выполняемое в отношении указанного идентификатора вызова. Значения могут быть связаны | предварительное принятие | принятие | отклонение | завершение | «прекратить» |
Ответ об успехе
{ "messaging_product": "whatsapp", "success" : true }
Ответ с ошибкой
Возможные ошибки, которые могут возникнуть:
идентификатор вызоваНеверный номер телефонаПринять/отклонить уже находящийся в процессе/завершенный/неудачный вызовВызов с отклонением уже выполняетсяОшибки доступа/авторизацииВеб-хуки для инициированных пользователем звонков
внутри
"value" ответа вебхука находится "calls" "calls" содержит метаданные о звонке, которые используются для обработки каждого звонка, полученного вашей компанией.Чтобы получать веб-хуки Calling API, подпишитесь на поле веб-хука calls.
Веб-перехватчик вызова Connect
Уведомление через веб-хук отправляется практически в режиме реального времени, когда звонок, инициированный вашей компанией, готов к соединению с пользователем WhatsApp (
ответ SDP ).Крайне важно, что веб-перехватчик содержит информацию, необходимую для установления соединения через WebRTC.
После получения веб-перехватчика Call Connect вы можете применить
ответ SDP к вашему стеку WebRTC, чтобы инициировать медиасоединение.{ "object": "whatsapp_business_account", "entry": [ { "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID> ", "изменения": [ { "значение": { "messaging_product": "whatsapp", "метаданные": { "display_phone_number": "16315553601", "phone_number_id": "<PHONE_NUMBER_ID> " }, "контакты": [ { "профиль": { "имя": "<CALLEE_NAME> " }, "wa_id": "16315553602" } ], "calls": [ { "id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh", "to": "16315553601", "from": "16315553602", "event": "connect", "timestamp": "1671644824", "direction": "USER_INITIATED", "deeplink_payload": "deeplink_payload", "cta_payload": "cta_payload", "session": { "sdp_type": "offer", "sdp": "<<RFC 8866 SDP> >" } } ] }, "field": "calls" } ] } ] }
Значения веб-хуков для "вызовов"
| Заполнитель | Описание |
|---|---|
идентификаторНить | Уникальный идентификатор для вызова |
кЦелое число | Вызываемый номер (звонящий) |
отЦелое число | Номер звонящего |
событиеЦелое число | Событие вызова, о котором этот веб-перехватчик уведомляет подписчика |
метка времениЦелое число | Временная метка UNIX события веб-перехватчика |
направлениеНить | Направление совершаемого звонка. Может содержать либо: BUSINESS_INITIATED — для звонков, инициированных вашей компанией.USER_INITIATED — для звонков, инициированных пользователем WhatsApp. |
deeplink_payloadНить | Произвольная строка, указанная в biz_payload при вызове по диплинку. Будет возвращена только в том случае, если вызов был инициирован с диплинка с таким параметром.Дополнительные сведения см. в разделе «Сообщения кнопки вызова и прямые ссылки» |
cta_payloadНить | Произвольная строка, указанная в полезной нагрузки кнопки вызова. Будет возвращена только в том случае, если вызов был инициирован с помощью кнопки вызова с указанной полезной нагрузкой.Дополнительные сведения см. в разделе «Сообщения кнопки вызова и прямые ссылки» |
сессияJSON-объект | Необязательный Содержит тип протокола описания сессии (SDP) и язык описания. Требуется два значения: sdp_type — ( Строка ) Обязательный параметр«Предложение» обозначает предложение SDP sdp — ( Строка ) Обязательный параметр |
контактыJSON-объект | Информация о звонящем. Содержит два значения: имя — имя профиля WhatsApp собеседника.wa_id — идентификатор вызываемого абонента в WhatsApp. |
Вызов веб-перехватчика "Завершение"
Уведомление через веб-хук отправляется всякий раз, когда вызов завершается по какой-либо причине, например, когда пользователь WhatsApp кладёт трубку или когда компания вызывает
POST-запрос. /вызывает конечную точку с действием завершения или отклонения .{ "object": "whatsapp_business_account", "entry": [ { "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID> ", "изменения": [ { "значение": { "messaging_product": "whatsapp", "метаданные": { "display_phone_number": "16505553602", "phone_number_id": "<PHONE_NUMBER_ID> ", }, "вызовы": [ { "id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh", "to": "16315553601", "from": "16315553602", "event": "terminate" "direction": "USER_INITIATED", "deeplink_payload": "deeplink_payload", "cta_payload": "cta_payload", "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. |
deeplink_payloadНить | Произвольная строка, указанная в biz_payload при вызове по диплинку. Будет возвращена только в том случае, если вызов был инициирован с диплинка с таким параметром.Дополнительные сведения см. в разделе «Сообщения кнопки вызова и прямые ссылки» |
cta_payloadНить | Произвольная строка, указанная в полезной нагрузки кнопки вызова. Будет возвращена только в том случае, если вызов был инициирован с помощью кнопки вызова с указанной полезной нагрузкой.Дополнительные сведения см. в разделе «Сообщения кнопки вызова и прямые ссылки» |
время началаЦелое число | Временная метка UNIX, указывающая на начало звонка. Присутствует только тогда, когда на звонок ответил другой абонент. |
конец_времениЦелое число | Временная метка UNIX, отражающая момент завершения звонка. Присутствует только тогда, когда на звонок ответил другой абонент. |
продолжительностьЦелое число | Продолжительность разговора в секундах. Присутствует только тогда, когда на звонок ответил другой абонент. |
biz_opaque_callback_dateНить | Произвольная строка, которую ваша компания передает в вызов для отслеживания и регистрации данных. Возврат средств возможен только в том случае, если запрос на инициирование звонка или запрос на принятие звонка |
ошибки.кодЦелое число | Объект errors присутствует только для неудачных вызовов, если доступна информация об ошибке. Code — это один из кодов ошибок вызова. |
Поддержка двухтонального многочастотного тона (DTMF)
Клавиатура, предоставляемая API вызовов, поддерживает только сценарии использования DTMF.
Она не поддерживает звонки между абонентами и не изменяет никаких других функций совершения звонков. Например, с помощью клавиатуры нельзя набрать номер и инициировать звонок или отправить сообщение в WhatsApp.
API WhatsApp Business Calling поддерживает DTMF-тона, что позволит приложениям BSP поддерживать системы на основе IVR.
Пользователи WhatsApp могут нажимать кнопки с тонами в своем клиентском приложении, и эти DTMF-тона будут передаваться в поток WebRTC RTP, устанавливаемый в рамках VoIP-соединения.
Наш поток WebRTC соответствует стандарту RFC 4733 для передачи цифр DTMF через полезную нагрузку RTP.
Для передачи DTMF-цифр отсутствует веб-хук.
Частота тактирования DTMF
В наших SDP поддерживается только частота обновления 8000 МГц. Для вызовов, инициированных пользователем, наше предложение SDP включает только частоту обновления 8000 МГц. Для вызовов, инициированных бизнес-процессами, ваше предложение SDP должно содержать частоту обновления 8000 МГц. Даже если она отсутствует, API все равно будет использовать частоту обновления 8000 МГц для полезной нагрузки типа 126.
Пакеты RTP, представляющие события DTMF, будут использовать ту же базовую дату метки времени и базовую дату порядкового номера, что и обычные аудиопакеты. Поэтому вам не нужно беспокоиться о различиях в тактовых частотах между аудиопакетами и пакетами DTMF. Поле длительности пакета DTMF рассчитывается с использованием 8000 единиц тактовой частоты.
API не поддерживает частоту тактирования 48000 Гц для DTMF.
Отправка DTMF-сигналов через пользовательский WhatsApp-клиент
В приложениях WhatsApp добавлена клавиатура для звонков на бизнес-телефонные номера, использующие CloudAPI. Пользователь WhatsApp может нажимать кнопки на клавиатуре и отправлять DTMF-сигналы.

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