Skip to main content

Один диалог на внешнего пользователя

Диалог определяется двумя вещами: API-ключом и external_user_id, который вы отправляете. Вы никогда не создаёте диалог явно: первый запрос в чат с новым external_user_id создаёт его, а каждое последующее сообщение от того же внешнего пользователя через тот же ключ продолжает его. Следствия, о которых стоит знать:
  • Изоляция по ключу. Один и тот же external_user_id, пришедший через два разных ключа, — это два разных диалога, даже если оба ключа принадлежат одному агенту. Ключ никогда не видит диалоги другого ключа или другого канала (Telegram, виджета и так далее).
  • Обновление сохраняет историю. Обновление ключа меняет его секрет, а не идентификатор, поэтому его диалоги остаются привязанными.
  • external_user_id — ваш. Используйте стабильный идентификатор из своей системы, 1-255 символов. Не помещайте в него персональные данные, которые не хотели бы хранить рядом с диалогом.
  • Один ответ за раз. Если сообщение для внешнего пользователя приходит, пока предыдущий ответ ещё генерируется, API отвечает 409 conversation_busy с Retry-After: 2. Подождите и отправьте снова.

Список диалогов

GET /v1/agents/{agent_id}/conversations возвращает диалоги ключа, сначала самые недавно обновлённые. Его могут вызывать ключи и с read-only, и с full.
last_message_preview — последний текст пользователя или ассистента, обрезанный до 160 символов, либо null для пустого диалога.

Чтение сообщений

GET /v1/agents/{agent_id}/conversations/{conversation_id}/messages возвращает сообщения одного диалога, сначала новые. Возвращаются только сообщения user и assistant; обмены с инструментами, записи об активности инструментов и системный промпт никогда не раскрываются. У каждого сообщения есть id, role (user или assistant), type (text, image, file, …), content (текст; нетекстовое содержимое отображается как его текст или имя) и created_at. Идентификатор диалога, который принадлежит другому ключу или каналу либо не существует, — это 404 conversation_not_found. API не различает эти два случая.

Пагинация

Каждый список — это {"data": [...], "next_cursor": "..." | null}. Передайте next_cursor обратно как cursor, чтобы получить следующую страницу, и остановитесь, когда он станет null. Курсоры непрозрачны; некорректный курсор — это 422 validation_error.

Даты

Даты — в ISO-8601. Значения с часовым поясом переводятся в UTC, значения без пояса читаются как UTC, а date_to не включается. date_to раньше date_from — это 422 validation_error.