Перейти к основному содержимому

Звонки, инициированные бизнесом | Документация для разработчиков

Звонки, инициированные бизнесом

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

Обзор

API для звонков позволяет совершать звонки пользователям WhatsApp из вашего бизнеса.
Пользователь определяет, когда можно принимать звонки, предоставляя права на совершение звонков рабочему номеру телефона .

Диаграмма последовательности вызовов

Диаграмма последовательности звонков, инициированных бизнесом, показывающая взаимодействие между бизнесом, облачным API и пользователем WhatsApp
Примечание: ACCEPTED обычно приходит после установления соединения. Облачный API отправляет его в основном для аудита событий вызова.

Предварительные требования

Прежде чем начать совершать звонки по инициативе компании, убедитесь в следующем:
    Подпишитесь на поле веб-перехватчика «звонки».API для звонков включены для вашего рабочего телефонного номера
    И наконец, прежде чем позвонить пользователю WhatsApp, вы должны получить его разрешение.

    Схема обработки звонков, инициированных бизнесом

    Часть 1: Получение разрешения на звонок пользователю WhatsApp

    Получить разрешение на совершение звонков от пользователя WhatsApp можно одним из следующих способов:
    Отправить сообщение с запросом на разрешение вызова
    Вы можете запросить разрешение на звонок, отправив пользователю WhatsApp запрос на разрешение. Отправьте его в виде сообщения в свободной форме во время работы службы поддержки клиентов или используйте шаблон сообщения.
      Узнайте, как отправить запрос на разрешение на звонок в свободной форме.Узнайте, как отправить запрос на разрешение для вызова шаблона.
      Включите параметр callback_permission_status в настройках вызова.
      Если параметр callback_permission_status включен, пользователь автоматически предоставляет вашей компании разрешение на совершение звонков при обращении к вам.
      Пользователь WhatsApp предоставил постоянные разрешения
      Пользователь также может в любое время предоставить компании постоянные права доступа через свой бизнес-профиль.

      Часть 2: Ваша компания инициирует новый звонок пользователю WhatsApp

      Теперь, когда у вас есть разрешение пользователя, вы можете инициировать новый звонок нужному пользователю WhatsApp.
      Теперь вы можете позвонить на почту. /calls со следующим телом запроса:
      ПОЧТА
      <НОМЕР_ТЕЛЕФОНА_ИДЕНТИФИКАТОР>/звонки {"messaging_product":"WhatsApp","к":"12185552828",// Номер телефона пользователя WhatsApp (звонящий)"действие":"соединять","сессия":{"sdp_type":"предложение","sdp":«<<RFC 8866 SDP> >"}}
      Если ошибок нет, вы получите успешный ответ:
      {"messaging_product":"WhatsApp","звонки":["идентификатор":"wacid.HBgLMTIxODU1NTI4MjgVAgARGCAyODRQIAFRoA",//
      Идентификатор вызова WhatsApp]}
      Примечание: Ответ с кодом ошибки 138006 указывает на отсутствие у пользователя WhatsApp разрешения на запрос вызова для этого номера компании.

      Часть 3: Установление соединения с помощью сигнализации веб-перехватчика

      После успешного инициирования нового вызова вы получите ответ веб-перехватчика Call Connect, содержащий ответ SDP от Cloud API. Затем ваша компания применит ответ SDP из этого веб-перехватчика к вашему стеку WebRTC для инициирования медиасоединения.
      {"вход":[{"изменения":[{"поле":"звонки","ценить":{"звонки":[{"biz_opaque_callback_data":"TRx334DUDFTI4Mj",//
      Произвольная строка, передаваемая компанией в целях отслеживания"сессия":{"sdp_type":"отвечать","sdp":"<RFC 8866 SDP> "},"от":"13175551399",// Рабочий телефонный номер, с которого совершается звонок (звонящий)"связь":{"webrtc":{"sdp":"<RFC 8866 SDP> "}},"идентификатор":"wacid.HBgLMTIxODU1NTI4MjgVAgARGCAyODRQIAFRoA",// Идентификатор вызова WhatsApp"к":"12185552828",// Номер телефона пользователя WhatsApp (звонящий)"событие":"соединять","временная метка":"1749196895","направление":"БИЗНЕС_ИНИЦИИРОВАН"}],"метаданные":{// Идентификационный и отображаемый номер корпоративного телефона, с которого совершается звонок (звонящий)"идентификатор_номера_телефона":"436666719526789","display_phone_number":"13175551399"},"messaging_product":"WhatsApp"}}],"идентификатор":"366634483210360"// Идентификатор бизнес-аккаунта WhatsApp, связанный с номером телефона компании}],"объект":"whatsapp_business_account"},
      После этого вы получаете соответствующий веб-хук статуса, указывающий на то, что вызов проходит успешно , принят или отклонен :
      {"вход":[{"изменения":[{"поле":"звонки","ценить":{"статусы":[{"идентификатор":"wacid.HBgLMTIxODU1NTI4MjgVAgARGCAyODRQIAFRoA",//
      Он
      WhatsApp
      вызов
      ИДЕНТИФИКАТОР"тип":"вызов",«статус»:"[ЗВОНОК|ПРИНЯТО|ОТКЛОНЕНО]",// Текущий статус вызова"временная метка":"1749197000","recipient_id":"12185552828"// Номер телефона пользователя WhatsApp (звонящий)}],"метаданные":{// Идентификационный и отображаемый номер корпоративного телефона, с которого совершается звонок (звонящий)"идентификатор_номера_телефона":"436666719526789","display_phone_number":"13175551399"},"messaging_product":"WhatsApp"}}],"идентификатор":"366634483210360"// Идентификатор бизнес-аккаунта WhatsApp, связанный с номером телефона компании}],"объект":"whatsapp_business_account"}

      Часть 4: Ваша компания или пользователь WhatsApp завершает звонок

      Вы или пользователь WhatsApp можете в любой момент завершить звонок.
      Вы звоните ПОЧТА<PHONE_NUMBER_ID> /звонки Для завершения вызова необходимо отправить следующий запрос в конечную точку:
      ПОЧТА<PHONE_NUMBER_ID> /calls { "messaging_product": "whatsapp", "call_id": "wacid.HBgLMTIxODU1NTI4MjgVAgARGCAyODRQIAFRoA", // Идентификатор вызова WhatsApp "action" : "terminate" }
      Если ошибок не обнаружено, вы получите подтверждение об успешном завершении операции:
      {"успех":истинный}
      Когда компания или пользователь WhatsApp завершают вызов, вы получаете веб-хук "Завершение вызова":
      {"объект":"whatsapp_business_account","вход":[{"идентификатор":"366634483210360",// Идентификатор бизнес-аккаунта WhatsApp, связанный с номером телефона компании"изменения":[{"ценить":{"messaging_product":"WhatsApp","метаданные":{// Идентификационный и отображаемый номер корпоративного телефона, с которого совершается звонок (звонящий)"идентификатор_номера_телефона":"436666719526789","display_phone_number":"13175551399",},"звонки":[{"идентификатор":"wacid.HBgLMTIxODU1NTI4MjgVAgARGCAyODRQIAFRoA","к":"12185552828",// Номер телефона пользователя WhatsApp (звонящий)"от":"13175551399",// Рабочий телефонный номер, с которого совершается звонок (звонящий)"событие":"завершить","направление":"БИЗНЕС_ИНИЦИИРОВАН","временная метка":"1749197480",«статус»:["Неуспешный","Завершенный"],"start_time":"1671644824",// Начало вызова метки времени UNIX"end_time":"1671644944",// Метка времени завершения вызова UNIX"продолжительность":480// Длительность вызова в секундах}]},"поле":"звонки"}]}]}
      Конечные точки для звонков, инициированных бизнесом
      

      

      

      

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

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

      

      

      Запрос
синтаксис
      ПОЧТА <НОМЕР_ТЕЛЕФОНА_ИДЕНТИФИКАТОР>/звонки
      
Заполнитель

Описание

Пример значения

      <PHONE_NUMBER_ID>
      Целое число
      Необходимый

      
Идентификатор номера телефона компании, с которого вы инициируете новый звонок.
      106540352242922
      Текст запроса
      {"messaging_product":"WhatsApp","к":"14085551234","действие":"соединять","сессия":{"sdp_type":"предложение","sdp":«<<RFC 8866 SDP> >"},"biz_opaque_callback_data":"0fS5cePMok"}
      Параметры тела
      

      
Параметр
      

      
Описание
      

      		
Пример значения

      к
      Целое число
      Необходимый

      
Вызываемый номер (звонящий)
      “17863476655”
      действие
      Нить
      Необходимый

      
Действие, выполняемое в отношении указанного идентификатора вызова.
      Значения могут быть соединять | pre_accept | принимать | отклонять | завершить
      "соединять"
      сессия
      JSON-объект
      Необязательный

      
Содержит тип протокола описания сессии (SDP) и язык описания.
      Требуется два значения:
      sdp_type — (Нить) Необходимый
      «Предложение» обозначает предложение SDP
      sdp — (Нить) Необходимый
      Информация SDP устройства на другом конце вызова. SDP должен соответствовать определенным требованиям RFC 8866⁠.
      "сессия":{"sdp_type":"предложение","sdp":«<<RFC 8866 SDP> >"}
      biz_opaque_callback_data
      Нить
      Необязательный

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

      {"messaging_product":"WhatsApp","звонки":[{"идентификатор":"wacid.ABGGFjFVU2AfAgo6V",}]}
      

      

      

      

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

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

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



        

        

        

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

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

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

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

        

        

        

        ЗапросТело синтаксиспараметры
        

        ПОЧТА
<НОМЕР_ТЕЛЕФОНА_ИДЕНТИФИКАТОР>/звонки
        



Параметр 

Описание 

Пример значения 




        <PHONE_NUMBER_ID>
        Целое число
        Необходимый

        
Рабочий телефонный номер, с которого вы завершаете звонок.
        18274459827
        Текст запроса
        {"messaging_product":"WhatsApp","call_id":"wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh","действие":"завершить"}
        Параметры тела
        
Параметр

Описание

Пример значения

        call_id
        

        Нить
        


        

        Необходимый
        


        
Идентификатор телефонного звонка.
        

        При входящих звонках вы получаете идентификатор вызова от веб-перехватчика Call Connect, когда звонок инициирует пользователь WhatsApp.
        


        

        “wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh”
        



        

        действие
        

        Нить
        


        

        Необходимый
        


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

        Значения могут быть связаны | предварительное принятие | принятие | отклонение | завершение
        


        

        «прекратить»
        

        

        

        

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

        {"messaging_product":"WhatsApp","успех":истинный}
        

        

        

        

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

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

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



          

          

          

          Веб-хуки для инициированных бизнес-звонков
          

           внутри  "value" ответа вебхука находится  "calls"  "calls" содержит метаданные о звонке, которые используются для обработки каждого звонка, совершенного или принятого вашей компанией.
          

          Чтобы получать веб-хуки Calling API, подпишитесь на поле веб-хука «calls».
          


          

          

          Вызов
подключить веб-перехватчик
          Вы получаете уведомление через веб-хук практически в режиме реального времени, когда звонок, инициированный вашей компанией, готов к соединению с пользователем WhatsApp ( Ответ SDP).
          Крайне важно, что веб-перехватчик содержит информацию, необходимую для установления соединения через WebRTC.
          После получения веб-перехватчика Call Connect вы можете его применить Ответ SDP Получено в веб-хуке для вашего стека WebRTC, чтобы инициировать медиасоединение.
          {"объект":"whatsapp_business_account","вход":[{"идентификатор":"<WHATSAPP_BUSINESS_ACCOUNT_ID> ","изменения":[{"ценить":{"messaging_product":"WhatsApp","метаданные":{"display_phone_number":"16315553601","идентификатор_номера_телефона":"<PHONE_NUMBER_ID> "},"контакты":[{"ва_ид":"16315553602"}],"звонки":[{"идентификатор":"wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh","к":"16315553601","от":"16315553602","событие":"соединять","временная метка":"1671644824","направление":"БИЗНЕС_ИНИЦИИРОВАН","сессия":{"sdp_type":"отвечать","sdp":«<<RFC 8866 SDP> >"}}]},"поле":"звонки"}]}]}
          Значения веб-перехватчика для "звонки"
          
Заполнитель

Описание

          идентификатор
          Нить
          Уникальный идентификатор для вызова
          к
          Целое число
          Вызываемый номер (звонящий)
          от
          Целое число
          Номер звонящего
          событие
          Целое число
          Событие вызова, о котором этот веб-перехватчик уведомляет подписчика
          метка времени
          Целое число
          Временная метка UNIX события веб-перехватчика
          направление
          Нить
          Направление совершаемого звонка.
          Может содержать либо:
          ИНИЦИИРОВАННЫЙ БИЗНЕСдля звонков, инициированных вашей компанией.
          ИНИЦИИРОВАННЫЙ ПОЛЬЗОВАТЕЛЕМдля звонков, инициированных пользователем WhatsApp.
          сессия
          JSON-объект
          Необязательный

          
Содержит тип протокола описания сессии (SDP) и язык описания.
          Требуется два значения:
          sdp_type — (Нить) Необходимый
          «Предложение» обозначает предложение SDP
          sdp — (Нить) Необходимый
          Информация SDP устройства на другом конце вызова. SDP должен соответствовать определенным требованиям RFC 8866⁠.
          контакты
          JSON-объект
          wa_id — WhatsApp ID вызывающего абонента.
          веб-перехватчик статуса вызова
          

          Этот веб-перехватчик отправляется при следующих событиях вызова:
          

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

            Здесь используется структура веб-хуков, аналогичная структуре веб-хуков статуса, применяемых для сообщений Cloud API.
            

            {"объект":"whatsapp_business_account","вход":[{"идентификатор":"<WHATSAPP_BUSINESS_ACCOUNT_ID> ","изменения":[{"ценить":{"messaging_product":"WhatsApp","метаданные":{"display_phone_number":"16315553601","идентификатор_номера_телефона":"<PHONE_NUMBER_ID> ",},"статусы":[{"идентификатор":"wacid.ABGGFjFVU2AfAgo6V","временная метка":"1671644824","тип":"вызов"«статус»:"[ЗВОНОК|ПРИНЯТО|ОТКЛОНЕНО]","recipient_id":"163155536021","biz_opaque_callback_data":"random_string",}]},"поле":"звонки"}]}]}
            


            

            

            

            Значения веб-хуков для "статусов"
            

            

            



Заполнитель 

Описание 




            

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

            Нить
            


            

            Уникальный идентификатор для вызова
            



            

            метка времени
            

            Целое число
            


            

            Временная метка UNIX события веб-перехватчика
            



            

            recipient_id
            

            Целое число
            


            

            Номер телефона пользователя WhatsApp, принимающего звонок
            



            

            статус
            

            Целое число
            


            

            Текущий статус вызова.
            

            Возможные значения:
            

            ЗВОНОК : Инициированный компанией звонок поступает на абонента.
            

            ПРИНЯТО : Звонок, инициированный компанией, принят пользователем.
            

            ОТКЛОНЕНО : Звонок, инициированный представителем компании, отклонен пользователем.
            



            

            biz_opaque_callback_data
            

            Нить
            


            

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

            Возвращается только в том случае, если предоставлено через запросы API Initiate New Call.
            

            

            

            

            Вызов завершения веб-перехватчика
            

            Уведомление через веб-хук отправляется всякий раз, когда вызов завершается по какой-либо причине, например, когда пользователь WhatsApp кладёт трубку или когда компания вызывает POST-запрос. /вызывает конечную точку с действием завершения или отклонения .
            

            {"объект":"whatsapp_business_account","вход":[{"идентификатор":"<WHATSAPP_BUSINESS_ACCOUNT_ID> ","изменения":[{"ценить":{"messaging_product":"WhatsApp","метаданные":{"display_phone_number":"16505553602","идентификатор_номера_телефона":"<PHONE_NUMBER_ID> ",},"звонки":[{"идентификатор":"wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh","к":"16315553601","от":"16315553602","событие":"завершить""направление":"БИЗНЕС_ИНИЦИИРОВАН","biz_opaque_callback_data":"random_string","временная метка":"1671644824",«статус»:[НЕУСПЕШНЫЙ
            
|
            
ЗАВЕРШЕННЫЙ],"start_time":"1671644824","end_time":"1671644944","продолжительность":120}],"ошибки":[{"код":
            
INT_CODE,"сообщение":"ERROR_TITLE","href":"ERROR_HREF","error_data":{"подробности":"ПОДРОБНОСТИ ОШИБКИ"}}]},"поле":"звонки"}]}]}
            

            Значения веб-хуков для "вызовов"
            

            

            



Заполнитель 

Описание 




            

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

            Нить
            


            

            Уникальный идентификатор для вызова
            



            

            к
            

            Целое число
            


            

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



            

            от
            

            Целое число
            


            

            Номер звонящего
            



            

            событие
            

            Целое число
            


            

            Событие вызова, о котором этот веб-перехватчик уведомляет подписчика
            



            

            метка времени
            

            Целое число
            


            

            Временная метка UNIX события веб-перехватчика
            



            

            направление
            

            Нить
            


            

            Направление совершаемого звонка.
            

            Может содержать либо:
            

            BUSINESS_INITIATED — для звонков, инициированных вашей компанией.
            

            USER_INITIATED — для звонков, инициированных пользователем WhatsApp.
            



            

            время начала
            

            Целое число
            


            

            Временная метка UNIX, указывающая на начало звонка.
            

            Присутствует только тогда, когда на звонок ответил другой абонент.
            



            

            конец_времени
            

            Целое число
            


            

            Временная метка UNIX, отражающая момент завершения звонка.
            

            Присутствует только тогда, когда на звонок ответил другой абонент.
            



            

            продолжительность
            

            Целое число
            


            

            Продолжительность разговора в секундах.
            

            Присутствует только тогда, когда на звонок ответил другой абонент.
            



            

            biz_opaque_callback_data
            

            Нить
            


            

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

            Возвращается только в том случае, если предоставлено через запрос API Initiate Call или запрос Accept Call.
            



            

            ошибки.код
            

            Целое число
            


            

            Объект errors присутствует только для неудачных вызовов, если доступна информация об ошибке. Code — это один из кодов ошибок вызова.
            

            

            

            

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

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

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

            
    
                    
            
    
            

            
            
        
            
    
            

    
            

    
    
            
        
            
             Вернуться наверх