Перейти к основному содержимому

Обзор API

  • Адрес: https://<адрес установки>/api/integration/v1/.
  • Формат: JSON, время — строки RFC 3339 с зоной (format: date-time). Поля ответа, отмеченные в схеме required, приходят всегда.
  • Спецификация: OpenAPI integration.json — в справочнике (кнопка скачивания) и в каталоге sdk/openapi/ комплекта поставки. У каждой операции короткий operationId — так называется метод SDK (closeConversation, listQueues) — и группа в tags.

Операции​

ГруппаОперации
ОбращенияGET conversations (фильтры customer_namespace и customer_external_id, state, opened_after), POST conversations (начать), GET conversations/{id}, …/history (автор, файлы), …/transcript, …/route
ДиалогPOST conversations/{id}/messages — сообщение клиента (client_message_id, text и/или attachment_ids, нужно хотя бы одно); в закрытое обращение — начинает следующее (started_conversation_id). POST conversations/{id}/typing — «клиент печатает…» с необязательным draft, не чаще раза в 3 с. Обе операции — только в обращения, начатые через API: в обращения мессенджеров, виджета и своего канала — 409
УправлениеPOST …/close (resolution из results, final), …/reopen, …/transfer (queue — код очереди в системе организации или её id), PUT …/priority, …/subject, …/category, GET и POST …/tags, DELETE …/tags/{tag_id}, POST …/notes
КлиентыGET customers/by-identity/{namespace}/{external_id}, PUT …/attributes, PUT …/block
СправочникиGET queues, operators, categories, results, tags
Отчёты и формыGET monitor (очереди сейчас), GET conversations/{id}/ratings, GET conversations/{id}/forms
Отчёты файламиPOST reports/{kind}/exports (sla, queues, employees, customers, channels, categories, ratings, tags; период до 366 дней, csv или xlsx), GET report-exports/{id} (статус), GET report-exports/{id}/file. Файл хранится 30 дней
ВыгрузкиPOST exports/conversations (фильтры как в реестре обращений и q — номер или текст темы, клиента, сообщений и заметок; zip с историей), POST exports/customers (csv или xlsx, mask), GET exports/{conversations,customers}/{id} (статус, sha256), GET …/{id}/file. Файл хранится 7 дней
Журнал и конфигурацияPOST exports/audit (фильтры журнала: actor_id, action, object_type, object_id, failed, category, q, since, until; json или csv, до 100 000 записей), GET exports/audit/{id}, GET …/{id}/file. POST exports/config — пакет конфигурации, тот же, что переносит администратор между окружениями; собирается сразу (status = ready), GET exports/config/{id} (checksum), GET …/{id}/file (JSON). Файлы хранятся 7 дней
Файлы и ботыPOST conversations/{id}/uploads (name, size), затем PUT …/uploads/{upload_id}/content частями до 5 МиБ с Content-Range; attachment_id — в последнем ответе; GET и DELETE …/uploads/{upload_id}. GET attachments/{id}, ответы внешнего бота (bots/…)
Вебхукиподписки сервисного аккаунта и журнал доставок — вебхуки

Обращения и команды​

  • Команды состояния (закрыть, переоткрыть, передать, приоритет, тема) принимают expected_version из карточки обращения. Ответ — новая карточка с новой version. Устаревшая версия — 409 VERSION_CONFLICT: перечитайте обращение.
  • Результат закрытия (resolution) — код из справочника GET results: коды у каждой организации свои.
  • Списки листаются курсором — пагинация.

Клиенты​

Клиент называется парой namespace и external_id:

  • token:<издатель> (token:crm) — id из системы организации. То же пространство даёт chat token виджета с этим издателем, поэтому клиент, начатый через API и вошедший в виджет, — один человек;
  • email, guest, custom:<ref> (свой канал), telegram:, max:, vk: с id аккаунта канала.

Другое пространство — 422. Гостем (guest) обращение через API не начинают.

Файлы​

  • Файл клиента загружается только в обращение, начатое через API (иначе 409), и попадает в сообщение этого же клиента (файл другого обращения — 404).
  • Пока антивирус файл не проверил, оператор его не видит, а GET attachments/{id} отвечает 409 ATTACHMENT_NOT_READY.
  • Часть, отправленную повторно после обрыва, сервер второй раз не принимает: 409 UPLOAD_OFFSET_MISMATCH сообщает received_bytes, с него и продолжают. SDK делают это сами.
  • Прямых ссылок на хранилище нет: файлы скачиваются только через API.

Выгрузки​

  • Выгрузку и файл отчёта видит только запросивший аккаунт; другой аккаунт и сотрудники получают 404.
  • Файл собирается в фоне: опрашивайте статус до ready (или failed). Права проверяются и при скачивании: после смены роли или отключения аккаунта файл недоступен.
  • Пакет конфигурации не содержит значений секретов: на месте токена бота — заглушка ${secret:bots/<имя>/token}, секреты каналов, издателей и webhook-ов в пакет не входят. Запрос и каждое скачивание журнала и пакета пишутся в журнал аудита.

Чего в API нет​

Чтения журнала аудита и ввоза конфигурации (есть только их выгрузки файлами), остальных привилегированных прав сотрудников. Пакеты SDK в публичные реестры не публикуются: они в комплекте поставки (SDK).