Dialogi
Начать бесплатно

Справочник · Чат

Диалоги и сообщения

Диалоги с клиентами из чата на сайте, мессенджеров и почты - те же, что в инбоксе личного кабинета. Через API можно читать диалоги и сообщения, отвечать клиенту и закрывать диалог. Диалог принадлежит проекту: ключ видит диалоги только своих проектов.

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

Диалог с клиентом в одном канале: чат на сайте, мессенджер или почта.

objectстрокаобязателен

Тип объекта, всегда conversation.

Значения: conversation

iduuidобязателен

id диалога.

project_iduuidобязателен

id проекта диалога.

channelстрокаобязателен

Канал: web - чат на сайте, telegram, vk, max, email, image - комментарии в соцсетях: читать и закрывать можно, отвечать через API нельзя. Список значений может пополняться.

statusстрокаобязателен

open - открыт, snoozed - отложен, closed - закрыт, spam - помечен как спам.

Значения: opensnoozedclosedspam

closed_reasonстрокаобязателенможет быть null

Почему закрыт: resolved - закрыт как решённый, abandoned - клиент пропал, duplicate - дубль, spam - спам, wrong_channel - не по адресу. У незакрытого или без причины - null. resolved не значит, что клиент подтвердил решение: так закрывается и диалог, который ИИ-ассистент закрыл прощанием, когда клиент не ответил на его вопрос, и диалог в чате на сайте, когда посетитель сам начал новый, а при закрытии сотрудником или через API это причина по умолчанию.

Значения: resolvedabandonedduplicatespamwrong_channel

closed_atдата и время с зонойобязателенможет быть null

Когда диалог закрыли, UTC. У незакрытого - null.

customer_nameстрокаобязателенможет быть null

Как клиент подписан в канале: имя в мессенджере, email или телефон.

message_countцелое числообязателен

Сколько сообщений в диалоге.

first_message_atдата и время с зонойобязателенможет быть null

Время первого сообщения, UTC.

last_message_atдата и время с зонойобязателенможет быть null

Время последнего сообщения, UTC.

created_atдата и время с зонойобязателенможет быть null

Когда диалог создан, UTC.

updated_atдата и время с зонойобязателенможет быть null

Когда диалог последний раз менялся, UTC.

Объект диалога 
{
  "object": "conversation",
  "id": "01a0d7f0-e4f2-7b3c-9d5e-6f7a8b9c0d1e",
  "project_id": "01a0c4e2-3f10-7b4d-9c2e-5d8a1f6b3e20",
  "channel": "telegram",
  "status": "open",
  "closed_reason": null,
  "closed_at": null,
  "customer_name": "Анна",
  "message_count": 4,
  "first_message_at": "2026-09-25T09:30:02Z",
  "last_message_at": "2026-09-25T09:41:12Z",
  "created_at": "2026-09-25T09:30:02Z",
  "updated_at": "2026-09-25T09:41:12Z"
}
GET/v1/conversations

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

Право: conversations:read

Диалоги проектов ключа, от новых к старым, по страницам. Фильтры можно сочетать.

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

limitцелое числоможет быть null

Сколько объектов на странице, от 1 до 100.

По умолчанию: 20

starting_afteruuidможет быть null

id последнего объекта предыдущей страницы: страница начнётся после него. См. Пагинация.

project_iduuidможет быть null

Только объекты этого проекта. Проекта нет в ключе - ошибка 403.

statusстрокаможет быть null

Только диалоги в этих статусах, через запятую. Значения - как у поля status диалога.

channelстрокаможет быть null

Только диалоги этих каналов, через запятую. Значения - как у поля channel диалога.

created[gte]дата и время с зонойможет быть null

Диалоги, созданные не раньше этого времени. Время с часовым поясом (RFC 3339).

created[lte]дата и время с зонойможет быть null

Диалоги, созданные не позже этого времени. Время с часовым поясом (RFC 3339).

Ответы

  • 200Страница списка диалогов.
  • 401Нет ключа, ключ неверный, истёк или отозван (unauthenticated).
  • 402У компании не подключено дополнение «Публичный API» (api-addon-required).
  • 403У ключа нет нужного права или доступа к проекту (forbidden).
  • 422Данные запроса не прошли проверку (validation). Какие поля и почему - в errors.
  • 429Превышен лимит запросов (rate-limited). Повторите через столько секунд, сколько указано в Retry-After.
  • 503Сервис временно недоступен (unavailable). Повторите позже.
Запрос 
curl https://api.ru.dialogi.io/v1/conversations \
  -H "Authorization: Bearer dk_live_…"
Ответ 200
{
  "object": "list",
  "data": [
    {
      "object": "conversation",
      "id": "01a0d7f0-e4f2-7b3c-9d5e-6f7a8b9c0d1e",
      "project_id": "01a0c4e2-3f10-7b4d-9c2e-5d8a1f6b3e20",
      "channel": "telegram",
      "status": "open",
      "closed_reason": null,
      "closed_at": null,
      "customer_name": "Анна",
      "message_count": 4,
      "first_message_at": "2026-09-25T09:30:02Z",
      "last_message_at": "2026-09-25T09:41:12Z",
      "created_at": "2026-09-25T09:30:02Z",
      "updated_at": "2026-09-25T09:41:12Z"
    }
  ],
  "has_more": true
}
GET/v1/conversations/{conversation}

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

Право: conversations:read

Диалог по id. Диалог из проекта, которого нет в ключе, для ключа не существует - ответ 404.

Параметры пути

conversationuuidобязателен

id диалога.

Ответы

  • 200Диалог.
  • 401Нет ключа, ключ неверный, истёк или отозван (unauthenticated).
  • 402У компании не подключено дополнение «Публичный API» (api-addon-required).
  • 403У ключа нет нужного права или доступа к проекту (forbidden).
  • 404Объекта с таким id нет или он в проекте, которого нет в ключе (not-found).
  • 429Превышен лимит запросов (rate-limited). Повторите через столько секунд, сколько указано в Retry-After.
  • 503Сервис временно недоступен (unavailable). Повторите позже.
Запрос 
curl https://api.ru.dialogi.io/v1/conversations/0192d3a1-7b2c-7c3e-9a51-2f6b8e4d1c90 \
  -H "Authorization: Bearer dk_live_…"
Ответ 200
{
  "object": "conversation",
  "id": "01a0d7f0-e4f2-7b3c-9d5e-6f7a8b9c0d1e",
  "project_id": "01a0c4e2-3f10-7b4d-9c2e-5d8a1f6b3e20",
  "channel": "telegram",
  "status": "open",
  "closed_reason": null,
  "closed_at": null,
  "customer_name": "Анна",
  "message_count": 4,
  "first_message_at": "2026-09-25T09:30:02Z",
  "last_message_at": "2026-09-25T09:41:12Z",
  "created_at": "2026-09-25T09:30:02Z",
  "updated_at": "2026-09-25T09:41:12Z"
}
POST/v1/conversations/{conversation}/close

Закрыть диалог

Право: conversations:write Idempotency-Key поддерживается

Закрывает диалог так же, как кнопка «Закрыть» у сотрудника в инбоксе личного кабинета. Повторное закрытие уже закрытого диалога - не ошибка: ответ 200 с тем же диалогом, причина не меняется.

Параметры пути

conversationuuidобязателен

id диалога.

Параметры тела

reasonстрокаможет быть null

Причина закрытия - как у поля closed_reason диалога.

Значения: resolvedabandonedduplicatespamwrong_channel

По умолчанию: "resolved"

Ответы

  • 200Закрытый диалог.
  • 400Idempotency-Key в неверном формате (idempotency-key-invalid).
  • 401Нет ключа, ключ неверный, истёк или отозван (unauthenticated).
  • 402У компании не подключено дополнение «Публичный API» (api-addon-required).
  • 403У ключа нет нужного права или доступа к проекту (forbidden).
  • 404Объекта с таким id нет или он в проекте, которого нет в ключе (not-found).
  • 409Idempotency-Key уже использован с другим запросом (idempotency-conflict) или первый запрос с ним ещё выполняется (idempotency-in-progress).
  • 422Данные запроса не прошли проверку (validation). Какие поля и почему - в errors.
  • 429Превышен лимит запросов (rate-limited). Повторите через столько секунд, сколько указано в Retry-After.
  • 503Сервис временно недоступен (unavailable). Повторите позже.
Запрос 
curl https://api.ru.dialogi.io/v1/conversations/0192d3a1-7b2c-7c3e-9a51-2f6b8e4d1c90/close \
  -H "Authorization: Bearer dk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-20195208" \
  -d '{
    "reason": "resolved"
  }'
Ответ 200
{
  "object": "conversation",
  "id": "01a0d7f0-e4f2-7b3c-9d5e-6f7a8b9c0d1e",
  "project_id": "01a0c4e2-3f10-7b4d-9c2e-5d8a1f6b3e20",
  "channel": "telegram",
  "status": "open",
  "closed_reason": null,
  "closed_at": null,
  "customer_name": "Анна",
  "message_count": 4,
  "first_message_at": "2026-09-25T09:30:02Z",
  "last_message_at": "2026-09-25T09:41:12Z",
  "created_at": "2026-09-25T09:30:02Z",
  "updated_at": "2026-09-25T09:41:12Z"
}
GET/v1/conversations/{conversation}/messages

Список сообщений

Право: conversations:read

Сообщения диалога от новых к старым, по страницам. Только переписка с клиентом, без внутренних заметок команды.

Параметры пути

conversationuuidобязателен

id диалога.

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

limitцелое числоможет быть null

Сколько объектов на странице, от 1 до 100.

По умолчанию: 20

starting_afteruuidможет быть null

id последнего объекта предыдущей страницы: страница начнётся после него. См. Пагинация.

project_iduuidможет быть null

Не влияет на список: сообщения берутся из диалога, id которого в пути.

Ответы

  • 200Страница сообщений диалога.
  • 401Нет ключа, ключ неверный, истёк или отозван (unauthenticated).
  • 402У компании не подключено дополнение «Публичный API» (api-addon-required).
  • 403У ключа нет нужного права или доступа к проекту (forbidden).
  • 404Объекта с таким id нет или он в проекте, которого нет в ключе (not-found).
  • 422Данные запроса не прошли проверку (validation). Какие поля и почему - в errors.
  • 429Превышен лимит запросов (rate-limited). Повторите через столько секунд, сколько указано в Retry-After.
  • 503Сервис временно недоступен (unavailable). Повторите позже.
Запрос 
curl https://api.ru.dialogi.io/v1/conversations/0192d3a1-7b2c-7c3e-9a51-2f6b8e4d1c90/messages \
  -H "Authorization: Bearer dk_live_…"
Ответ 200
{
  "object": "list",
  "data": [
    {
      "object": "message",
      "id": "01a0d7f0-f5a3-7c4d-8e6f-7a8b9c0d1e2f",
      "conversation_id": "01a0d7f0-e4f2-7b3c-9d5e-6f7a8b9c0d1e",
      "direction": "outbound",
      "author_type": "operator",
      "source": "api",
      "text": "Здравствуйте! Заказ 20195208 передан в доставку.",
      "attachments": [],
      "status": "delivered",
      "failure": null,
      "created_at": "2026-09-25T09:41:12Z"
    }
  ],
  "has_more": true
}
POST/v1/conversations/{conversation}/messages

Отправить сообщение

Право: conversations:write Idempotency-Key обязателен

Отправляет клиенту текст в канал диалога. Сообщение уходит как ответ сотрудника: в чате на сайте клиент увидит название ключа API как имя оператора, а ИИ-ассистент после такого ответа на время перестаёт отвечать в диалоге - так же, как после ответа сотрудника.

Только текст: вложения через API не отправляются, запрос с непустым полем attachments - ошибка 422. Длина - по каналу: Telegram и VK - до 4096 символов, MAX - до 4000, чат на сайте и почта - до 8000. Закрытый диалог API заново не открывает, а в канал image писать нельзя - в обоих случаях ошибка 409.

Если канал не принял сообщение, ответ всё равно 201: сообщение сохранено со статусом failed, причина - в failure.code. Повтор с тем же Idempotency-Key вернёт это же сообщение со статусом failed - чтобы отправить его ещё раз, передайте новый ключ.

Idempotency-Key обязателен: повтор запроса без него отправил бы клиенту сообщение второй раз. Повтор в тот же диалог с тем же ключом и тем же телом вернёт то же сообщение и не отправит его снова - и спустя сутки тоже. Ключ закреплён за диалогом: тот же ключ в запросе к другому диалогу в первые 24 часа - ошибка 409, а позже отправит новое сообщение. Для каждого сообщения берите свой ключ.

Параметры пути

conversationuuidобязателен

id диалога.

Параметры тела

textстрокаобязателен

Текст сообщения. Длина - по каналу диалога: Telegram и VK - до 4096 символов, MAX - до 4000, чат на сайте и почта - до 8000.

Ответы

  • 201Сообщение сохранено и отправлено в канал - или не доставлено, тогда status = failed.
  • 400Нет заголовка Idempotency-Key (idempotency-key-required) или ключ в неверном формате (idempotency-key-invalid).
  • 401Нет ключа, ключ неверный, истёк или отозван (unauthenticated).
  • 402У компании не подключено дополнение «Публичный API» (api-addon-required).
  • 403У ключа нет нужного права или доступа к проекту (forbidden).
  • 404Объекта с таким id нет или он в проекте, которого нет в ключе (not-found).
  • 409Idempotency-Key уже использован с другим запросом (idempotency-conflict) или первый запрос с ним ещё выполняется (idempotency-in-progress). Диалог закрыт (conversation-closed), диалог в чате на сайте завершён (conversation-archived), в этот канал API не пишет (channel-not-supported) или канал отключён в личном кабинете (channel-disconnected).
  • 422Данные запроса не прошли проверку (validation). Какие поля и почему - в errors.
  • 429Превышен лимит запросов (rate-limited). Повторите через столько секунд, сколько указано в Retry-After.
  • 503Сервис временно недоступен (unavailable). Повторите позже.
Запрос 
curl https://api.ru.dialogi.io/v1/conversations/0192d3a1-7b2c-7c3e-9a51-2f6b8e4d1c90/messages \
  -H "Authorization: Bearer dk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-20195208" \
  -d '{
    "text": "Здравствуйте! Заказ 20195208 передан в доставку."
  }'
Ответ 201
{
  "object": "message",
  "id": "01a0d7f0-f5a3-7c4d-8e6f-7a8b9c0d1e2f",
  "conversation_id": "01a0d7f0-e4f2-7b3c-9d5e-6f7a8b9c0d1e",
  "direction": "outbound",
  "author_type": "operator",
  "source": "api",
  "text": "Здравствуйте! Заказ 20195208 передан в доставку.",
  "attachments": [],
  "status": "delivered",
  "failure": null,
  "created_at": "2026-09-25T09:41:12Z"
}