Вызовы, инициированные пользователем | Документация для разработчиков
Звонки, инициированные пользователем
Обновлено: 13 ноября 2025 г
Обзор
API для звонков поддерживает прием звонков, совершаемых пользователями WhatsApp на ваш бизнес.
Ваша компания сама определяет время приема звонков, устанавливая рабочие часы и исключая возможность приема звонков в праздничные дни .
Соответствие потребительских устройств критериям
В настоящее время API для бизнес-звонков WhatsApp позволяет принимать звонки как с основного, так и с дополнительных телефонов iPhone или Android пользователя.
Основное устройство — это главное устройство пользователя, как правило, мобильный телефон, которое хранит авторитетное состояние учетной записи пользователя. Оно имеет полный доступ к истории сообщений и основным функциям. В любой момент времени на одну учетную запись пользователя приходится ровно одно основное устройство.
Вспомогательные устройства — это дополнительные устройства, зарегистрированные в учетной записи пользователя, которые могут работать параллельно с основным устройством. Примеры включают веб-клиенты, настольные приложения, планшеты и умные очки. Вспомогательные устройства имеют доступ к части или всей истории сообщений и основным функциям, но их возможности ограничены по сравнению с основным устройством. Для вызовов через Cloud API поддерживаются только вспомогательные устройства iPhone и Android для инициированных пользователем вызовов .
Функциональность разрешения обратного вызова на сопутствующих устройствах
Для компаний, у которых функция обратного вызова , эта функциональность пока не поддерживается на сопутствующих устройствах.
Предварительные требования
Прежде чем начать совершать звонки по инициативе пользователя, убедитесь в следующем:
Подпишитесь на поле веб-перехватчика вызововВключите функции API для звонков на вашем рабочем телефонном номере
Диаграмма последовательности вызовов
Конечные точки для инициированных пользователем звонков
Предварительное принятие звонка
При предварительном принятии входящего вызова вы позволяете установить медиасоединение с вызывающим абонентом, прежде чем пытаться передать медиаконтент через это соединение.
При последующем вызове конечной точки приема вызова передача медиаконтента начинается немедленно, поскольку соединение уже установлено.
Рекомендуется предварительно принимать звонки, поскольку это способствует более быстрому установлению соединения и позволяет избежать проблем с искажением звука .
веб-хука Call Connect есть примерно от 30 до 60 секунд, чтобы принять телефонный звонок. Если компания не отвечает, звонок завершается на стороне пользователя WhatsApp с уведомлением «Не отвечено», и вам отправляется веб-хук завершения вызова
Примечание: Поскольку соединение WebRTC устанавливается до вызова конечной точки Accept Call , убедитесь, что передача медиаданных происходит только после получения ответа 200 OK.
Если передача медиаконтента начинается слишком рано, звонящий пропустит первые несколько слов разговора. Если передача медиаконтента начинается слишком поздно, звонящий услышит тишину.
Параметры тела
| Параметр | Описание | Пример значения |
|---|---|---|
call_idНить |
Необходимый
Идентификатор телефонного звонка. При входящих звонках вы получаете идентификатор вызова от веб-перехватчика Call Connect, когда звонок инициирует пользователь WhatsApp. |
“wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh” |
действиеНить |
Необязательный
Действие, выполняемое в отношении указанного идентификатора вызова. Значения могут быть связаны | предварительное принятие | принятие | отклонение | завершение |
“предварительное_принятие” |
сессияJSON-объект |
Необязательный
Содержит тип протокола описания сессии (SDP) и язык описания. Требуется два значения:
sdp_type — ( Строка ) Обязательный параметр«Предложение» обозначает предложение SDP
sdp — ( Строка ) Обязательный параметр |
Ответ с ошибкой
Возможные ошибки, которые могут возникнуть:
Неверный идентификатор вызоваНеверный номер телефонаОшибка, связанная с вашим способом оплатыНеверные данные соединения, например, SDP или ICEПринять/отклонить уже находящийся в процессе/завершенный/неудачный вызовОшибки доступа/авторизации
Принять звонок
Используйте эту конечную точку для подключения к вызову, указав SDP оператора колл-центра.
веб-хука Call Connect у вас есть примерно от 30 до 60 секунд, чтобы принять телефонный звонок. Если ваша компания не отвечает, звонок завершается на стороне пользователя WhatsApp с уведомлением «Не отвечено», и вам отправляется веб-хук Terminate
Параметры тела
Ответ с ошибкой
Возможные ошибки, которые могут возникнуть:
Неверный идентификатор вызоваНеверный номер телефонаОшибка, связанная с вашим способом оплатыНеверные данные соединения, например, SDP или ICEПринять/отклонить уже находящийся в процессе/завершенный/неудачный вызовОшибки доступа/авторизацииОтвет SDP, предоставленный в запросе accept, не совпадает с ответом SDP, предоставленным в конечной точке pre-Accept для того же идентификатора вызова.
Отклонить вызов
Используйте этот адрес электронной почты, чтобы отклонить вызов.
веб-хука Call Connect у вас есть примерно от 30 до 60 секунд, чтобы принять телефонный звонок. Если компания не отвечает, звонок завершается на стороне пользователя WhatsApp с уведомлением «Не отвечено», и вам отправляется веб-хук завершения вызова
Параметры тела
| Параметр | Описание | Пример значения |
|---|---|---|
call_idНить |
Необходимый
Идентификатор телефонного звонка. При входящих звонках вы получаете идентификатор вызова от веб-перехватчика Call Connect, когда звонок инициирует пользователь WhatsApp. |
“wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh” |
действиеНить |
Необязательный
Действие, выполняемое в отношении указанного идентификатора вызова. Значения могут быть связаны | предварительное принятие | принятие | отклонение | завершение |
"отклонять" |
Ответ с ошибкой
Возможные ошибки, которые могут возникнуть:
Неверный идентификатор вызоваНеверный номер телефонаПринять/отклонить уже находящийся в процессе/завершенный/неудачный вызовОшибки доступа/авторизации
Завершить вызов
Используйте эту конечную точку для завершения активного вызова.
в медиатракте присутствует
RTCP BYE Когда пользователь WhatsApp завершает вызов, вам не нужно звонить на эту конечную точку. После успешного завершения вызова вам будет отправлен веб-хук завершения вызова
Параметры тела
| Параметр | Описание | Пример значения |
|---|---|---|
call_idНить |
Необходимый
Идентификатор телефонного звонка. При входящих звонках вы получаете идентификатор вызова от веб-перехватчика Call Connect, когда звонок инициирует пользователь WhatsApp. |
“wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh” |
действиеНить |
Необязательный
Действие, выполняемое в отношении указанного идентификатора вызова. Значения могут быть связаны | предварительное принятие | принятие | отклонение | завершение |
«прекратить» |
Ответ с ошибкой
Возможные ошибки, которые могут возникнуть:
Неверный идентификатор вызоваНеверный номер телефонаПринять/отклонить уже находящийся в процессе/завершенный/неудачный вызовВызов с отклонением уже выполняетсяОшибки доступа/авторизации
Веб-хуки для инициированных пользователем звонков
внутри
"value" ответа вебхука находится "calls" "calls" содержит метаданные о звонке, которые используются для обработки каждого звонка, полученного вашей компанией.Чтобы получать веб-хуки Calling API, подпишитесь на поле веб-хука calls.
Вызов веб-перехватчика "Завершение"
Уведомление через веб-перехватчик отправляется всякий раз, когда вызов завершается по какой-либо причине, например, когда пользователь WhatsApp кладет трубку или когда компания вызывает конечную точку с действием «
завершить» или «отклонить» .Значения веб-хуков для "вызовов"
| Заполнитель | Описание |
|---|---|
идентификаторНить |
Уникальный идентификатор для вызова |
кЦелое число |
Вызываемый номер (звонящий) |
отЦелое число |
Номер звонящего |
событиеЦелое число |
Событие вызова, о котором этот веб-перехватчик уведомляет подписчика |
метка времениЦелое число |
Временная метка 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 используется для согласования параметров передачи данных между отправителем и получателем, позволяя им согласовать специфику обмена данными.
Комментарии отсутствуют
Комментарии отсутствуют