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

Просмотр шагов диалога

Используйте шаги диалога (turns) для анализа задержек, ошибок и последовательности вызовов LLM и инструментов для отдельного пользователя WhatsApp. Справочник по API: GET Get Conversation Turns
user_phone_number должен содержать только код страны и цифры. Не указывайте начальный знак +, пробелы или разделители. Границы временных меток задаются в миллисекундах Unix epoch включительно. Не объединяйте 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 ID. Поле metadata необязательно и поддерживает до 2000 символов. Справочник по API: POST Control Thread
Освобождение контроля прекращает отправку ответов агентом в этой ветке. Контекст диалога может быть утерян при последующем возврате контроля агенту. Текущий интерфейс REST не предоставляет эндпоинт, сообщающий о текущем владельце ветки, поэтому ваша интеграция должна отслеживать запрошенные переходы и их результаты.

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

Отправляйте событие только в том случае, если агент контролирует ветку клиента. Справочник по API: POST Submit Agent Event · GET Get Agent Event Status
При наличии ответ о статусе включает в себя conversation_id — тот же непрозрачный идентификатор, который возвращается методом Conversation Turns. Используйте его для сопоставления записей, а не как идентификатор события или подтверждение доставки сообщения. Поле может отсутствовать. Сохраните agent_event_id из ответа и опрашивайте GET Get Agent Event Status для получения состояния обработки, временных меток, error_message или skipped_reason. Успешная отправка подтверждает лишь то, что событие принято для асинхронной обработки; она не гарантирует отправку ответа клиенту. Пропуск события может означать, что агент больше не контролирует данную ветку.

Просмотр логов выполнения коннектора

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

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

YCloud сохраняет соответствующий HTTP-статус вышестоящего сервиса и возвращает безопасную структуру ошибки вместо передачи необработанных ответов или учетных данных из вышестоящего сервиса. Когда вышестоящий сервис не возвращает применимую ошибку, YCloud может вернуть MBA_UPSTREAM_UNAVAILABLE. Повторяйте операции чтения с ограниченной экспоненциальной задержкой (exponential backoff) для 429, 500 и 502. Перед повторной отправкой запроса на создание, обновление, удаление, отправку события, тест, запуск инструмента, учетные данные или multipart-запроса определите, вступила ли в силу исходная запись. При эскалации повторяющегося сбоя фиксируйте оба идентификатора запроса и очищенную структуру запроса.

Учитывайте ограничения раннего доступа

Следующие особенности являются ограничениями, а не гарантиями контракта YCloud REST:
  • Некоторые сбои проверки критериев отображаются как 500, а не как стабильный ответ о несоответствии.
  • Тестирование агента может зависеть от настроек раскатки и аудитории.
  • Контекст диалога может быть утерян после передачи оператору-человеку и возврата.
  • Таблицы PDF или CSV могут интерпретироваться ненадежно.
  • Агент может ненадежно отправлять файлы или изображения клиентам.
  • Коннекторы MCP недоступны; используйте коннекторы и инструменты HTTP.
  • Биллинг и коммерческие условия могут измениться на этапе раннего доступа к продукту.

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

Отправляйте DELETE Delete Agent только тогда, когда агента необходимо удалить с этого телефонного номера WhatsApp Business. Успешный запрос возвращает HTTP 200 и может содержать deleted_agent_id, если вышестоящий сервис передает его в ответе. Удаление агента отличается от отключения раскатки. Используйте rollout.enabled=false, если вам нужна обратимая пауза.