Skip to main content

​
Что это такое

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

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

  1. Подключите Agent через 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. Обратные вызовы управления, обработанные, когда Agent находится в состоянии Draft, игнорируются.
Полезная нагрузка не генерирует фиктивную идентификацию клиента. consumerPhoneNumber опускается, если обратный вызов не предоставляет валидный номер телефона, и никакой BSUID не выводится из соседних сообщений. phoneNumberId идентифицирует номер компании, который может обслуживать множество клиентов.
Не рассматривайте это событие как подтверждение того, что сотрудник был назначен или что кастомное сообщение о передаче было отправлено либо доставлено.

​
Запрос

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

​
Ответ

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

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

​
Запрос

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

​
Ответ

​
Объяснение

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

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