Голосовые и видеозвонки WhatsApp в UnifyPort: закрытая бета

Клиент описал проблему в WhatsApp, но ещё один абзац не поможет её прояснить. Оператору нужно обсудить детали доставки или увидеть проблему через камеру. Закрытая бета UnifyPort позволяет подготовить голосовой или видеозвонок WhatsApp один на один из вашего бизнес-приложения, дать оператору запустить его в браузере и получать события состояния звонка на вашем сервере.

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

Что добавляет бета звонков

В справочнике API звонков теперь описаны три операции:

• POST /v1/calls подготавливает голосовой или видеозвонок и возвращает одноразовый join_url с коротким сроком действия.
• GET /v1/calls/active получает текущий звонок выбранного аккаунта, которым управляет UnifyPort.
• POST /v1/calls/{call_id}/hangup завершает выбранный звонок.

Два события Webhook помогают приложению отслеживать разговор: call.answered сообщает о соединении, а call.ended — о завершении, его причине и длительности после соединения. Эти возможности позволяют разработчикам добавить разговор с оператором в существующий процесс поддержки.

API-запрос подготавливает звонок. Чтобы позвонить, оператор открывает полученную ссылку и нажимает Start call. Сделайте это действие явным в интерфейсе, чтобы оператор мог проверить выбранного клиента перед началом звонка.

Когда вместо переписки нужен разговор

Рассмотрим несколько возможных сценариев поддержки:

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

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

В общем ящике можно добавить действие звонка рядом с выбранным чатом WhatsApp. Используйте conversation_id этого чата из подключённого аккаунта мессенджера: API звонков не принимает произвольную строку с номером телефона. Назначение оператора и закрытие обращения остаются в вашем приложении, как описано в руководстве по общему ящику WhatsApp.

Подготовьте звонок и дайте оператору запустить его

Сначала запросите бета-доступ для рабочего пространства и подключите авторизованный аккаунт WhatsApp. Если подключение аккаунта ещё не настроено, руководство по аутентификации через QR и Passkey описывает этот отдельный этап настройки.

Отправьте запрос на создание с вашего сервера, используя X-Api-Key рабочего пространства. Следующий JSON показывает документированное тело запроса. Перед отправкой в POST /v1/calls замените acc_example и <conversation_id> на выбранный аккаунт и настоящий идентификатор его диалога:

{
  "account_id": "acc_example",
  "to": {
    "id": "<conversation_id>",
    "type": "user"
  },
  "media_type": "video"
}

Укажите voice для голосового звонка или video для звонка с поддержкой видео. Храните API-ключ на сервере и передавайте полученный join_url только нужному оператору по закрытому каналу.

При создании возвращается 201 Created с полями call_id, state: preparing, join_url и expires_at. Этот ответ не означает, что клиенту уже позвонили или что он ответил.

По умолчанию период подготовки составляет две минуты с момента создания. Фактический срок берите из возвращённого expires_at, поскольку сервер может его менять. До этого срока оператор должен открыть ссылку и нажать Start call. Срок подготовки не ограничивает длительность разговора после соединения.

Браузеру требуется разрешение на доступ к микрофону; доступ к камере необязателен. Считайте ссылку приватной и одноразовой: не публикуйте её и не записывайте полный URL в журнал.

Верните состояние звонка в рабочий процесс

Сохраните полученный call_id в собственной системе вместе с выбранным аккаунтом, диалогом и обращением в поддержку. Endpoint текущего звонка позволяет при необходимости получить управляемый звонок, в том числе если его идентификатор был потерян. Если управляемого звонка нет, он возвращает data: {}. Он не определяет, разговаривает ли кто-либо из участников в мобильном приложении WhatsApp.

Подпишитесь на call.answered и call.ended, чтобы обновлять запись о звонке в приложении. Если subscribed_events задан явным списком, в него нужно включить эти названия событий. Для рабочих пространств с бета-доступом *, пустой список или отсутствие списка включает разрешённые события звонков. Обычные рабочие пространства не получают их через подписку с wildcard.

Событие завершения содержит data.call.id, reason и duration_seconds. Длительность — это время после соединения, округлённое вниз до целых секунд, поэтому одно значение 0 не доказывает, что звонок остался без ответа. Отслеживайте также событие ответа. При синхронной ошибке создания callback о завершении может не прийти; обрабатывайте HTTP-ошибку отдельно.

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

Границы текущей закрытой беты

Эта бета поддерживает голосовые и видеозвонки WhatsApp один на один, которые запускаются через браузер. Групповые звонки, звонки в каналах, звонки в других мессенджерах и обработка входящих звонков сейчас не входят в её возможности. Документированное событие call.incoming — зарезервированный контракт: его наличие в каталоге событий не открывает приём звонков.

Запись разговоров, транскрибация, интеграция с SIP/PBX и голосовые AI-агенты не входят в возможности этой беты. UnifyPort предоставляет неофициальный интерфейс. Статья описывает собственный контракт звонков UnifyPort и не представляет его как официальный WhatsApp Business Calling API от Meta.

Флаг рабочего пространства is_beta доступен только для чтения и по умолчанию выключен. Доступ должна включить техническая поддержка. Рабочее пространство без доступа при обращении к API звонков получает 403 beta_feature_not_enabled с числовым кодом 41002. Изменение metadata или отправка PATCH для рабочего пространства не включает доступ.

Вопросы перед началом

Можно начать звонок, указав только номер телефона?

Нет. Используйте настоящий conversation_id выбранного аккаунта WhatsApp вместе с to.type: user.

API сразу набирает номер?

Нет. Он подготавливает ссылку на звонок. Чтобы позвонить, человек открывает ссылку и нажимает Start call до срока expires_at.

Звонки ограничены двумя минутами?

Нет. Две минуты — период подготовки по умолчанию с момента создания. Это не ограничение длительности разговора после соединения.

Может ли команда отвечать на входящие звонки с бета-доступом?

Нет. Входящие звонки в текущей бете недоступны, в том числе рабочим пространствам с is_beta: true.

Запросите доступ для команды

Обратитесь в техническую поддержку, чтобы запросить бета-доступ к звонкам для вашего рабочего пространства. Чтобы объяснить планируемое применение, рекомендуем указать ID рабочего пространства, сценарий поддержки в WhatsApp и потребность в голосовых или видеозвонках. Это полезные сведения для заявки, а не процедура автоматической регистрации. Не включайте в заявку API-ключи и приватные ссылки на звонки.

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