Настройка параметров вызовов | Документация для разработчиков
Настройка параметров вызовов
Обновлено: 23 марта 2026 г
Функция звонков по умолчанию отключена для корпоративного телефонного номера
Используйте
POST / /settings для включения функций Calling API для корпоративного телефонного номера.Право на совершение звонков
Для использования функций Calling API ваша компания должна установить лимит на количество инициированных компанией разговоров не менее 2000 в течение 24 часов.
При тестировании интеграции звонков WhatsApp с использованием общедоступных тестовых номеров (PTN) и тестовых учетных записей ограничения API звонков снимаются.
Обзор
Используйте эти конечные точки для просмотра и настройки параметров вызовов для API бизнес-звонков WhatsApp.
Также можно настроить протокол инициации сессии (SIP) для сигнализации вызовов вместо использования вызовов конечных точек Graph API и веб-хуков.
Настройка/обновление параметров звонков по корпоративному телефонному номеру
Используйте этот конечный пункт для обновления настроек вызовов для отдельного корпоративного телефонного номера.
Клиенты WhatsApp отображают последние настройки вызовов
После обновления настроек звонков пользователям WhatsApp может потребоваться до 7 дней, чтобы изменения вступили в силу. Большинство пользователей обновляют настройки гораздо быстрее. Вы можете принудительно обновить настройки в WhatsApp, открыв окно чата в режиме «Бизнес» и перейдя на страницу информации о чате. Независимо от поведения клиента WhatsApp, семантика настроек по-прежнему учитывается на стороне сервера.
Синтаксис запроса
POST /< PHONE_NUMBER_ID >/ настройкиПараметры конечной точки
| Заполнитель | Описание | Пример значения |
|---|---|---|
<PHONE_NUMBER_ID>Целое число | Необходимый Идентификатор номера корпоративного телефона, для которого вы обновляете настройки API вызовов. | 106540352242922 |
Текст запроса
{
"calling"
: { "status"
: "ENABLED" , "call_icon_visibility"
: "DEFAULT" , "call_icons"
: { "restrict_to_user_countries"
: [ "US"
, "BR"
]
},
"call_hours"
: { "status"
: "ENABLED" , "timezone_id"
: "America/Manaus" , "weekly_operating_hours"
: [ {
"day_of_week"
: "MONDAY" , "open_time"
: "0400" , "close_time"
: "1020" },
{
"day_of_week"
: "TUESDAY" , "open_time"
: "0108" , "close_time"
: "1020" }
],
"holiday_schedule"
: [ {
"date"
: "2026-01-01" , "start_time"
: "0000" , "end_time"
: "2359" }
]
},
"callback_permission_status"
: "ENABLED" , "sip"
: { "status"
: "ENABLED | DISABLED (default)" , "servers"
: [ {
"hostname"
: SIP_SERVER_HOSTNAME, "port"
: SIP_SERVER_PORT, "request_uri_user_params"
: { "KEY1"
: "VALUE1" , "KEY2"
: "VALUE2" }
}
]
},
"audio"
: { "additional_codecs"
: [ "PCMA" , "PCMU" ] }
}
}
Параметры тела
| Параметр | Описание | Пример значения |
|---|---|---|
статусНить | Необязательный Включить или отключить API для звонков для указанного номера телефона компании. | "ВКЛЮЧЕНО""НЕПОЛНОЦЕННЫЙ" |
call_icon_visibilityНить | Необязательный Настройте отображение значка кнопки вызова WhatsApp для пользователей при общении с компанией. | |
call_iconsНить | Необязательный Настройте отображение значка кнопки вызова WhatsApp для пользователей при общении с компанией. | |
часы звонковJSON-объект | Необязательный Позволяет задавать и активировать параметры обработки входящих вызовов в зависимости от вашего часового пояса, рабочего времени и расписания праздников. Все ранее заданные значения в параметре call_hours будут заменены значениями, переданными в теле запроса этого API-вызова. | |
callback_permission_statusНить | Необязательный Настройте, будет ли пользователю WhatsApp запрашиваться разрешение на совершение звонка после звонка в вашу компанию. Примечание: Запрос на разрешение вызова инициируется как при пропущенном, так и при установленном соединении. | "ВКЛЮЧЕНО""НЕПОЛНОЦЕННЫЙ" |
глотокJSON-объект | Необязательный Настройте сигнализацию вызовов с помощью протокола инициации сигнала (SIP). Примечание: При включенном протоколе SIP вы не сможете использовать конечные точки, связанные с вызовами, и не будете получать веб-хуки, связанные с вызовами. | |
аудиоJSON-объект | Необязательный Настройте параметры аудиокодека для звонков. Кодек Opus используется по умолчанию и всегда присутствует. | "audio" |
Статус вызова
Если
статуса установлен в значение «ВКЛЮЧЕНО» , функции вызова для рабочего номера телефона становятся доступны. Приложения WhatsApp будут отображать значок кнопки вызова как в рабочем чате, так и в профиле рабочего чата.Если
статуса присвоено значение «ОТКЛЮЧЕНО» , функции вызова отключаются значок кнопки вызова не отображается ни в деловом чате, ни в профиле делового чата Обновление
статуса будет обновлять значок кнопки вызова в существующих деловых чатах практически в режиме реального времени, если номер телефона компании есть в контактах пользователя WhatsApp.В противном случае обновления предоставляются в режиме реального времени ограниченному числу пользователей, ведущих диалог с компанией, и становятся доступными для остальных участников диалога.
Если для номера компании включены функции Calling API, вы все равно можете выбрать, отображать ли значок кнопки вызова или нет, используя
call_icon_visibility . Примечание: отключение видимости значка кнопки вызова не отключает возможность пользователя WhatsApp совершать незапрошенные звонки в вашу компанию.Для поддерживаемых опций поведение следующее:
ПО УМОЛЧАНИЮЗначок кнопки «Вызов» будет отображаться в строке меню чата и на странице информации о компании, что позволит пользователям WhatsApp совершать незапрошенные звонки в компанию.

ОТКЛЮЧИТЬ ВСЕЗначок кнопки вызова скрыт в строке меню чата и на странице информации о компании, а все остальные точки входа вне чата также отключены. Потребители не могут совершать незапрошенные звонки в компанию.
Ваша компания по-прежнему может отправлять интерактивные сообщения или шаблонные сообщения с помощью кнопки призыва к действию (CTA) через Calling API.

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

Значки вызова
С помощью
call_icons вы можете указать страны, в которых должны отображаться эти значки."call_icons"
: { "restrict_to_user_countries"
: [ "US"
, "BR"
]
}
| Параметр | Описание | Примерные значения |
|---|---|---|
restrict_to_user_countriesСписок строк | Необязательный Ограничьте отображение значков вызовов только для этих стран. ПРИМЕЧАНИЕ: Например, если вы ограничите действие только территорией «США», то это будет применяться ко всем людям, имеющим зарегистрированный в США номер телефона. Эти люди могут физически находиться как внутри, так и за пределами США. | Ограничить доступом только для США и Бразилии: "restrict_to_user_countries" Без ограничений: "restrict_to_user_countries": [] |
часы работы службы поддержки
С помощью
call_hours можно указать часовой пояс, часы работы предприятия и расписание праздничных дней, которые будут применяться ко всем звонкам, инициированным пользователем.Настройка этого параметра ограничивает звонки только доступными в течение недели часами, которые вы укажете. Звонки, инициированные пользователем, будут недоступны вне установленных вами еженедельных часов и праздничных дней.
параметр callback_permission_status включен приложение WhatsApp предложит пользователям возможность связаться с компанией в чате или запросить обратный звонок. На экране выбора параметров пользователю также будет показан ближайший доступный временной интервал для звонка.
"call_hours"
: { "status"
: "ENABLED" , "timezone_id"
: "America/Manaus" , "weekly_operating_hours"
: [ {
"day_of_week"
: "MONDAY" , "open_time"
: "0400" , "close_time"
: "1020" },
{
"day_of_week"
: "TUESDAY" , "open_time"
: "0108" , "close_time"
: "1020" }
],
"holiday_schedule"
: [ {
"date"
: "2026-01-01" , "start_time"
: "0000" , "end_time"
: "2359" }
]
}
| Параметр | Описание | Примерные значения | ||
|---|---|---|---|---|
статусНить | Необходимый Включить или отключить часы работы службы поддержки для предприятия. Если функция оповещения о времени работы отключена, считается, что предприятие работает круглосуточно, 7 дней в неделю. | "ВКЛЮЧЕНО""НЕПОЛНОЦЕННЫЙ" | ||
timezone_idНить | Необходимый Часовой пояс, в котором работает компания. | «Америка/Меномине»«Азия/Сингапур» | ||
еженедельные_часы_работыСписок объектов JSON | Необходимый Расписание работы на каждый день недели. Каждая запись представляет собой JSON-объект, содержащий 3 пары ключ/значение: день недели — ( Перечисление ) [Обязательно]День недели. Может принимать одно из семи значений: «MONDAY» , «TUESDAY» , «WEDNESDAY» , «THURSDAY» , «FRIDAY» , «SATURDAY» , «SUNDAY».
Время открытия и закрытия указывается в 24-часовом формате, например, "11:30" = 11:30 утра.Время открытия (open_time) должно быть раньше времени закрытия (close_time).Повторяющиеся записи не допускаются | { | ||
расписание праздниковНить | Необязательный Дополнительная возможность изменения еженедельного расписания. Можно указать до 20 вариантов переопределения. Примечание: Если параметр holiday_schedule не указан в запросе, то существующее расписание holiday_schedule будет удалено и заменено пустым расписанием.дата — ( Строка ) [Обязательно]Дата, для которой вы хотите указать значение для переопределения. Формат ГГГГ-ММ-ДД.
Время открытия и закрытия указывается в 24-часовом формате, например, «11:30» = 11:30 утра.Время открытия (open_time) должно быть раньше времени закрытия (close_time).Повторяющиеся записи не допускаются | { |
Аудиокодек
Opus — это аудиокодек по умолчанию для всех звонков в WhatsApp. Вы можете включить кодеки G.711 (PCMA/PCMU) для обеспечения совместимости с устаревшими телефонными системами или шлюзами PSTN.
Рекомендации и соображения
"audio"
: { "additional_codecs"
: [ "PCMA" , "PCMU" ] }
| Параметр | Описание | Примерные значения |
|---|---|---|
дополнительные_кодекиСписок строк | Необязательный Включите дополнительные аудиокодеки. Поддерживаемые значения: "PCMA" (G.711 A-law), "PCMU" (G.711 µ-law). Opus всегда включен по умолчанию и не может быть удален. После включения дополнительных кодеков их можно выбрать во время согласования кодеков SDP в соответствии с RFC 3264. | "additional_codecs" Дополнительные кодеки отсутствуют: "additional_codecs": [] |
Ответ об успехе
{
"success"
: true }
Ответ с ошибкой
Возможные ошибки, которые могут возникнуть:
call_hours праздника, указанная в call_hours, уже прошла. параметре call_hours указан недопустимый часовой пояс Параметр weekly_operating_hours в call_hours не может быть пустым.Формат даты в holiday_schedule для call_hours недопустим. графике работы службы поддержки (call_hours) не допускается более 2 записей.Перекрывающиеся графики в call_hours не допускаются.Получить настройки звонков по номеру телефона
Используйте эту конечную точку для проверки конфигурации настроек функции вызова API.
Этот конечный пункт может возвращать информацию о других настройках функций Cloud API.
Синтаксис запроса
GET / <PHONE_NUMBER_ID> / настройкиПараметры конечной точки
| Параметр | Описание | Пример значения |
|---|---|---|
<PHONE_NUMBER_ID>Целое число | Необходимый Идентификатор номера телефона компании, для которого вы получаете настройки API вызовов. | 106540352242922 |
Требуются разрешения приложения
whatsapp_business_management : Для использования API конечными бизнес-клиентами требуется расширенный доступ.Ответный текст
{
"calling"
: { "status"
: "ENABLED" , "call_icon_visibility"
: "DEFAULT" , "callback_permission_status"
: "ENABLED" , "call_hours"
: { "status"
: "ENABLED" , "timezone_id"
: "[REDACTED]" , "weekly_operating_hours"
: [ {
"day_of_week"
: "MONDAY" , "open_time"
: "0400" , "close_time"
: "1020" },
{
"day_of_week"
: "TUESDAY" , "open_time"
: "0108" , "close_time"
: "1020" }
],
"holiday_schedule"
: [ {
"date"
: "2026-01-01" , "start_time"
: "0000" , "end_time"
: "2359" }
]
},
"sip"
: { "status"
: "ENABLED" , "servers"
: [ {
"hostname"
: "[REDACTED]" , "sip_user_password"
: "[REDACTED]" }
]
},
"audio"
: { "additional_codecs"
: [ "PCMA" , "PCMU" ] }
},
-вызов конфигурации функции...> }
В ответ необходимо включить пароль пользователя SIP
При желании вы можете включить учетные данные пользователя SIP в тело ответа, добавив параметр запроса SIP credentials в POST-запрос:
GET / <PHONE_NUMBER_ID> / settings ? include_sip_credentials = trueВ результате будет получен следующий ответ:
{
"calling"
: { ... // другие настройки API для звонков
"sip"
: { "status"
: "ENABLED" , "servers"
: [ {
"hostname"
: "sip.example.com" , "sip_user_password"
: "{SIP_USER_PASSWORD}" }
]
}
}
}
Подробности ответа
GET
/ /settings возвращает настройки API вызовов, а также другую информацию о конфигурации вашего бизнес-номера телефона WhatsApp.Ответ с ограничениями на звонки
Если в вашей компании действуют ограничения, тело ответа содержит информацию об этих ограничениях, а также другие настройки вызывающего API.
{
"вызов"
: { ... // другие настройки API вызовов
"ограничения"
: { "список_ограничений"
: [ {
"тип"
: "[Ограниченные_вызовы_для_бизнеса_инициируются_пользователями|Ограниченные_вызовы_для_пользователей_инициируются_пользователями ]" , "причина"
: "Возможность совершения звонков по инициативе бизнеса/пользователя временно отключена для этого номера телефона из-за большого количества негативных отзывов от пользователей." , "срок действия"
: 1754072386 }
]
}
}
}
| Параметр | Описание |
|---|---|
<restrictions>Объект JSON | Объект restrictions содержит следующие значения: restriction_list (объект JSON) : список текущих наложенных ограничений со следующими значениями:type (string) - для ограничения вызова это будет значение RESTRICTED_BUSINESS_INITIATED_CALLING или RESTRICTED_USER_INITIATED_CALLINGпричина (строка) - описание ограниченияexpiration (целое число) — время в часовом поясе UTC, в которое истечет срок действия ограничения в UNIX. |
Ответ с ошибкой
Возможные ошибки, которые могут возникнуть:
Настройки звонков в WhatsApp Manager
Вы также можете управлять настройками звонков через WhatsApp Manager .
Чтобы получить доступ к элементам управления вызовами в WhatsApp Manager:

Настройка и использование сигнализации вызовов через протокол инициации сеанса (SIP)
Протокол инициации сеанса (SIP) — это протокол сигнализации, используемый для инициирования, поддержания, изменения и завершения сеансов связи в реальном времени между двумя или более конечными точками. Вы можете отправлять и получать сигналы вызова, используя SIP вместо конечных точек Graph API.
Обновление настроек веб-хуков
Вы можете подписаться на новое поле подписки веб-хука
account_settings_update , чтобы получать уведомления об обновлениях настроек номера телефона.Шаги для начала работы
account_settings_update .Это же приложение необходимо также подписать на бизнес-аккаунт WhatsApp, привязанный к вашему рабочему номеру телефона.Вашему приложению необходимо иметь whatsapp_business_management для получения веб-хуков. Если при использовании токена доступа для этого же приложения вам удается получить настройки , значит, ваше приложение также может получать веб-хуки.Полезная нагрузка веб-перехватчика
{ "object" : "whatsapp_business_account" , "entry" : [ { "id" : "whatsapp-business-account-id" , "changes" : [ { "value" : { "messaging_product" : "whatsapp" , "timestamp" : "1671644824" , "type" : "[phone_number_settings]" , "phone_number_settings" : { "phone_number_id" : "phone-number-id" , "calling" : { "status" : "ENABLED" , "call_icon_visibility" : "DEFAULT" , "callback_permission_status" : "ENABLED" , "call_hours" : { "status" : "ENABLED" , "timezone_id" : "[REDACTED]" , "weekly_operating_hours" : [ { "day_of_week" : "MONDAY" , "open_time" : "0400" , "close_time" : "1020" }, { "day_of_week" : "TUESDAY" , "open_time" : "0108" , "close_time" : "1020" } ], "holiday_schedule" : [ { "date" : "2026-01-01" , "start_time" : "0000" , "end_time" : "2359" } ] }, "sip" : { "status" : "ENABLED" , "servers" : [ { "hostname" : "[REDACTED]" , "port" : SIP_SERVER_PORT } ] } } } }, "field" : "account_settings_update" } ] } ] }Значения веб-перехватчика
| Заполнитель | Описание |
|---|---|
messaging_productНить | что всегда пользуюсь WhatsApp. |
метка времениЦелое число | Время обновления настроек |
типНить | Тип изменения. В настоящее время только PHONE_NUMBER_SETTINGS |
настройки номера телефонаОбъект | Это поле присутствует, если тип — PHONE_NUMBER_SETTINGS . В настоящее время поддерживается только вызов подполя в рамках этого типа. |
phone_number_settings.phone_number_idНить | Номер телефона, настройки которого были обновлены |
phone_number_settings.callingОбъект | Этот параметр присутствует только в том случае, если обновляются поля, связанные с вызовом . В противном случае он равен null. Если он присутствует, полезная нагрузка совпадает с API получения настроек. |
Ограничения на звонки для обратной связи с пользователями
Если ваши звонки получают много негативных отзывов от пользователей, таких как блокировки и жалобы, то функции совершения звонков по инициативе компании, звонков по инициативе пользователя или обе функции одновременно на вашем телефонном номере могут быть ограничены.
Раннее предупреждение
Вы получите уведомление о приближении блокировки рабочего телефонного номера в качестве предупреждения. Уведомления о приближении блокировки будут передаваться по указанным ниже каналам
Электронная почта
Уведомления о нарушениях рассылаются на электронные адреса всех пользователей и администраторов, связанных с компанией. Если вы не получили уведомление, проверьте, какой адрес электронной почты вы указали в качестве контактного для вашего приложения, и убедитесь, что он активен, может получать новые письма и не помечает их как спам.
Вебхук
Веб-хук будет отправлен по
account_update :{
"object"
: "whatsapp_business_account" , "entry"
: [ {
"id"
: "0" , "time"
: 1623862418 , "changes"
: [ {
"field"
: "account_update" , "value"
: { "phone_number"
: "PN" , "event"
: "ACCOUNT_VIOLATION" , "violation_info"
: { "violation_type"
: "[LOW_BUSINESS_INITIATED_CALLING_QUALITY|LOW_USER_INITIATED_CALLING_QUALITY ]" , }
}
}
]
}
]
}
Если вызовы, инициированные компанией или пользователем, близки к приостановке, вы получите веб-перехватчик для соответствующего типа нарушения. Для получения информации о веб-перехватчике account_update
Функция паузы при вызове
Как только количество негативных отзывов пользователей достигнет определенного порога, Cloud API автоматически ограничит возможность совершения звонков на ваш номер телефона на 7 дней. В течение этого периода номер телефона, на который будет произведен звонок, будет недоступен
После блокировки вашего номера телефона уведомления будут отправляться по указанным ниже каналам.
Примечание: Любые разрешения на совершение звонков, одобренные или отклоненные пользователями во время паузы, остаются в силе.
Электронная почта
Уведомления о нарушениях рассылаются на электронные адреса всех пользователей и администраторов, связанных с компанией. Если вы не получили уведомление, проверьте, какой адрес электронной почты вы указали в качестве контактного для вашего приложения, и убедитесь, что он активен, может получать новые письма и не помечает их как спам.
Вебхук
Веб-хук будет отправлен по
account_update :{
"object"
: "whatsapp_business_account" , "entry"
: [ {
"id"
: "0" , "time"
: 1641848059 , "changes"
: [ {
"field"
: "account_update" , "value"
: { "phone_number"
: "PN" , "event"
: "ACCOUNT_RESTRICTION" , "restriction_info"
: [ {
"restriction_type"
: "RESTRICTED_BUSINESS_INITIATED_CALLING" , "expiration"
: 1641848057 }
]
}
}
]
}
]
}
Для получения информации о веб-хуке обратитесь к разделу account_update
Приостановка функции вызова, инициированного пользователем
Как только количество негативных отзывов пользователей достигнет определенного порога, Cloud API автоматически ограничит возможность совершения звонков с вашего номера телефона на 7 дней. В период паузы звонки с этого номера будут невозможны
После блокировки вашего номера телефона уведомления будут отправляться по указанным ниже каналам.
Электронная почта
Уведомления о нарушениях рассылаются на электронные адреса всех пользователей и администраторов, связанных с компанией. Если вы не получили уведомление, проверьте, какой адрес электронной почты вы указали в качестве контактного для вашего приложения, и убедитесь, что он активен, может получать новые письма и не помечает их как спам.
Вебхук
Веб-хук будет отправлен по
account_update :{
"object"
: "whatsapp_business_account" , "entry"
: [ {
"id"
: "0" , "time"
: 1641848059 , "changes"
: [ {
"field"
: "account_update" , "value"
: { "phone_number"
: "PN" , "event"
: "ACCOUNT_RESTRICTION" , "restriction_info"
: [ {
"restriction_type"
: "RESTRICTED_USER_INITIATED_CALLING" , "expiration"
: 1641848057 }
]
}
}
]
}
]
}
Для получения информации о веб-хуке обратитесь к разделу account_update
Ограничения на звонки из-за низкого процента ответов на звонки
Если на вашем рабочем телефонном номере включена функция звонков, вы должны отвечать на звонки, которые вам поступают от пользователей.
Если значительное количество звонков на ваш рабочий телефонный номер с возможностью совершения звонков останется без ответа, вы получите уведомление и вам будет предложено внести изменения.
Что произойдет, если вы не будете отвечать на звонки?
Как смягчить ситуацию
Если вы получили предупреждение
Вебхуки
Предупреждение веб-перехватчика
[
{
"object"
: "whatsapp_business_account" , "entry"
: [ {
"id"
: "0" , "time"
: 1641848059 , "changes"
: [ {
"field"
: "account_update" , "value"
: { "phone_number"
: "16505552771" , "event"
: "ACCOUNT_VIOLATION" , "violation_info"
: { "violation_type"
: "USER_INITIATED_CALLS_LOW_PICKUP_RATE" , "remediation"
: "Пожалуйста, выявите и устраните причину, по которой звонки, инициированные пользователем, не принимаются, и убедитесь, что у компании достаточно ресурсов для обработки ожидаемого объема звонков." }
}
}
]
}
]
}
]
Веб-перехватчик принудительного исполнения
[
{
"object"
: "whatsapp_business_account" , "entry"
: [ {
"id"
: "0" , "time"
: 1641848059 , "changes"
: [ {
"field"
: "account_update" , "value"
: { "phone_number"
: "16505552771" , "event"
: "ACCOUNT_RESTRICTION" , "restriction_info"
: [ {
"restriction_type"
: "RESTRICTED_USER_INITIATED_CALLING_CALL_BUTTON_HID DEN" , "remediation"
: "Кнопка вызова скрыта из-за низкого процента ответов. Пожалуйста, определите и устраните причину, по которой инициированные пользователем звонки не принимаются. Затем отобразите кнопки вызова, либо обратившись к вашему партнеру, либо перейдя в WhatsApp Manager > Инструменты учетной записи > Номера телефонов > Выберите номер телефона > Вызовы > включите отображение кнопок вызова" }
]
}
}
]
}
]
}
]