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

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

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

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

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

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

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

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

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

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

```bash
curl -X POST "https://engine-<instance>.connectiveone.io/api/v1/auth/token" -H "Content-Type: application/json" -d '{"email":"integration@example.com","password":"<password>","expires_in":3600}'
```

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

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

Детальніше про авторизацію — у статті [Як використовувати API](/uk/integrations/how-to/use-api.md).

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

```bash
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:

```bash
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](/uk/operatorline/how-to/export-chatroom-to-pdf.md).

## Пов'язані матеріали

- [Як використовувати API](/uk/integrations/how-to/use-api.md)
- [Довідник API](/uk/integrations/reference/api-reference.md)
- [Експортувати чат у PDF](/uk/operatorline/how-to/export-chatroom-to-pdf.md)