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

Устранение ошибок при совершении звонков в WhatsApp — справочное руководство | Документация для разработчиков

Устранение ошибок при совершении звонков в WhatsApp — справочное руководство

Обновлено: 3 декабря 2025 г

Стандартный ответ об ошибке

В большинстве случаев при возникновении ошибки её форма будет выглядеть следующим образом:
{
"ошибка": { "сообщение": "<Error Message> ", "тип": "<Exception Type> ", "код":<Exception Code> , "fbtrace_id": "<Trace ID> " } }
Используйте приведенный ниже список кодов ошибок вызова API для выявления и устранения ошибок вызова.

Журналы звонков

« Журнал звонков» в WhatsApp Manager предоставляет компаниям и партнерам подробный, удобный для самостоятельного просмотра событий звонков, что помогает в устранении неполадок во время разговоров.
На вкладке отображается таблица последних звонков на телефонные номера вашей компании. Для каждого звонка есть свой журнал. Каждый журнал может содержать несколько событий, представляющих собой запрос к Graph API, сделанный компанией, или веб-перехватчик, отправленный Meta. Каждая строка представляет собой звонок, при этом выделены разные столбцы, предоставляющие информацию о каждом звонке.

Как просмотреть журналы звонков

    Перейдите в WhatsApp Manager > Инструменты учетной записи > Номера телефонов .Выберите нужный номер телефона, чтобы просмотреть журнал звонков

    Журналы звонков и события

    Поле Описание
    Отметка времени
    Отметка времени, когда произошёл звонок.
    Направление вызова
    Исходящие (инициированные бизнесом) или входящие (инициированные пользователем).
    Сигнализация
    Протокол сигнализации, используемый для установления соединения (SIP, GRAPH_API).
    Идентификатор вызова
    Идентификатор звонка WhatsApp.
    Примечание: Пожалуйста, указывайте этот идентификатор при обращении в службу поддержки.
    Идентификатор запроса
    Идентификатор запроса, инициировавшего вызов.
    Детали звонка
    Дополнительная информация, содержащая журнал событий на протяжении всего жизненного цикла вызова.

    Коды ошибок вызова

    Код Описание Возможные решения Код состояния HTTP
    100
    Недопустимый параметр
    В вашем вызове Graph API обнаружен недопустимый параметр.
    Подробные сведения об ошибке будут указаны в error_data полезной нагрузки ответа.
    Если это ошибка, связанная с проверкой SDP, то точное описание проблемы будет указано в подробностях.
    400
    Неверный запрос
    613
    Получение разрешения на вызов для номера телефона потребителя. Достигнут лимит API
    Достигнут лимит запросов к API получения статуса разрешения на вызов.
    Попробуйте позже или уменьшите частоту или количество запросов к API, которые отправляет приложение.
    429
    Слишком много запросов
    131009
    Тип интерактивного сообщения, voice_call не поддерживается. Поддерживаемые типы: [ button , list ]
    Убедитесь, что отправитель находится в одной из поддерживаемых стран .
    400
    Неверный запрос
    131030
    Номер телефона получателя отсутствует в списке разрешенных номеров.
    Ошибка возникает как при попытках совершения звонков, так и при запросах на разрешение совершения звонков.
    Это происходит только при использовании общедоступных тестовых номеров (PTN).
    Добавьте номер телефона получателя в список получателей и попробуйте снова.
    400
    Неверный запрос
    138000
    Функция звонков отключена
    Для этого номера телефона API для совершения звонков отключены
    Звонки на рабочий телефонный номер недоступны.
    401
    Несанкционированный доступ
    138001
    Получатель недоступен для вызова
    Приёмник не может принимать звонки
    Причины могут включать в себя:
      Номер телефона получателя не является номером телефона WhatsApp.Получатель не принял наши новые Условия предоставления услуг и Политику конфиденциальности.Получатель использует неподдерживаемое приложение. В настоящее время поддерживаются следующие приложения: Android, iOS, SMB Android и SMB iOS
      Уточните у получателя, согласен ли он на то, чтобы вы связывались с ним через WhatsApp, и использует ли он последнюю версию WhatsApp.
      400
      Неверный запрос
      138002
      Ограничение на количество одновременных звонков
      Достигнут лимит на максимальное количество одновременных вызовов (1000) для заданного числа
      Попробуйте позже или уменьшите частоту или объем вызовов API, которые выполняет приложение.
      429
      Слишком много запросов
      138003
      Повторный вызов
      Разговор с принимающей стороной уже идёт
      Попробуйте позже, когда текущий звонок завершится.
      400
      Неверный запрос
      138004
      Ошибка подключения
      Ошибка при установлении соединения
      Попробуйте позже или изучите параметры подключения, предоставленные API.
      500
      Ошибка сервера
      138005
      Превышен лимит количества звонков
      Достигнут лимит на максимальное количество звонков, которые могут быть инициированы с корпоративного телефонного номера
      Попробуйте позже или уменьшите частоту или объем вызовов API, которые выполняет приложение.
      429
      Слишком много запросов
      138006
      Разрешение на вызов не найдено
      От получателя не получено одобрение на совершение звонка.
      Убедитесь, что потребитель дал согласие на совершение звонка
      401
      Несанкционированный доступ
      138007
      Ошибка "Таймаут подключения"
      Звонок не удалось установить из-за истечения времени ожидания
      Компания не применила SDP-пакет предложения/ответа из Cloud API вовремя. API Connect не был вызван с SDP-пакетом ответа вовремя
      500
      Ошибка сервера
      138009
      Превышен лимит запросов на разрешение вызова
      Достигнут лимит запросов на разрешение вызова, отправленных для указанной пары "бизнес-пользователь" и "потребитель"
      Если компания отправляет больше запросов на разрешение вызова, чем позволяет лимит за определенный период времени, устанавливается ограничение на количество запросов на разрешение вызова. Установление соединения с клиентом приведет к сбросу лимита.
      400
      Неверный запрос
      138012
      Достигнут лимит звонков, инициированных компанией
      Достигнут лимит на максимальное количество деловых звонков, разрешенных в течение 24 часов. В настоящее время разрешено 100 подключенных деловых звонков в течение 24 часов.
      Подробные сведения об ошибке будут указаны в error_data полезной нагрузки ответа.
      В подробности будет включена отметка времени, когда будет разрешен следующий звонок.
      400
      Неверный запрос
      138013
      Возможность совершения деловых звонков недоступна
      Для этого корпоративного номера телефона недоступна возможность совершения деловых звонков.
      Убедитесь, что для этого корпоративного номера телефона доступна функция совершения звонков по инициативе компании, в разделе «Доступность» здесь .
      400
      Неверный запрос
      138014
      Функция звонков временно отключена
      Доступ к API для звонков на этот бизнес-номер WhatsApp временно отключен из-за низкого качества связи.
      Убедитесь, что ваше взаимодействие с пользователями является ценным и не представляет собой спам.
      Повторите действие после снятия ограничений на учетную запись.
      400
      Неверный запрос
      138015
      Функция звонков недоступна
      Для этого номера телефона невозможно включить API для совершения звонков.
      Проверьте и убедитесь, что лимит сообщений на вашем телефонном номере составляет 2000 или более.
      400
      Неверный запрос
      138017
      Запрос на разрешение вызова не может быть отправлен, поскольку постоянное разрешение уже существует.
      Запрос на разрешение на совершение звонка не может быть отправлен, поскольку пользователь уже одобрил постоянное разрешение для этого номера телефона корпоративного аккаунта.
      Нет необходимости отправлять запросы на разрешение вызова.
      400
      Неверный запрос
      138018
      Функция звонков WhatsApp Business не может быть включена, поскольку не выполнены технические требования.
      Более подробная информация в разделе «Предварительные требования»
      Настройте SIP или убедитесь, что к бизнес-аккаунту WhatsApp подключено хотя бы одно приложение, которое также подключено к звонков .
      400
      Неверный запрос
      138019
      Не удалось установить соединение
      Клиент WhatsApp не смог установить соединение.
      Эта ошибка отправляется в веб-перехватчике завершения вызова.
      Попробуйте позже.
      400
      Неверный запрос
      138020
      Соединение с ретранслятором не удалось
      Клиент WhatsApp не смог установить соединение с ретрансляционным сервером.
      Эта ошибка отправляется в веб-перехватчике завершения вызова.
      Попробуйте позже.
      400
      Неверный запрос
      138021
      Медиафайлы получают тайм-аут
      Приложение WhatsApp прервало звонок из-за длительного отсутствия входящих сообщений.
      Эта ошибка отправляется в веб-перехватчике завершения вызова.
      Убедитесь, что медиаданные вызова передаются на ретранслятор, и повторите попытку.
      400
      Неверный запрос
      138022
      Таймаут передачи медиафайлов
      Приложение WhatsApp прервало звонок из-за длительной отсутствия передачи мультимедийных данных.
      Эта ошибка отправляется в веб-перехватчике завершения вызова.
      Попробуйте позже.
      400
      Неверный запрос
      138023
      Вызов принят, но прерван без передачи медиасигнала
      Вызов был принят, но завершился без сигнала подключения к сети.
      Облачный API не смог определить, установлено ли соединение.
      Эта ошибка отправляется в веб-перехватчике завершения вызова.
      Попробуйте позже.
      400
      Неверный запрос
      131044
      При отсутствии действительного способа оплаты на вызовы, инициированные пользователем, отправляется веб-хук с ошибкой
      Это похоже на «Проблема с выплатой пособия бизнесу», которая появляется в сообщениях.
      400
      Неверный запрос
      131055
      Этот метод не разрешен. Вызовы Graph API для номеров с поддержкой SIP запрещены
      Используйте SIP для бизнес-номеров, поддерживающих SIP.
      400
      Неверный запрос

      Ошибки SIP

      Для получения дополнительной информации по устранению неполадок также обратитесь к разделу часто задаваемых вопросов (FAQ) по протоколу SIP.

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

      Статус и сообщение SIP Описание Возможные решения
      400
      Актив не найден, неверный номер телефона компании
      Номер телефона в «От» приглашения недействителен и не соответствует зарегистрированному аккаунту на платформе WhatsApp Business.
      Проверьте номер телефона и повторно отправьте приглашение с правильным From . См. примеры.
      403
      SIP-сервер foo.com, полученный по приглашению INVITE, не соответствует ни одному SIP-серверу, настроенному для идентификатора телефонного номера [ID].
      В вашем SIP INVITE-запросе к Meta в From указано (например, [email protected] на рабочем телефонном номере нет SIP-сервера с таким именем хоста
      Проверьте конфигурацию SIP и убедитесь, что она соответствует домену, указанному в From . Имя хоста в конфигурации SIP должно совпадать с доменом в From вашего SIP INVITE. Также допустимо, чтобы имя хоста являлось поддоменом домена в From . Например, настроенный SIP-сервер — bar.foo.com , а заголовок From — [email protected]
      403
      Разрешение на совершение вызова не найдено: Получатель не предоставил разрешение на совершение вызова
      Нет пользователя WhatsApp с указанным номером, или пользователь не принял наши новые Условия предоставления услуг, или у пользователя нет разрешения на звонок в компанию. Meta не может с уверенностью подтвердить наличие номера телефона в WhatsApp по соображениям конфиденциальности. Поэтому вы можете получить эту ошибку по нескольким причинам.
      Дважды проверьте номер телефона пользователя и убедитесь, что вы получили разрешение пользователя. См Получение разрешений пользователя на вызов  для получения дополнительной информации
      403
      Приложение [APP_ID], настроенное для SIP-сервера example.com, не авторизовано для телефонного номера с идентификатором [ID].
      При настройке SIP-сервера на рабочем телефоне Meta извлекает идентификатор приложения из токена доступа и сохраняет сопоставление SIP-сервера с этим идентификатором приложения. При отправке SIP INVITE Meta обращается к этому сопоставлению, чтобы определить, какое приложение отправляет SIP-запрос. Эта ошибка означает, что у приложения нет whatsapp_business_messaging на рабочем телефоне.
      Убедитесь, что вы используете правильное приложение и что у него есть необходимые разрешения на рабочем телефоне. Если вы можете отправлять сообщения, используя токен доступа приложения, это означает, что у приложения есть необходимые разрешения. В противном случае вам может потребоваться удалить и добавить SIP-сервер с правильным приложением и повторить попытку отправки SIP-сообщения INVITE. См. раздел « Настройка параметров SIP» .
      403
      Достигнут лимит подключенных звонков в день, инициированных компанией
      Достигнут лимит на максимальное количество деловых звонков, разрешенных в течение 24 часов. В настоящее время разрешено 5 деловых звонков в течение 24 часов.
      Подробнее об ограничениях и скорректируйте тариф на звонки можно здесь.
      403
      К дополнительным причинам для получения номера 403 относятся:
        Повторный вызов, поскольку между данной компанией и учетной записью пользователя может быть активен только один вызовНеверный ответ дайджест-аутентификацииВопрос о выплате пособия для бизнесаОшибка проверки SDP
        Подробности см. в описании каждой ошибки
        Обратитесь к предыдущим разделам этой страницы, например, к кодам ошибок при вызове.
        404
        Не найдено
        Использование IP-адреса в URI запроса для SIP-приглашений запрещено
        Используйте правильный URI запроса. См. примеры.
        407
        Требуется аутентификация прокси-сервера
        Meta требует использования дайджест-аутентификации для ваших SIP INVITE-запросов, и это стандартный ответ-запрос от Meta
        Повторно отправьте SIP INVITE с ответом в формате дайджеста. См. примеры.
        408
        Таймаут RTP
        Приложение WhatsApp прервало звонок из-за длительного отсутствия входящих сообщений.
        480
        Временно недоступно
        Пользователь WhatsApp недоступен или не ответил на звонок
        Попробуйте отправить сообщение или позвонить позже. Неотвеченные звонки влияют на права доступа к вызовам. Узнайте больше.
        486
        Пользователь отклонил звонок
        Пользователь WhatsApp отклонил ваш звонок
        Попробуйте отправить сообщение или позвонить позже. Отклоненные вызовы влияют на права доступа к вызовам. Узнайте больше.
        487
        Запрос завершен
        Компания отменила свой SIP INVITE с помощью команды SIP CANCEL
        Ожидаемая доходность вашего SIP INVITE при отмене INVITE до получения ответа от Meta на ваш INVITE
        503
        Сервис недоступен
        Общая внутренняя ошибка.
        Повторите запрос через некоторое время или обратитесь в службу поддержки Meta
        Проблема Описание Возможные решения
        Звонок обрывается через 20 секунд после начала разговора
        Если в начале звонка в течение 20 секунд отсутствует передача медиаконтента от компании к пользователю WhatsApp, звонок будет прерван из-за отсутствия медиасообщений
          Проверьте свой медиасервер, чтобы убедиться, что он инициирует медиасессию и отправляет медиапакетыПроверьте свой брандмауэр, чтобы исключить потерю пакетов на границе сетиЗахватите сетевой трафик с помощью pcap или аналогичного инструмента и прикрепите его к заявке в службу поддержки для дальнейшего устранения неполадок компанией Meta
          Звук не слышен, звонок обрывается через 30 секунд
          После установления соединения, если в течение 30 секунд от компании к пользователю WhatsApp не поступает медиапакет, клиент WhatsApp разорвет соединение из-за отсутствия приема медиапакета
            Убедитесь, что вы отправляете как минимум пакеты RTCP даже в условиях тишины или ожидания ввода от пользователя (например, в IVR)Проверьте свой медиасервер, чтобы понять, почему он перестал отправлять медиапакеты в MetaЗахватите сетевой трафик с помощью pcap или аналогичного инструмента и прикрепите его к заявке в службу поддержки для дальнейшего устранения неполадок компанией Meta

            Проблема с искажением звука и её решение

            При передаче медиаданных от пользователя WhatsApp через WebRTC к другому медиаканалу, например, SIP , важно учитывать потенциальные проблемы с искажением звука и способы их предотвращения. Распространенным симптомом этой проблемы является то, что пользователь WhatsApp может пропустить примерно одну секунду звука от компании. Например, если система IVR воспроизводит последовательность «1-2-3», пользователь может услышать только «2» или «3». Степень потери звука варьируется в зависимости от конкретной интеграции и серьезности проблемы.
            Приведенная ниже диаграмма последовательности иллюстрирует эту проблему на примере, где канал WebRTC от Cloud API соединен с каналом передачи медиаконтента SIP. В зависимости от поставщика SIP и реализации, воспроизведение медиаконтента от SIP User Agent может начаться на шаге 11, но оно не достигнет потребителя WhatsApp до шага 18.

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

            Последовательность действий, демонстрирующая процесс соединения вызовов WebRTC и SIP (Щелкните правой кнопкой мыши по изображению и выберите «Открыть в новой вкладке», чтобы увеличить его)
            Компоненты диаграммы последовательности
              WAConsumer — пользователь WhatsApp, звонящий на рабочий телефонный номер с помощью мобильного приложения WhatsApp.Meta — это продукт Cloud API.MetaWebrtcEndpoint — это агент WebRTC в инфраструктуре Meta.BizIntegration — это сервер веб-хуков, принимающий вызовы, связанные с веб-хуками, и сервер приложений с бизнес-логикой для вызова API Cloud API Graph.BizWebrtcEndpoint — это точка завершения WebRTC, а также контроллер UAC SIP, обычно расположенный на медиасервере на вашей стороне.BizSipEndpoint — это SIP-агент пользователя (UA), часто представляющий собой IVR или бизнес-агента.
              Важные моменты, на которые следует обратить внимание
                После получения веб-хука подключения (шаг 5 выше) инициализируйте свой агент WebRTC, подготовьте ответ SDP и выполните вызов Graph API предварительного принятия с этим ответом SDP. Это предварительно устанавливает соединение WebRTC в ожидании ответа «accept/ok» от пользовательского агента SIP (UA). В большинстве случаев на звонок абонента отвечает, например, автоматическая запись или система IVR.На шаге 11, описанном выше, дождитесь завершения процесса ICE по созданию действительных списков, что будет означать скорое завершение установления соединения ICE (см. ссылку RFC).Если SIP-агент отклоняет вызов вместо возврата кода 200 OK, используйте API Graph для завершения вызова.Если соединение с абонентом будет готово раньше, чем соединение по протоколу SIP, абонент может столкнуться с несколькими миллисекундами тишины, что предпочтительнее, чем потеря части первоначального звука от компании.

                Первопричина

                При объединении двух медиаканалов крайне важно, чтобы медиасервер синхронизировал свою готовность, чтобы предотвратить искажение звука. В этом сценарии BizWebrtcEndpoint позволяет SIP-агенту пользователя (UA) передавать медиафайлы значительно раньше, чем WebRTC-канал будет готов их принять. В результате пакеты теряются на медиасервере, что приводит к проблемам с искажением звука.

                Предложенные решения

                Ниже представлен краткий обзор альтернативных подходов к решению проблемы искажения звука, призванный стимулировать обсуждение и рассмотрение. Хотя каждый вариант имеет свои недостатки, вы можете оценить их целесообразность в контексте ваших конкретных требований.
                  Используйте SDES : настройте SDES для номера вашей компании вместо DTLS. Распространенной причиной задержки настройки медиасоединения между вашей инфраструктурой и Meta является завершение рукопожатия DTLS. Meta не может завершить рукопожатие DTLS, пока не получит ваш SDP. Возможно, вы не сможете поделиться своим SDP с Meta, пока ваша внутренняя конечная точка не ответит вам своим SDP. В распространенных реализациях DTLS интервал повторной попытки составляет 1 с, 2 с, 4 с и так далее. После отправки SDP в Meta часто возникает задержка около 3 секунд, прежде чем мы получим ваш пакет DTLS client hello, и именно в это время ваша внутренняя конечная точка отправляет медиаданные, но они теряются. При переключении на SDES вы можете напрямую отправлять SRTP после отправки нам вашего SDP.Воспроизведение звука с задержкой: Укажите SIP-агенту пользователя (UA) ожидать подтверждения (ACK) от BizWebrtcEndpoint перед воспроизведением звука. Подтверждение будет отправлено только после получения успешного ответа от Accept API, после чего последует искусственная задержка. Такой подход гарантирует установление соединения WebRTC до начала воспроизведения звука.Задержка на основе состояния соединения: указывает SIP-агенту подождать, пока состояние соединения WebRTC не станет «подключено», прежде чем воспроизводить звук. Этот метод основан на том, что соединение WebRTC должно быть полностью установлено до начала воспроизведения звука.Буферизованные медиапакеты: SIP-медиапакеты буферизуются и отправляются только после установления соединения WebRTC. Такой подход гарантирует отсутствие потери аудиопакетов из-за преждевременного воспроизведения.Вставка тишины: Вставьте короткий отрезок тишины в аудиозапись IVR перед началом воспроизведения основного аудиоконтента. Этот метод позволяет установить соединение WebRTC во время воспроизведения тишины в IVR, что снижает вероятность искажения звука.Предварительное принятие : Согласно рекомендациям RFC , агент WebRTC, такой как BizWebrtcEndpoint, не должен передавать медиаданные до тех пор, пока процесс ICE не будет практически завершен. В нашем контексте это означает применение стратегии «оптимистичного принятия», вызывая API-вызов предварительного принятия еще до отправки SIP INVITE. Согласно RFC SIP, клиент пользовательского агента (UAC) должен быть готов к приему медиаданных сразу после отправки INVITE. Поэтому рекомендуется инициировать процесс установки соединения WebRTC до отправки SIP INVITE.
                  Эти решения могут иметь различную степень сложности и оказывать различное влияние на вашу систему. Крайне важно оценить их целесообразность и потенциальные компромиссы в контексте вашего конкретного случая использования.

                  Поддерживать

                  Для получения поддержки по API звонков WhatsApp Business выберите WaBiz: Calling API при создании прямой поддержки .
                  Вернуться наверх