Справочник по API и веб-перехватчикам | Документация для разработчиков

Справочник по API и веб-перехватчикам

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

Вызов конечных точек API

Настройте или обновите параметры вызовов

Вызовите конечную точку «Обновить настройки номера телефона» и передайте параметры API вызовов, чтобы настроить параметры корпоративного номера телефона, указанного в синтаксисе запроса.

Параметры конечной точки

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

Подробности параметра: Статус вызова

Если статуса установлен в значение «ВКЛЮЧЕНО», функции вызова для рабочего номера телефона становятся доступны. Приложения WhatsApp будут отображать значок кнопки вызова как в рабочем чате, так и в профиле рабочего чата.

Если статуса присвоено значение «ОТКЛЮЧЕНО», функции вызова отключаютсяни в деловом чате, ни в профиле делового чата значок кнопки вызова не отображается

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

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

Подробности параметра: Видимость значка кнопки вызова

Если для номера компании включены функции Calling API, вы все равно можете выбрать, отображать ли значок кнопки вызова или нет, используя call_icon_visibility . Примечание: отключение видимости значка кнопки вызова не отключает возможность пользователя WhatsApp совершать незапрошенные звонки в вашу компанию.

Для поддерживаемых опций поведение следующее:

ПО УМОЛЧАНИЮ

Значок кнопки «Вызов» будет отображаться в строке меню чата и на странице информации о компании, что позволит пользователям WhatsApp совершать незапрошенные звонки в компанию.

Скриншот, демонстрирующий значок кнопки вызова, отображаемый в строке меню чата WhatsApp и на странице информации о компании

ОТКЛЮЧИТЬ ВСЕ

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

Ваша компания по-прежнему может отправлять интерактивные сообщения или шаблонные сообщения с помощью кнопки призыва к действию (CTA) через Calling API.

Скриншот, демонстрирующий интерфейс чата WhatsApp со скрытым значком кнопки вызова

Разрешения на обратный вызов

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

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

Скриншот диалогового окна запроса разрешения на звонок в WhatsApp

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

{
"success": true
}

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

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

Ошибки доступа/авторизацииНедействительный статусНеверное расписание для call_hoursпраздника, указанная в call_hours, уже прошла.указан недопустимый часовой пояс параметре call_hoursПараметр weekly_operating_hours в call_hours не может быть пустым.Формат даты в holiday_schedule для call_hours недопустим.не допускается более 2 записей. службы поддержки графике работы (call_hours)Перекрывающиеся графики в call_hours не допускаются.

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

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

Получить настройки звонков по номеру телефона

Для получения настроек API вызовов для конкретного номера телефона компании, указанного в синтаксисе запроса, воспользуйтесь конечной точкой Get Phone Number Settings.

Этот конечный пункт может возвращать информацию о других настройках функций Cloud API.

Параметры конечной точки

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

Требуются разрешения приложения

whatsapp_business_management: Для использования API конечными бизнес-клиентами требуется расширенный доступ.

Подробности ответа

GET / Конечная точка возвращает настройки API вызовов, а также другую информацию о конфигурации вашего бизнес-номера телефона WhatsApp.

Узнайте больше о настройках вызова API и их значениях

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

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

Ошибки доступа/авторизации

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

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

Предварительное принятие звонка

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

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

Рекомендуется предварительно принимать звонки, поскольку это способствует более быстрому установлению соединения и позволяет избежать проблем с искажением звука.

есть примерно от 30 до 60 секунд, веб-хука Call Connect чтобы принять телефонный звонок. Если компания не отвечает, звонок завершается на стороне пользователя WhatsApp с уведомлением «Не отвечено», и веб-хук завершения вызова вам отправляется

Примечание: Поскольку соединение WebRTC устанавливается до вызова конечной точки Accept Call, убедитесь, что передача медиаданных происходит только после получения ответа 200 OK.

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

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

Параметр	Описание	Пример значения
`call_id` Нить	Необходимый Идентификатор телефонного звонка. При входящих звонках вы получаете идентификатор вызова от веб-перехватчика Call Connect, когда звонок инициирует пользователь WhatsApp.	`“wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh”`
`действие` Нить	Необязательный Действие, выполняемое в отношении указанного идентификатора вызова. Значения могут быть `связаны` \| `предварительное принятие` \| `принятие` \| `отклонение` \| `завершение`	`“предварительное_принятие”`
`сессия` JSON-объект	Необязательный Содержит тип протокола описания сессии (SDP) и язык описания. Требуется два значения: `sdp_type` — (Строка) Обязательный параметр «Предложение» обозначает предложение SDP `sdp` — (Строка) Обязательный параметр Информация SDP устройства на другом конце вызова. SDP должен соответствовать 8866.RFC Узнайте больше о протоколе описания сессии (SDP)⁠ Посмотреть примеры структур SDP

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

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

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

Неверный идентификатор вызоваНеверный номер телефонаОшибка, связанная с вашим способом оплатыНеверные данные подключения, например, sdp, iceПринять/отклонить уже находящийся в процессе/завершенный/неудачный вызовОшибки доступа/авторизации

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

Принять звонок

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

у вас есть примерно от 30 до 60 секунд, веб-хука Call Connect чтобы принять телефонный звонок. Если ваша компания не отвечает, звонок завершается на стороне пользователя WhatsApp с уведомлением «Не отвечено», и веб-хук Terminate вам отправляется

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

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

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

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

Неверный идентификатор вызоваНеверный номер телефонаОшибка, связанная с вашим способом оплатыНеверная информация о соединении, например, параметры sdp, ice или другие параметры соединенияПринять/отклонить уже находящийся в процессе/завершенный/неудачный вызовОшибки доступа/авторизацииОтвет SDP, предоставленный в запросе accept, не совпадает с ответом SDP, предоставленным в конечной точке pre-Accept для того же идентификатора вызова.

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

Отклонить вызов

Используйте этот адрес электронной почты, чтобы отклонить вызов.

у вас есть примерно от 30 до 60 секунд, веб-хука Call Connect чтобы принять телефонный звонок. Если компания не отвечает, звонок завершается на стороне пользователя WhatsApp с уведомлением «Не отвечено», и веб-хук завершения вызова вам отправляется

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Получить текущее состояние разрешения на вызов

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

Параметры запроса

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

Параметры отклика

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

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

Неверный номер телефонаЕсли номер телефона потребителя недоступен для звонка, API ответит сообщением no_permission.Ошибки доступа/авторизации.Достигнут лимит запросов. Максимально 5 запросов к API в течение 1 секунды.Для корпоративного телефонного номера функция звонков отключена.

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

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

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

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

Примеры структур SDP, инициированные бизнесом

Пример структуры предложения SDP

v=0
o=-36261663187458529552 IN IP4 127.0.0.1
s=-
t=00
a=group:BUNDLE 0
a=extmap-allow-mixed a=msid-semantic: WMS d8b26053-4474-4eb7-b3c3-c93d6c8c9b2e m=audio 9 UDP/TLS/RTP/SAVPF 11163908110126
c=IN IP4 0.0.0.0
a=rtcp:9 IN IP4 0.0.0.0
a=ice-ufrag:4g1c
a=ice-pwd:qY/Bb+jQzg5ICn6X4fhJQetk a=ice-options:trickle a=fingerprint:sha-25635:47:24:24:9F:93:C4:3E:DB:37:7F:BB:ED:F8:20:B5:AD:AC:DC:35:C2:7D:67:EE:6C:35:54:DF:A6:00:5C:4A
a=setup:actpass a=mid:0
a=extmap:1 urn:ietf:params:rtp-hdrext:ssrc-audio-level a=extmap:2 http://www.webrtc.org/experiments/rtp-hdrext/abs-send-time
a=extmap:3 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01
a=extmap:4 urn:ietf:params:rtp-hdrext:sdes:mid a=sendrecv a=msid:d8b26053-4474-4eb7-b3c3-c93d6c8c9b2e 5b4d3d96-ea9b-44a8-87e6-11a1ad21a3bc
a=rtcp-mux a=rtpmap:111 opus/48000/2
a=rtcp-fb:111 transport-cc a=fmtp:111 minptime=10;useinbandfec=1
a=rtpmap:63 red/48000/2
a=fmtp:63111/111
a=rtpmap:9 G722/8000
a=rtpmap:0 PCMU/8000
a=rtpmap:8 PCMA/8000
a=rtpmap:110 telephone-event/48000
a=rtpmap:126 telephone-event/8000
a=ssrc:2220762577 cname:w/zwpg3jXNiTFTdZ a=ssrc:2220762577 msid:d8b26053-4474-4eb7-b3c3-c93d6c8c9b2e 5b4d3d96-ea9b-44a8-87e6-11a1ad21a3bc

Пример структуры ответа SDP

v=0
o=-7418078391020537252 IN IP4 127.0.0.1
s=-
t=00
a=group:BUNDLE 0
a=extmap-allow-mixed a=msid-semantic: WMS 798a9670-c0d6-47a8-925e-5f082ef4d8a0
a=ice-lite m=audio 3482 UDP/TLS/RTP/SAVPF 111908110126
c=IN IP4 31.13.65.130
a=rtcp:9 IN IP4 0.0.0.0
a=кандидат:27549362801 udp 211393715131.13.65.1303482 typ host generation 0 network-cost 50 ufrag JHqAXFH4HcAY/8
a=candidate:15814963991 udp 21139397112a03:2880:f211:d1:face:b00c:0:699c3482 typ host generation 0 network-cost 50 ufrag JHqAXFH4HcAY/8
a=ice-ufrag:JHqAXFH4HcAY/8
a=ice-pwd:dNNMmR8wUcGezvfBZOO0Qgcwl2m86GP/
a=ice-options:trickle a=fingerprint:sha-2569C:97:5C:4C:A9:BE:9E:2F:06:94:F5:BB:38:2C:A1:29:B5:69:B8:FA:94:10:56:1D:0B:5D:80:28:C1:FD:F0:F6 a=setup:active a=mid:0
a=extmap:1 urn:ietf:params:rtp-hdrext:ssrc-audio-level a=extmap:2 http://www.webrtc.org/experiments/rtp-hdrext/abs-send-time
a=extmap:3 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01
a=sendrecv a=rtcp-mux a=rtpmap:111 opus/48000/2
a=rtcp-fb:111 transport-cc a=fmtp:111 minptime=10;useinbandfec=1
a=rtpmap:9 G722/8000
a=rtpmap:0 PCMU/8000
a=rtpmap:8 PCMA/8000
a=rtpmap:110 telephone-event/48000
a=rtpmap:126 telephone-event/8000
a=ssrc:3407645770 cname:bg8KQDoIk2UJa6sf a=ssrc:3407645770 msid:798a9670-c0d6-47a8-925e-5f082ef4d8a0 audio#nuxVMf9EAJX
a=ssrc:3407645770 mslabel:798a9670-c0d6-47a8-925e-5f082ef4d8a0
a=ssrc:3407645770 label:audio#nuxVMf9EAJX

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

Пример структуры предложения SDP

v=0
o=-76025637897899450802 IN IP4 127.0.0.1
s=-
t=00
a=group:BUNDLE audio a=msid-semantic: WMS 6932bc1c-db1a-4abe-b437-0c4168be8a13
a=ice-lite m=audio 40012 UDP/TLS/RTP/SAVPF 111126
c=IN IP4 31.13.65.60
a=rtcp:9 IN IP4 0.0.0.0
a=candidate:19726373201 udp 211393715131.13.65.6040012 typ host generation 0 network-cost 50 ufrag 6k2qP1R6kBfI/2
a=candidate:16522627911 udp 21139397112a03:2880:f211:cf:face:b00c:0:644340012 typ host generation 0 network-cost 50 ufrag 6k2qP1R6kBfI/2
a=ice-ufrag:6k2qP1R6kBfI/2
a=ice-pwd:UApvJw3NcwFRDvIMKdM0vWCdlXah25E9
a=fingerprint:sha-2561B:B6:6B:40:A5:0B:8C:75:0D:8C:CB:90:2F:99:74:1E:26:45:AE:AF:45:C1:51:60:8F:73:C9:2D:10:6D:8A:88
a=setup:actpass a=mid:audio a=extmap:1 urn:ietf:params:rtp-hdrext:ssrc-audio-level a=extmap:2 http://www.webrtc.org/experiments/rtp-hdrext/abs-send-time
a=extmap:3 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01
a=sendrecv a=rtcp-mux a=rtpmap:111 opus/48000/2
a=rtcp-fb:111 transport-cc a=fmtp:111 minptime=10;useinbandfec=1
a=rtpmap:126 telephone-event/8000
a=ssrc:4208138518 cname:gAXq2V9TKltrnapv a=ssrc:4208138518 msid:6932bc1c-db1a-4abe-b437-0c4168be8a13 audio#R5wfXFcdmT6
a=ssrc:4208138518 mslabel:6932bc1c-db1a-4abe-b437-0c4168be8a13
a=ssrc:4208138518 label:audio#R5wfXFcdmT6

Пример структуры ответа SDP

v=0
o=-28226442481446439332 IN IP4 127.0.0.1
s=-
t=00
a=group:BUNDLE audio a=msid-semantic: WMS eb909cf0-87f0-4358-a4c9-7861680d9431
m=audio 9 UDP/TLS/RTP/SAVPF 111126
c=IN IP4 0.0.0.0
a=rtcp:9 IN IP4 0.0.0.0
a=ice-ufrag:X1ho a=ice-pwd:7fJSbV2N5qWiA5QiDKwK3vuh
a=fingerprint:sha-2562E:35:9F:21:9E:63:72:E5:42:74:76:2D:B3:70:F7:CB:24:14:9B:14:52:71:05:48:DA:4D:67:31:09:58:2A:ED a=setup:active a=mid:audio a=extmap:1 urn:ietf:params:rtp-hdrext:ssrc-audio-level a=extmap:2 http://www.webrtc.org/experiments/rtp-hdrext/abs-send-time
a=extmap:3 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01
a=sendrecv a=rtcp-mux a=rtpmap:111 opus/48000/2
a=rtcp-fb:111 transport-cc a=fmtp:111 minptime=10;useinbandfec=1
a=rtpmap:126 telephone-event/8000
a=ssrc:330833028 cname:EDc1JutBl8rwHQc2
a=ssrc:330833028 msid:eb909cf0-87f0-4358-a4c9-7861680d9431 ea478c16-d9f7-493c-8cec-19bfac750a36

Справочник по API и веб-перехватчикам | Документация для разработчиков