Chatonio

This is taking longer than usual.

Chatonio

Диалоги

7 июля 2026 г. 48 просмотровChatonio API

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

Возвращает диалоги проекта, сначала с самой недавней активностью, с курсорной пагинацией.

GET/api/v1/conversations/

Список диалогов (сначала недавно обновлённые).

Ответ

200Успех
{
  "results": [
    {
      "id": "3f2b1c9a-7d4e-4b21-9c33-0a1b2c3d4e5f",
      "status": "PROCESSING",
      "channel_type": "TELEGRAM",
      "ticket_number": 1042,
      "message_count": 7,
      "contact": { "id": "7c4e9b02-1a55-4e88-b0d1-2f3a4b5c6d7e", "display_name": "Jane Doe" },
      "updated_at": "2026-07-01T10:40:00+00:00"
    }
  ],
  "next_cursor": "MjAyNi0wNy0wMVQxMDo0MDowMHwzZjJi",
  "has_more": true
}

Параметры запроса

  • status — фильтр по статусу: NEW, ESCALATING, PROCESSING, WAITING, RESOLVED, CLOSED.
  • channel_id — UUID канала для фильтрации.
  • updated_since — метка времени ISO-8601; только диалоги, обновлённые в это время или позже.
  • cursor — непрозрачный курсор из поля next_cursor предыдущего ответа.
  • limit — размер страницы, по умолчанию 50, максимум 100.

Как работает курсорная пагинация — см. статью Ошибки, лимиты и пагинация.

Получить диалог

GET/api/v1/conversations/{id}/

Получить один диалог по id.

Ответы

200Успех
{
  "id": "3f2b1c9a-7d4e-4b21-9c33-0a1b2c3d4e5f",
  "status": "PROCESSING",
  "priority": "HIGH",
  "subject": "Refund request",
  "source": "CHANNEL",
  "channel_id": "9a1c5f30-2b6d-4c71-8e42-1a2b3c4d5e6f",
  "channel_type": "TELEGRAM",
  "ticket_number": 1042,
  "detected_language": "en",
  "message_count": 7,
  "contact": { "id": "7c4e9b02-1a55-4e88-b0d1-2f3a4b5c6d7e", "display_name": "Jane Doe" },
  "created_at": "2026-07-01T10:12:00+00:00",
  "updated_at": "2026-07-01T10:40:00+00:00",
  "last_message_at": "2026-07-01T10:40:00+00:00"
}
404Не найдено
{ "detail": "conversation_not_found" }

Объект диалога

  • id — UUID.
  • status — один из шести статусов выше.
  • priority — LOW / MEDIUM / HIGH / URGENT или null.
  • subject, source (CHANNEL/PORTAL/OPERATOR), ticket_number, detected_language, message_count.
  • channel_id, channel_type (TELEGRAM, TELEGRAM_GROUP, WEB, EMAIL, HELPDESK, …).
  • contact — { id, display_name }.
  • created_at, updated_at, last_message_at — ISO-8601.

Диалоги TELEGRAM_GROUP (один бот, обслуживающий групповой чат Telegram) в API v1 доступны только для чтения: отправка сообщения возвращает 400 group_conversations_not_supported, а смена статуса — 400 status_change_not_supported_for_group.

Статусы диалога

  • NEW — обрабатывается ИИ, оператора пока нет.
  • ESCALATING — передан человеку; операторы уведомлены.
  • PROCESSING — оператор подключился.
  • WAITING — оператор ждёт ответа клиента.
  • RESOLVED — решён; ответ клиента может открыть заново.
  • CLOSED — закрыт.

Что ещё возвращается в деталях диалога

GET /api/v1/conversations/{id}/ возвращает больше, чем список. Каждое из этих полей стоит отдельного запроса к базе, поэтому они есть только в ответе по одному диалогу:

  • assigned_operator и assigned_operators — кто ведёт диалог, с отображаемым именем и аватаром.
  • tags — теги диалога.
  • rating — оценка удовлетворённости, если клиент её оставил: { score, comment, rated_at }, иначе null.
  • ai_autoresponse_mode и ai_active — переключатель ИИ и то, отвечает ли ИИ прямо сейчас.
  • webchat — только для веб-чата: страница, на которой находится посетитель, его недавние переходы и кто он.

Данные посетителя и право pii

Блок webchat.visitor отдаёт страну, браузер и операционную систему с обычным правом read. IP-адрес и user agent посетителя включаются, только если у ключа есть ещё и pii, — так ключ для отчётности не будет получать персональные данные, которые ему не нужны.

Начать диалог

POST /api/v1/conversations/ открывает исходящий диалог с контактом — например, чтобы сообщить об отправке заказа. У контакта уже должен быть идентификатор в этом канале (см. статью о контактах); без него доставлять некуда.

{
  "contact_id": "a7c3…",
  "channel_id": "id-вашего-email-канала",
  "subject": "Ваш заказ отправлен",
  "content": "Трек-номер: 1Z999…"
}

Диалог создаётся без назначенного оператора и в статусе NEW — то есть ИИ-ассистент на нём уже работает: если клиент ответит, он получит ответ, а не попадёт в пустую очередь. Если вы хотите, чтобы ИИ молчал, установите ai_autoresponse_mode в OFF или назначьте оператора.

Каналы email и хелпдеск допускают несколько открытых диалогов с одним человеком; во всех остальных второй диалог вернёт 409 conversation_already_open с идентификатором уже открытого.

Назначение оператора

POST /api/v1/conversations/{id}/assign/ с телом {"operator_id": "…"} передаёт диалог сотруднику и переводит его в PROCESSING — так же, как если бы оператор взял диалог в дашборде. POST .../unassign/ возвращает диалог в очередь. Для обоих нужно право admin; идентификаторы операторов — GET /api/v1/operators/.

Именно поэтому PATCH не позволяет выставить PROCESSING напрямую: этот статус означает, что диалогом занимается человек, поэтому он следует из назначения, а не устанавливается сам по себе.

Теги

POST /api/v1/conversations/{id}/tags/ с телом {"tag_id": "…"} добавляет тег, а DELETE /api/v1/conversations/{id}/tags/{tag_id}/ — удаляет; PATCH с полем tag_ids заменяет весь набор. GET /api/v1/tags/ покажет доступные.

Где взять нужные идентификаторы

Есть три эндпоинта только для чтения, чтобы ничего не приходилось зашивать в код: GET /api/v1/tags/, GET /api/v1/channels/ и GET /api/v1/operators/.

Эта статья была полезной?