> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Передача управления WhatsApp Agent обновлена

> Отслеживайте поддерживаемые обратные вызовы передачи управления Agent и учитывайте ограничения их корреляции.

## Что это такое

Подпишитесь на `whatsapp.meta_business_agent.handover.updated`.

Вы получаете это событие, когда YCloud обрабатывает поддерживаемый обратный вызов передачи/управления для Agent, созданного через API. Оно сообщает о передаче управления, а не о результате назначения во входящих (Inbox) или кастомном сообщении о передаче.

В отличие от двух событий Echo, это событие намеренно сохраняет объект
`whatsappMetaBusinessAgent`, поскольку метаданные Agent и управления являются частью
контракта передачи управления.

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

1. Подключите Agent через [Public REST API](/ru/api-reference/meta-business-agents/onboard).
2. Подпишите активную конечную точку Webhook в том же аккаунте на `whatsapp.meta_business_agent.handover.updated`.
3. Проверяйте `YCloud-Signature` по исходному телу запроса, надежно принимайте каждое событие и обрабатывайте его идемпотентно.

<Warning>
  Агенты, созданные в консоли, не отправляют этот клиентский Webhook. Их синхронизация с Inbox выполняется отдельным потоком.
</Warning>

Инструкции по настройке конечной точки см. в разделе [Настройка вебхуков](/ru/api-reference/guides/api-fundamentals/configure-webhooks#subscribe-to-echo-and-handover-events).

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

Во всех примерах используются идентификаторы-заполнители. Маршрутизируйте по внешнему `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, игнорируются.

<Warning>
  Полезная нагрузка не генерирует фиктивную идентификацию клиента. `consumerPhoneNumber` опускается, если обратный вызов не предоставляет валидный номер телефона, и никакой BSUID не выводится из соседних сообщений. `phoneNumberId` идентифицирует номер компании, который может обслуживать множество клиентов.
</Warning>

Не рассматривайте это событие как подтверждение того, что сотрудник был назначен или что кастомное сообщение о передаче было отправлено либо доставлено.

## Запрос

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

## Ответ

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

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

### Запрос

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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
  }
}
```

### Ответ

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Объяснение

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

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

* [Создано эхо-сообщение WhatsApp](/ru/api-reference/guides/examples/webhook-examples/whatsapp-echo-message-created)
* [Эхо-сообщение WhatsApp обновлено](/ru/api-reference/guides/examples/webhook-examples/whatsapp-echo-message-updated)
* [Примеры эхо-сообщений и передачи управления Agent](/ru/api-reference/guides/examples/webhook-examples/overview#echo-and-agent-handover-events)
* [Полный каталог полезных нагрузок](/ru/api-reference/guides/examples/webhook-examples/webhook-payload-examples)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.