WhatsApp Cloud API — API для звонков | Документация для разработчиков

WhatsApp Cloud API - API для звонков

Экземпляр для программы магистратуры (LLM)

Версия

API для бизнес-звонков WhatsApp позволяет инициировать и принимать звонки от пользователей WhatsApp, используя протокол VoIP (голосовая связь через интернет).

База URL

~~https://graph.facebook.com~~

Конечные точки

~~ПОЛУЧАТЬ~~	~~/{Version}/{Phone-Number-ID}/call_permissions~~
~~ПОЧТА~~	~~/{Версия}/{Идентификатор-номера-телефона}/звонки~~

GET /{Version}/{Phone-Number-ID}/call_permissions

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

Статус доступа:

предоставлено: У вас есть действующее разрешение на звонок этому пользователю - ожидание: Запрос на разрешение отправлен, но еще не одобрен - отклонено: Пользователь отказал в разрешении на звонок - истекло: Предыдущее разрешение истекло

Доступные действия:

start_call: Инициировать новый вызов этому пользователю - send_call_permission_request: Отправить запрос на разрешение этому пользователю

Обработка ошибок:

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

Синтаксис запроса

GET /{Version}/{Phone-Number-ID}/call_permissions

Попробуйте!

Выберите язык

curl --request GET \ --url 'https://graph.facebook.com/{Version}/{Phone-Number-ID}/call_permissions' \ --header 'Authorization: Bearer<Token> ' \ --header 'Content-Type: application/json' \ --data '{}'

Выберите код состояния

{ "Предоставлено разрешение": { "значение": { "messaging_product": "whatsapp", "разрешение": { "статус": "предоставлено", "время истечения срока действия": 1735689600 }, "действия": [ { "имя_действия": "начать_звонок", "можно_выполнить_действие": true, "ограничения": [ { "период_времени": "24 ч", "текущее_использование": 5, "максимально_разрешено": 100, "ограничение_времени_истечения срока действия": 1735689600 } ] }, { "имя_действия": "запрос на разрешение отправки_звонка", "можно_выполнить_действие": false, "ограничения": "" } ] } }, "Ожидаемое разрешение": { "значение": { "messaging_product": "whatsapp", "разрешение": { "статус": "ожидающее" }, "действия": [ { "имя_действия": "start_call", "can_perform_action": false }, { "action_name": "send_call_permission_request", "can_perform_action": false } ] } }, "Denied Permission": { "value": { "messaging_product": "whatsapp", "permission": { "status": "denied" }, "actions": [ { "action_name": "start_call", "can_perform_action": false }, { "action_name": "send_call_permission_request", "can_perform_action": true, "limits": [ { "time_period": "24h", "current_usage": 2, "max_allowed": 5, "limit_expiration_time": 1735689600 } ] } ] } } }

Параметры заголовка

User-AgentСтрока

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

авторизацииСтрока·обязательный

Токен Bearer для аутентификации API. Это должен быть действительный токен доступа, полученный через соответствующий поток OAuth, или системный пользовательский токен.

Content-TypeОдин из "application/json", "application/x-www-form-urlencoded", "multipart/form-data"·обязательный

Тип носителя информации в теле запроса

Параметры пути

версииСтрока·обязательный

Версия API для использования

Phone-Number-IDСтрока·обязательный

Идентификатор номера телефона, зарегистрированного в вашем аккаунте WhatsApp Business

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

user_wa_idстрока·обязательный

Идентификатор WhatsApp пользователя, для которого вы хотите проверить права на звонки

Ответы

Статус доступа:

Доступные действия:

Обработка ошибок:

200

Проверка прав доступа прошла успешно

Тип содержимого: application/json

Схема: CallPermissionCheckResponsePayload

Показать дочерние атрибуты

CallPermissionCheckResponsePayload

messaging_productstring·required

Продукт для обмена сообщениями

разрешенияобъект·обязательный

Информация о разрешении на вызов

Показать дочерние атрибуты

Статус:Один из вариантов: "предоставлено", "ожидается", "отказано", "истек срок действия"·требуется

Текущий статус разрешений для вызова этого пользователя

expiration_timeinteger (int64)

Отметка времени Unix, когда истекает срок действия разрешения (если применимо)

действийобъекта

Доступные действия и их ограничения

Показать дочерние атрибуты

действия[]объект

Показать дочерние атрибуты

action_nameОдин из "start_call", "send_call_permission_request"·required

Название действия

can_perform_actionboolean·required

Может ли предприятие выполнить это действие?

ограничиваетмассив объектов

Ограничения скорости для этого действия

Показать дочерние атрибуты

ограничения[]объект

Показать дочерние атрибуты

time_periodстрока·обязательный

Период времени для установления лимита

current_usageцелое число·обязательно

Текущее количество использований

максимально допустимоецелое число·обязательное

Максимально допустимое использование

limit_expiration_timeinteger (int64)

Unix-метка времени, когда сбрасывается лимит

400

Неверный запрос - Недопустимые параметры запроса

Тип содержимого: application/json

429

Слишком много запросов — превышен лимит запросов

Тип содержимого: application/json

403

Запрещено — Шаблон не одобрен или имеются недостаточные права доступа

Тип содержимого: application/json

500

Внутренняя ошибка сервера — произошла непредвиденная ошибка

Тип содержимого: application/json

Выберите язык

curl --request GET \ --url 'https://graph.facebook.com/{Version}/{Phone-Number-ID}/call_permissions' \ --header 'Authorization: Bearer<Token> ' \ --header 'Content-Type: application/json' \ --data '{}'

Выберите код состояния

{ "Предоставлено разрешение": { "значение": { "messaging_product": "whatsapp", "разрешение": { "статус": "предоставлено", "время истечения срока действия": 1735689600 }, "действия": [ { "имя_действия": "начать_звонок", "можно_выполнить_действие": true, "ограничения": [ { "период_времени": "24 ч", "текущее_использование": 5, "максимально_разрешено": 100, "ограничение_времени_истечения срока действия": 1735689600 } ] }, { "имя_действия": "запрос на разрешение отправки_звонка", "можно_выполнить_действие": false, "ограничения": "" } ] } }, "Ожидаемое разрешение": { "значение": { "messaging_product": "whatsapp", "разрешение": { "статус": "ожидающее" }, "действия": [ { "имя_действия": "start_call", "can_perform_action": false }, { "action_name": "send_call_permission_request", "can_perform_action": false } ] } }, "Denied Permission": { "value": { "messaging_product": "whatsapp", "permission": { "status": "denied" }, "actions": [ { "action_name": "start_call", "can_perform_action": false }, { "action_name": "send_call_permission_request", "can_perform_action": true, "limits": [ { "time_period": "24h", "current_usage": 2, "max_allowed": 5, "limit_expiration_time": 1735689600 } ] } ] } } }

POST /{Version}/{Phone-Number-ID}/calls

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

Для инициирования или управления вызовом:

Отправьте POST-запрос с соответствующим действием (connect, pre_accept, accept, reject, terminate).

Для завершения вызова:

Отправьте POST-запрос с действием "terminate" и call_id.

Примечание: Ответ с кодом ошибки 138006 указывает на отсутствие у пользователя WhatsApp разрешения на запрос вызова для этого номера компании.

Синтаксис запроса

POST /{Version}/{Phone-Number-ID}/calls

Попробуйте!

Выберите язык

curl --request POST \ --url 'https://graph.facebook.com/{Version}/{Phone-Number-ID}/calls' \ --header 'Authorization: Bearer<Token> ' \ --header 'Content-Type: application/json' \ --data '{ "messaging_product": "whatsapp", "to": "14085551234", "action": "connect", "session": { "sdp_type": "offer", "sdp": "v=0\no=- 3626166318745852955 2 IN IP4 127.0.0.1\ns=-\nt=0 0\na=group:BUNDLE 0\na=extmap-allow-mixed\na=msid-semantic: WMS d8b26053-4474-4eb7-b3c3-c93d6c8c9b2e\nm=audio 9 UDP/TLS/RTP/SAVPF 111 63 9 0 8 110 126\nc=IN IP4 0.0.0.0\na=rtcp:9 IN IP4 0.0.0.0\na=ice-ufrag:4g1c\na=ice-pwd:qY/Bb+jQzg5ICn6X4fhJQetk\na=ice-options:trickle\na=fingerprint:sha-256 35: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\na=setup:actpass\na=mid:0\na=extmap:1 urn:ietf:params:rtp-hdrext:ssrc-audio-level\na=extmap:2 http://www.webrtc.org/experiments/rtp-hdrext/abs-send-time\na=extmap:3 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01\na=extmap:4 urn:ietf:params:rtp-hdrext:sdes:mid\na=sendrecv\na=msid:d8b26053-4474-4eb7-b3c3-c93d6c8c9b2e 5b4d3d96-ea9b-44a8-87e6-11a1ad21a3bc\na=rtcp-mux\na=rtpmap:111 opus/48000/2\na=rtcp-fb:111 Transport-cc\na=fmtp:111 minptime=10;useinbandfec=1\na=rtpmap:63 red/48000/2\na=fmtp:63 111/111\na=rtpmap:9 G722/8000\na=rtpmap:0 PCMU/8000\na=rtpmap:8 PCMA/8000\na=rtpmap:110 Telephone-event/48000\na=rtpmap:126 Telephone-event/8000\na=ssrc:2220762577 cname:w/zwpg3jXNiTFTdZ\na=ssrc:2220762577 msid:d8b26053-4474-4eb7-b3c3-c93d6c8c9b2e 5b4d3d96-ea9b-44a8-87e6-11a1ad21a3bc\n" }, "biz_opaque_callback_data": "0fS5cePMok" }'

Выберите код состояния

{ "Подключить ответ на вызов": { "значение": { "messaging_product": "whatsapp", "calls": [ { "id": "wacid.ABGGFjFVU2AfAgo6V" } ] } }, "Завершить ответ на вызов": { "значение": { "success": true } } }

Параметры заголовка

User-AgentСтрока

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

авторизацииСтрока·обязательный

Content-TypeОдин из "application/json", "application/x-www-form-urlencoded", "multipart/form-data"·обязательный

Тип носителя информации в теле запроса

Параметры пути

версииСтрока·обязательный

Версия API для использования

Phone-Number-IDСтрока·обязательный

Идентификатор номера телефона, зарегистрированного в вашем аккаунте WhatsApp Business

Текст запросаНеобязательный

Тип содержимого: application/json

Схема: Должна быть одной из следующих: CallRequestPayload, CallTerminateRequestPayload

Показать дочерние атрибуты

Должно быть одно из следующих значений: CallRequestPayload, CallTerminateRequestPayload

CallRequestPayload

Показать дочерние атрибуты

messaging_productstring·required

Продукт для обмена сообщениями

встроку·обязательный

Вызываемый номер (звонящий)

Действие:Один из вариантов "connect", "pre_accept", "accept", "reject", "terminate"·обязательно

Действие, выполняемое с указанным идентификатором вызова

сессииобъект

Содержит тип протокола описания сессии (SDP) и язык описания

Показать дочерние атрибуты

sdp_typeОдин из "offer", "answer"·обязательный

Тип SDP: "offer" для действия подключения, "answer" для действия принятия

sdpстрока·обязательный

Информация SDP устройства на другом конце вызова. SDP должен соответствовать RFC 8866

biz_opaque_callback_datastring

Произвольная строка, которую можно передать для целей отслеживания и регистрации. Любое приложение, подписанное на поле веб-хука "вызовы" в вашем аккаунте WhatsApp Business, может получить эту строку, поскольку она включена в объект вызовов в последующей полезной нагрузке веб-хука завершения вызова. Cloud API не обрабатывает это поле. Максимальное количество символов: 512

CallTerminateRequestPayload

Показать дочерние атрибуты

messaging_productstring·required

Продукт для обмена сообщениями

call_idстрока·обязательный

Идентификатор вызова WhatsApp

действие«прекратить»·требуется

Действия по завершению вызова

Ответы

Для инициирования или управления вызовом:

Отправьте POST-запрос с соответствующим действием (connect, pre_accept, accept, reject, terminate).

Для завершения вызова:

Отправьте POST-запрос с действием "terminate" и call_id.

200

Успех в управлении звонками

Тип содержимого: application/json

Схема: Должна быть одной из следующих: CallResponsePayload, CallTerminateResponsePayload

Показать дочерние атрибуты

Должно быть одно из следующих значений: CallResponsePayload, CallTerminateResponsePayload

CallResponsePayload

Показать дочерние атрибуты

messaging_productstring

вызываетмассив объектов

Показать дочерние атрибуты

вызовы[]объект

Показать дочерние атрибуты

идентификаторастрока

CallTerminateResponsePayload

Показать дочерние атрибуты

успехлогическое значение

Выберите язык

curl --request POST \ --url 'https://graph.facebook.com/{Version}/{Phone-Number-ID}/calls' \ --header 'Authorization: Bearer<Token> ' \ --header 'Content-Type: application/json' \ --data '{ "messaging_product": "whatsapp", "to": "14085551234", "action": "connect", "session": { "sdp_type": "offer", "sdp": "v=0\no=- 3626166318745852955 2 IN IP4 127.0.0.1\ns=-\nt=0 0\na=group:BUNDLE 0\na=extmap-allow-mixed\na=msid-semantic: WMS d8b26053-4474-4eb7-b3c3-c93d6c8c9b2e\nm=audio 9 UDP/TLS/RTP/SAVPF 111 63 9 0 8 110 126\nc=IN IP4 0.0.0.0\na=rtcp:9 IN IP4 0.0.0.0\na=ice-ufrag:4g1c\na=ice-pwd:qY/Bb+jQzg5ICn6X4fhJQetk\na=ice-options:trickle\na=fingerprint:sha-256 35: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\na=setup:actpass\na=mid:0\na=extmap:1 urn:ietf:params:rtp-hdrext:ssrc-audio-level\na=extmap:2 http://www.webrtc.org/experiments/rtp-hdrext/abs-send-time\na=extmap:3 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01\na=extmap:4 urn:ietf:params:rtp-hdrext:sdes:mid\na=sendrecv\na=msid:d8b26053-4474-4eb7-b3c3-c93d6c8c9b2e 5b4d3d96-ea9b-44a8-87e6-11a1ad21a3bc\na=rtcp-mux\na=rtpmap:111 opus/48000/2\na=rtcp-fb:111 Transport-cc\na=fmtp:111 minptime=10;useinbandfec=1\na=rtpmap:63 red/48000/2\na=fmtp:63 111/111\na=rtpmap:9 G722/8000\na=rtpmap:0 PCMU/8000\na=rtpmap:8 PCMA/8000\na=rtpmap:110 Telephone-event/48000\na=rtpmap:126 Telephone-event/8000\na=ssrc:2220762577 cname:w/zwpg3jXNiTFTdZ\na=ssrc:2220762577 msid:d8b26053-4474-4eb7-b3c3-c93d6c8c9b2e 5b4d3d96-ea9b-44a8-87e6-11a1ad21a3bc\n" }, "biz_opaque_callback_data": "0fS5cePMok" }'

Выберите код состояния

{ "Подключить ответ на вызов": { "значение": { "messaging_product": "whatsapp", "calls": [ { "id": "wacid.ABGGFjFVU2AfAgo6V" } ] } }, "Завершить ответ на вызов": { "значение": { "success": true } } }

Аутентификация

Схема

Тип

Расположение

bearerAuth

HTTP Bearer

Заголовок: Авторизация

Примеры использования

bearerAuth:

Включите Authorization: Bearer your-token-here в заголовки запроса.

Глобальные требования к аутентификации

Для работы всех конечных точек требуется:

bearerAuth