Один диалог на внешнего пользователя
Диалог определяется двумя вещами: 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.