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

Настройте поведение передачи и последующих действий в Onboard and configure и проверьте его в Test and evaluate. Во время работы агент, рабочий процесс поддержки с участием человека и внутренняя автоматизация не должны предполагать, что они управляют одной и той же цепочкой одновременно.

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

Используйте реплики в разговоре для исследования задержек, ошибок и последовательности вызовов LLM и инструментов для одного пользователя WhatsApp. Справочник по API: GET Get Conversation Turns

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

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 · GET Get Agent Event Status

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 для получения состояния обработки, временных меток, error_message или skipped_reason. Успешная отправка подтверждает только то, что событие было принято для асинхронной обработки; это не гарантирует ответ, обращенный к клиенту. Пропущенное событие может означать, что агент больше не управляет цепочкой.

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

Запросите GET 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 только тогда, когда агента необходимо удалить с этого номера телефона WhatsApp Business. Успешный запрос возвращает HTTP 200 и может включать deleted_agent_id, если это предусмотрено ответом вышестоящей системы. Удаление агента отличается от отключения развертывания. Используйте rollout.enabled=false, если вам нужна обратимая пауза.

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

Руководства

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

Webhooks

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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