> ## 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.

# Эксплуатация и устранение неполадок

> Управляйте цепочками сообщений, обрабатывайте события, проверяйте журналы, обрабатывайте сбои и безопасно выводите из эксплуатации Meta Business Agent.

Настройте поведение передачи и последующих действий в [Onboard and configure](/ru/documentation/meta-business-agent/onboard-and-configure) и проверьте его в [Test and evaluate](/ru/documentation/meta-business-agent/test-and-evaluate). Во время работы агент, рабочий процесс поддержки с участием человека и внутренняя автоматизация не должны предполагать, что они управляют одной и той же цепочкой одновременно.

## Проверка реплик в разговоре

Используйте реплики в разговоре для исследования задержек, ошибок и последовательности вызовов LLM и инструментов для одного пользователя WhatsApp.

**Справочник по API:** [GET Get Conversation Turns](/api-reference/meta-business-agents/get-conversation-turns)

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --get \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/conversationTurns" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --data-urlencode "user_phone_number=14155550123" \
  --data-urlencode "start_timestamp_ms=1788134400000" \
  --data-urlencode "end_timestamp_ms=1788220800000" \
  --data-urlencode "limit=50"
```

`user_phone_number` должен содержать только код страны и цифры. Не включайте начальный `+`, пробелы или разделители. Границы временных меток — это включительные миллисекунды эпохи Unix. Не комбинируйте `before` и `after`.

Каждая реплика требует `conversation_id`, `turn_id` и `steps`. `message_id` является необязательным, и ответ не содержит `session_id`. Каждый шаг имеет тип `LLM_CALL` или `TOOL_CALL` и может иметь статус `SUCCESS`, `ERROR` или `TIMEOUT`.

Продолжайте нумерацию страниц, пока присутствует `paging.next`, даже если текущий массив `data` пуст или содержит меньше элементов, чем `limit`.

## Управление цепочкой клиента

Используйте `pass`, `release` или `take` с общей конечной точкой управления цепочкой. Укажите `to` в виде номера телефона E.164 или идентификатора WhatsApp. `metadata` является необязательным и поддерживает до 2000 символов.

**Справочник по API:** [POST Control Thread](/api-reference/meta-business-agents/control-thread)

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/threadControl" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "action": "release",
    "to": "+14155550123",
    "metadata": "Escalated to order support"
  }'
```

Освобождение управления останавливает агента от ответа в этой цепочке. Контекст разговора может быть потерян, когда управление позже возвращается к агенту. Текущая поверхность REST не предоставляет конечную точку, которая сообщает о текущем владельце цепочки, поэтому ваша интеграция должна отслеживать запрошенные переходы и их результаты.

## Отправка и отслеживание бизнес-событий

Отправляйте событие только тогда, когда агент управляет цепочкой клиента.

**Справочник по API:** [POST Submit Agent Event](/api-reference/meta-business-agents/submit-agent-event) · [GET Get Agent Event Status](/api-reference/meta-business-agents/get-agent-event-status)

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/events" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "to": "+14155550123",
    "event": {
      "type": "order_status_changed",
      "description": "The customer order moved to shipped.",
      "payload": "{\"order_id\":\"ORD-1001\",\"status\":\"shipped\"}"
    }
  }'
```

| Поле | Ограничение | Значение |
| - | - | - |
| `to` | E.164 | Номер телефона WhatsApp потребителя. |
| `event.type` | 256 символов | Стабильный тип события. |
| `event.description` | 1024 символа | Значение события на простом языке. |
| `event.payload` | 4096 символов | Непрозрачный JSON, сериализованный как строка. |

Сохраните `agent_event_id` из ответа и опрашивайте [GET Get Agent Event Status](/api-reference/meta-business-agents/get-agent-event-status) для получения состояния обработки, временных меток, `error_message` или `skipped_reason`. Успешная отправка подтверждает только то, что событие было принято для асинхронной обработки; это не гарантирует ответ, обращенный к клиенту. Пропущенное событие может означать, что агент больше не управляет цепочкой.

## Проверка журналов выполнения коннектора

Запросите [GET List Connector Logs](/api-reference/meta-business-agents/list-connector-logs), когда вызов инструмента завершается сбоем или становится медленным. Ответ объединяет записи журнала с количеством, процентом успешных выполнений и статистикой задержек.

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

## Безопасная обработка неудачных запросов

YCloud сохраняет соответствующий статус HTTP вышестоящей системы и возвращает безопасный конверт ошибки вместо раскрытия необработанных ответов вышестоящей системы или учетных данных.

| Поле | Значение |
| - | - |
| `status` | Код состояния HTTP. |
| `code` | Код ошибки YCloud. |
| `message` | Сводка для разработчика. |
| `target` | Связанная цель запроса, если доступна. |
| `docUrl` | Связанный URL-адрес документации YCloud, если доступен. |
| `requestId` | Идентификатор YCloud, используемый для поддержки и корреляции журналов. |
| `metaBusinessAgentApiError.title` | Заголовок ошибки вышестоящей системы, если он безопасен и доступен. |
| `metaBusinessAgentApiError.detail` | Практические сведения о вышестоящей системе. |
| `metaBusinessAgentApiError.type` | Категория ошибки или URI вышестоящей системы. |
| `metaBusinessAgentApiError.status` | Статус вышестоящей системы. |
| `metaBusinessAgentApiError.requestId` | Идентификатор запроса вышестоящей системы. |

Если вышестоящая служба не возвращает пригодную для использования ошибку, YCloud может вернуть `MBA_UPSTREAM_UNAVAILABLE`.

| Симптом | Что проверить |
| - | - |
| `401` | Проверьте ключ API YCloud и доступ арендатора. Не отправляйте маркер доступа Meta. |
| `403` | Проверьте доступ к продукту и принятие условий для компании-владельца. |
| `404` | Проверьте идентификатор номера телефона и активную привязку агента Public API арендатора. |
| Тест не возвращает ответ | Проверьте развертывание, аудиторию, список разрешений, соответствие требованиям и `no_response_reason`. |
| Веб-сайт остается в ожидании | Сканирование выполняется асинхронно; извлеките ресурс веб-сайта снова позже. |
| Сбой вызова коннектора | Проверьте журналы, учетные данные, состояние сертификата и привязки параметров. |

Повторяйте операции чтения с ограниченной экспоненциальной задержкой для `429`, `500` и `502`. Перед повторной попыткой запроса на создание, обновление, удаление, событие, тест, запуск инструмента, учетные данные или составного запроса определите, вступила ли в силу исходная запись. Запишите как идентификаторы запросов, так и очищенную форму запроса при эскалации повторяющегося сбоя.

## Планирование ограничений раннего доступа

Следующие особенности поведения являются ограничениями, а не гарантиями REST-контракта YCloud:

* Некоторые ошибки проверки соответствия требованиям отображаются как `500` вместо стабильного ответа о несоответствии.
* Тестирование агента может зависеть от настроек развертывания и аудитории.
* Контекст разговора может быть потерян после передачи оператору и возврата.
* Таблицы PDF или CSV могут интерпретироваться ненадежно.
* Агент может ненадежно отправлять файлы или изображения клиентам.
* Коннекторы MCP недоступны; используйте HTTP-коннекторы и инструменты.
* Биллинг и коммерческие условия могут измениться, пока продукт находится в раннем доступе.

## Удаление агента при выводе номера телефона из эксплуатации

Отправляйте [DELETE Delete Agent](/api-reference/meta-business-agents/delete-agent) только тогда, когда агента необходимо удалить с этого номера телефона WhatsApp Business. Успешный запрос возвращает HTTP `200` и может включать `deleted_agent_id`, если это предусмотрено ответом вышестоящей системы.

Удаление агента отличается от отключения развертывания. Используйте `rollout.enabled=false`, если вам нужна обратимая пауза.


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