Вивантажити переписку за період через API

Цю інструкцію читають інтегратори, яким треба забирати переписку з ConnectiveOne у свою систему: сховище даних, BI чи аналітику якості. Вона показує, як наявними запитами API отримати всі чати за період і текст кожного повідомлення з датою та автором.

Коли знадобиться

Потрібно регулярно забирати переписку за день, тиждень чи місяць у зовнішню систему.
Аналітикам треба розмітити повідомлення на «клієнт» і «оператор».
Потрібна разова вибірка діалогів за період для перевірки якості.

Що важливо знати

Після авторизації вивантаження складається з двох запитів: спершу список чатів за період, потім файл з повідомленнями для кожного чату.
Повідомлення одного чату віддаються файлом: CSV (за замовчуванням) або XLSX. Формат JSON для цього запиту не підтримується.
Запити виконуються від імені користувача, чий логін і пароль ви використали. Цей користувач має мати доступ до модуля Операторська панель. Радимо завести окремого технічного користувача для інтеграції.
Період у кроці 2 фільтрує чати за датою створення чату. Повідомлення всередині чату можуть бути й пізнішими.
Дуже широкий період у кроці 2 може завершитись помилкою 504 QUERY_TIMEOUT. Тоді звузьте період і забирайте дані частинами.

Перед початком

У вас є email і пароль користувача з доступом до операторської панелі.
Ви знаєте адресу вашого інстансу, наприклад https://engine-<instance>.connectiveone.io.
Ви вмієте надсилати HTTP-запити (curl, Postman або код інтеграції).

Покрокова інструкція

Крок 1. Отримайте токен доступу

curl -X POST "https://engine-<instance>.connectiveone.io/api/v1/auth/token" -H "Content-Type: application/json" -d '{"email":"[email protected]","password":"<password>","expires_in":3600}'

У відповіді буде токен. Додавайте його до кожного наступного запиту в заголовку Authorization: Bearer <token>.

expires_in — час життя токена в секундах. Максимум задає конфігурація інстансу; якщо значення завелике, запит поверне помилку 400 з допустимим діапазоном.
Токен не оновлюється. Коли строк вийде, отримайте новий тим самим запитом.

Детальніше про авторизацію — у статті Як використовувати API.

Крок 2. Отримайте список чатів за період

curl -G "https://engine-<instance>.connectiveone.io/kw/api/v1/OpChatRooms/list" -H "Authorization: Bearer <token>" --data-urlencode "filter[createdAt][gt]=2026-11-01T00:00:00.000Z" --data-urlencode "filter[createdAt][lt]=2026-11-08T00:00:00.000Z" --data-urlencode "order[createdAt]=asc" --data-urlencode "limit=100" --data-urlencode "offset=0"

Параметр	Що задає
`filter[createdAt][gt]`	Початок періоду (ISO 8601)
`filter[createdAt][lt]`	Кінець періоду (ISO 8601)
`limit`	Скільки чатів повернути за один запит (за замовчуванням 10)
`offset`	Скільки чатів пропустити — для переходу на наступну сторінку
`order[createdAt]`	Сортування: `asc` або `desc`

Відповідь містить масив rows і загальну кількість count. Із кожного рядка вам потрібне поле id — це id чату. Збільшуйте offset на limit, доки не пройдете всі count чатів.

Крок 3. Вивантажте повідомлення кожного чату

Для кожного id з кроку 2:

curl -G "https://engine-<instance>.connectiveone.io/kw/operator_panel/chat_room/messages/download" -H "Authorization: Bearer <token>" --data-urlencode "chat_room_id=12345" --data-urlencode "format=csv" -o chat-12345.csv

format — csv (за замовчуванням) або xlsx.
У файлі один рядок на повідомлення. Щоб упорядкувати повідомлення за часом, сортуйте за send_datetime.

Що буде у файлі

У файлі кожного чату такі колонки:

Колонка	Що в ній
`id`	Id повідомлення
`send_datetime`	Дата й час повідомлення у форматі `РРРР-ММ-ДД ГГ:ХХ:СС`
`message_text`	Текст повідомлення
`message_data`	Службові дані повідомлення: вкладення, кнопки тощо
`system`	`1` — системне повідомлення платформи (наприклад, про підключення оператора)
`message_read`	Чи прочитано повідомлення
`participant.client.full_name`, `participant.client.email`, `participant.client.phone`	Заповнені, якщо повідомлення написав клієнт
`participant.user.first_name`, `participant.user.last_name`	Заповнені, якщо повідомлення написав оператор

Id чату у файлі немає: беріть його з імені файлу або з кроку 2 і додавайте до рядків у своїй системі.

Щоб розмітити автора повідомлення:

заповнені колонки participant.client.* — повідомлення клієнта;
заповнені колонки participant.user.* — повідомлення оператора;
system = 1 — системне повідомлення.

Як переконатися, що все вдалось

Кількість оброблених чатів дорівнює count з кроку 2.
Для одного-двох чатів порівняйте файл із перепискою в операторській панелі: тексти повідомлень збігаються.
Звірте send_datetime одного повідомлення з часом в операторській панелі, щоб знати, у якому часовому поясі приходять дати.

Часті питання

Запит повертає 422 з повідомленням token data error. Що не так? Користувач, від імені якого отримано токен, не має доступу до операторської панелі. Видайте йому роль з цим доступом.

Можна отримати повідомлення одразу за весь період одним запитом? Ні: повідомлення вивантажуються окремо для кожного чату, як у кроці 3.

Чи можна вивантажити переписку без API? Так, для окремого діалогу: у меню чату в операторській панелі є пункт «Скачати» (CSV) і експорт у PDF.