Skip to main content

Что это такое

Подпишитесь на whatsapp.meta_business_agent.handover.updated. Вы получаете это событие, когда YCloud обрабатывает поддерживаемый обратный вызов передачи/управления для созданного через API Meta Business Agent. Оно сообщает о передаче управления, а не о результате назначения в Inbox или о кастомном сообщении о передаче диалога. В отличие от двух событий Echo, это событие намеренно сохраняет объект whatsappMetaBusinessAgent, поскольку метаданные агента и управления являются частью контракта передачи управления.

Перед началом работы

  1. Подключите агента через Public REST API.
  2. Подпишите активную конечную точку Webhook в том же аккаунте на whatsapp.meta_business_agent.handover.updated.
  3. Проверяйте YCloud-Signature по исходному телу запроса, надежно принимайте каждое событие и обрабатывайте его идемпотентно.
Агенты, созданные в консоли, не отправляют этот пользовательский Webhook. Синхронизация их Inbox представляет собой отдельный процесс.
См. раздел Настройка веб-перехватчиков для настройки конечной точки.

Принцип работы

Во всех примерах используются подстановочные идентификаторы. Маршрутизируйте по внешнему свойству type и считывайте whatsappMetaBusinessAgent, а не whatsappMessage, whatsappEchoMessage или data. Выполняйте дедупликацию повторных доставок с помощью внешнего поля id. Вложенное поле timestamp является целым числом в миллисекундах Unix; createTime представляет собой строку в формате RFC 3339.
  • В настоящее время значение controlState равно APP_CONTROL_TAKEN для поддерживаемых обратных вызовов передачи управления API Agent.
  • Поле consumerPhoneNumber берется из sender.phone_number обратного вызова передачи управления и при корректности нормализуется в формат E.164. Оно не является бизнес-номером или phoneNumberId.
  • Текущий контракт передачи управления не предоставляет recipientUserId или parentRecipientUserId. Отсутствующий идентификатор клиента не восстанавливается из соседнего обратного вызова сообщения.
  • Для приведенного ниже примера control_passed поле actor идентифицирует приложение предыдущего владельца, а не принимающего сотрудника.
  • reason — это опциональные метаданные провайдера. Относитесь к ним как к произвольной строке, а не как к фиксированному перечислению (enum).
  • Это не уведомление для каждого запроса take, release, Set Live или Set Draft. Обратные вызовы управления, обработанные, пока агент находится в состоянии Draft, игнорируются.
Полезная нагрузка не создает вымышленную идентификацию клиента. Поле consumerPhoneNumber опускается, когда обратный вызов не содержит корректный номер телефона, и BSUID не выводится из соседних сообщений. Поле phoneNumberId идентифицирует бизнес-номер, который может обслуживать множество клиентов.
Не рассматривайте это событие как подтверждение того, что сотрудник был назначен или что кастомное сообщение о передаче диалога было отправлено или доставлено.

Запрос

YCloud отправляет эти тела JSON в HTTP-запросах POST на настроенный вами URL-адрес Webhook.

Ответ

Возвращайте ответ 2xx после надежного принятия события. Длительные операции выполняйте асинхронно.

Агент передает управление вашему приложению

Запрос

APP_CONTROL_TAKEN сообщает о передаче управления, а не о назначении сотрудника Inbox или о доставке кастомного сообщения о передаче диалога. В этом примере actor — это ID приложения предыдущего владельца.

Ответ

Пояснение

Используйте consumerPhoneNumber, чтобы сопоставить переход управления с клиентом, если это поле присутствует. Не делайте выводов о назначении в Inbox или о доставке сообщения на основе этого события.

Связанные примеры