whatsapp.meta_business_agent.handover.updated

Используйте whatsapp.meta_business_agent.handover.updated для обработки этого события на вашей конечной точке Webhook.

Триггеры

Происходит, когда поддерживаемый callback-вызов передачи управления передает контроль от Public REST API Agent. Не подтверждает назначение во входящих (Inbox). Подпишитесь на whatsapp.meta_business_agent.handover.updated, когда будете настраивать конечную точку Webhook. Это событие доступно только для агентов, подключенных через Public REST API. Оно сообщает о передаче контроля от агента. Оно не подтверждает назначение во входящих (Inbox).

Синтаксис

YCloud отправляет HTTP-запрос POST на настроенный вами Webhook URL. Ниже показан один из вариантов полезной нагрузки. Значения в угловых скобках являются заполнителями; их типы перечислены в разделе Параметры. Необязательные поля и другие варианты описаны ниже.

{
  "id": "<ID>",
  "type": "whatsapp.meta_business_agent.handover.updated",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "whatsappMetaBusinessAgent": {
    "agentId": "<AGENT_ID>",
    "metaAgentId": "<META_AGENT_ID>",
    "phoneNumberId": "<PHONE_NUMBER_ID>",
    "wabaId": "<WABA_ID>",
    "consumerPhoneNumber": "<CONSUMER_PHONE_NUMBER>",
    "controlState": "<CONTROL_STATE>",
    "actor": "<ACTOR>",
    "reason": "<REASON>",
    "timestamp": "<TIMESTAMP_VALUE>"
  }
}

Параметры

Проверьте HTTP-заголовок YCloud-Signature перед обработкой тела JSON. См. раздел проверка подписи.

Оболочка события

Параметр	Тип	Обязательный	Описание
`id`	string	Да	Уникальный идентификатор события. Минимальная длина: `6`. Максимальная длина: `128`.
`type`	string	Да	Всегда `whatsapp.meta_business_agent.handover.updated`.
`apiVersion`	string	Да	Версия API, используемая для формирования этого события.
`createTime`	string (date-time)	Да	Время создания этого события в формате RFC 3339. Например, `2022-06-01T12:00:00.000Z`.

Полезная нагрузка события

Параметр	Тип	Обязательный	Описание
`whatsappMetaBusinessAgent`	object	Да	Специфичная для события полезная нагрузка `whatsappMetaBusinessAgent`.

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

whatsappMetaBusinessAgent

Параметр	Тип	Обязательный	Описание
`agentId`	string	Нет	Идентификатор агента YCloud. Не является идентификатором агента Meta или идентификатором назначенного сотрудника во входящих (Inbox).
`metaAgentId`	string	Нет	Идентификатор агента Meta, если доступен.
`phoneNumberId`	string	Нет	Идентификатор бизнес-номера телефона Meta. Не является номером телефона в формате E.164.
`wabaId`	string	Нет	Идентификатор WhatsApp Business Account из исходного callback-вызова, если доступен.
`consumerPhoneNumber`	string	Нет	Номер телефона клиента из callback-вызова передачи управления, приведенный к формату E.164, если доступен. Не является бизнес-номером или phoneNumberId. Шаблон: `^+[1-9][0-9]{7,14}$`.
`controlState`	string	Нет	Присутствует для событий передачи управления. В настоящее время APP_CONTROL_TAKEN для callback-вызовов передачи управления через Public REST API. Не подтверждает назначение во входящих (Inbox) или доставку сообщения.
`actor`	string	Нет	Необязательный инициатор источника передачи управления. При передаче с control_passed это идентификатор предыдущего приложения-владельца, а не сотрудник, получающий переписку.
`reason`	string	Нет	Необязательная причина передачи управления или метаданные провайдера, например customer_request. Не является закрытым перечислением (enum).
`timestamp`	integer (int64)	Нет	Исходное время события в миллисекундах Unix или время обработки, если оно недоступно.

Пример

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

{
  "id": "evt_example_agent_handover",
  "type": "whatsapp.meta_business_agent.handover.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:04.000Z",
  "whatsappMetaBusinessAgent": {
    "agentId": "00000000-0000-4000-8000-000000000001",
    "metaAgentId": "META_AGENT_ID",
    "phoneNumberId": "PHONE_NUMBER_ID",
    "wabaId": "WABA_ID",
    "consumerPhoneNumber": "+12025550124",
    "controlState": "APP_CONTROL_TAKEN",
    "actor": "PREVIOUS_OWNER_APP_ID",
    "reason": "customer_request",
    "timestamp": 1788919204000
  }
}

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

HTTP/1.1 200 OK

Пошаговые сценарии см. в разделе примеры с пояснениями.

Начало работы

Руководства

Конечные точки

Webhook reference

whatsapp.meta_business_agent.handover.updated

Триггеры

Синтаксис

Параметры

Оболочка события

Полезная нагрузка события

whatsappMetaBusinessAgent

Пример

​Триггеры

​Синтаксис

​Параметры

​Оболочка события

​Полезная нагрузка события

​whatsappMetaBusinessAgent

​Пример

Триггеры

Синтаксис

Параметры

Оболочка события

Полезная нагрузка события

whatsappMetaBusinessAgent

Пример