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

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

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

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

Обзор

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

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

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

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

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

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

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

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

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

      Теперь, когда у вас есть разрешение пользователя, вы можете инициировать новый звонок нужному пользователю WhatsApp.
      Теперь вы можете позвонить на почту. Для инициирования нового вызова необходимо передать в тело запроса следующую конечную точку:
      ПОЧТА
      <НОМЕР_ТЕЛЕФОНА_ИДЕНТИФИКАТОР>/звонки {"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 уже завершил звонокВызов с отклонением уже выполняетсяОшибки доступа/авторизации



          

          

          

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

          находится "calls" внутри "value" ответа вебхука "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 используется для согласования параметров передачи данных между отправителем и получателем, позволяя им согласовать специфику обмена данными.
            

            
    
                    
            
    
            

            
            
        
            
    
            

    
            

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