Рецепт: экспорт истории и постоянная синхронизация

Обновлено: 11 ноября 2026 · 10 мин чтения

Шаги

1. 1

   Что Вы получите

   • Диалоги, сообщения и контакты в одном gzip-файле, по одному объекту в строке.
   • Дальше только изменившиеся объекты, с задержкой в несколько минут, а через вебхук сразу.
   • Возможность вернуть события, пропущенные пока сервер не работал, за последние 30 дней.
2. 2

   Нужные scope

   • exports:run (высокий риск): массовый экспорт. В review укажите цель, систему, куда пойдёт файл, как часто Вы будете выгружать данные, сколько храните файл и как удаляете.
   • Для постоянной синхронизации: conversations:read, messages:read, contacts:read (средний риск). Берите только нужные ресурсы.
   • Для пропущенных событий: events:read (средний риск) вместе со scope на чтение темы.

   Готовый набор «Экспорт данных» отмечает exports:run и events:read.

3. 3

   1. Запустите экспорт

   resources принимает одно или несколько значений из conversations, messages, contacts, без него выгружаются все три. since и until это время в ISO 8601, фильтр идёт по updated_at.

   curl -X POST "https://api.clomni.ai/v1/exports" \
     -H "Authorization: Bearer clomni_pat_xxx" \
     -H "Content-Type: application/json" \
     -d '{"resources": ["conversations", "messages", "contacts"], "since": "2026-01-01T00:00:00Z", "until": "2026-11-01T00:00:00Z"}'

   Ответ 202 Accepted с id задачи и status: "queued".

4. 4

   2. Дождитесь готовности

   Проверяйте каждые 15-30 секунд:

   curl "https://api.clomni.ai/v1/exports/15" \
     -H "Authorization: Bearer clomni_pat_xxx"

   status: queued, running, done, failed. При done в ответе есть download_url и download_expires_at. Ссылка работает 1 час: если срок прошёл, прочитайте экспорт ещё раз, придёт новая ссылка. При failed причина в поле error.

5. 5

   3. Прочитайте файл

   Файл это JSON Lines, сжатый gzip: каждая строка {"type": ..., "data": {...}}. type бывает conversation, message или contact, data совпадает с объектом endpoint синхронизации. Читайте файл построчно, не загружайте его целиком в память:

   curl -s "$DOWNLOAD_URL" | gunzip | head -n 3

   attachments[].url в сообщении это короткоживущая ссылка. Если файлы нужны, скачайте их сразу после готовности экспорта. Если ссылка устарела, прочитайте сообщение заново через GET /v1/conversations/{conversation_id}/messages и получите свежую.

6. 6

   4. Затем забирайте только изменения

   Не повторяйте экспорт каждый день. После загрузки файла используйте endpoint синхронизации:

   curl "https://api.clomni.ai/v1/sync/messages?updated_since=2026-11-01T00:00:00Z&limit=100" \
     -H "Authorization: Bearer clomni_pat_xxx"

   • GET /v1/sync/conversations, GET /v1/sync/messages и GET /v1/sync/contacts возвращают объекты в порядке (updated_at, id).
   • Для следующей страницы передайте next_cursor в after, при has_more: false всё получено.
   • Сохраняйте самое большое updated_at, в следующий раз начинайте на 2 минуты раньше и записывайте объекты по id.
   • Запускать раз в 5-15 минут достаточно. Лимит 60 запросов в минуту на токен, используйте limit=100.

   Чтобы получать новые сообщения сразу, добавьте вебхук message.created, а синхронизация пусть закрывает пробелы. См. Вебхуки приложения и события: настройка, темы, проверка подписи.

7. 7

   5. Верните пропущенные события

   Если сервер не работал, заберите события за последние 30 дней из ленты, с теми же id, что и у вебхуков:

   curl "https://api.clomni.ai/v1/events?types=message.created&limit=100" \
     -H "Authorization: Bearer clomni_pat_xxx"

   Нужен и scope на чтение каждой темы: один events:read возвращает пустой список. События пишутся, только пока в workspace есть активный токен разработчика или установка, поэтому событий до создания токена в ленте нет.

8. 8

   Для панели отчётов

   Если Power BI или другому BI-инструменту нужны только сводные цифры, вместо экспорта используйте reports:read (низкий риск): количество диалогов, время первого ответа и решения, итоги по операторам, inbox и командам. Время передаётся в секундах Unix:

   curl "https://api.clomni.ai/v1/reports?metric=conversations_count&type=account&since=1793491200&until=1794096000&group_by=day&timezone_offset=4" \
     -H "Authorization: Bearer clomni_pat_xxx"

   Все endpoint отчётов: Scope и endpoint: отчёты, CSAT, SLA.

9. 9

   Лимиты и защита данных

   • В workspace одновременно идёт 1 экспорт: второй запрос получит 409 conflict.
   • 6 экспортов за 24 часа: сверх лимита приходит 429 rate_limited. Не повторяйте автоматически.
   • Неизвестный ресурс или неверный формат времени возвращает 400 invalid_request.
   • В файле персональные данные и сообщения клиентов. Храните его в зашифрованном виде, ограничьте доступ и удаляйте после срока, указанного в review. При удалении приложения данные, полученные из Clomni, должны быть удалены в течение 30 дней.
10. 10

    Частые ошибки

    • Экспорт повторяется каждый день, и дневной лимит заканчивается. Выгрузите один раз, затем используйте синхронизацию.
    • Файл целиком загружается в память. Читайте построчно.
    • download_url используется после истечения срока. GET /v1/exports/{export_id} выдаст новую ссылку.
    • В объекте синхронизации id диалога принимают за номер из панели. Внутренний ID лежит в id, номер из панели в number (в сообщении conversation_number).
    • В параметр conversation_id у /v1/sync/messages передают номер из панели. Туда нужен внутренний id объекта диалога из синхронизации.
    • Путают ISO 8601 и секунды Unix: синхронизация и экспорт используют ISO 8601, старые списки и отчёты используют секунды Unix.
    • Обычные списки (GET /v1/conversations) листают постранично, чтобы скопировать всё. Между страницами порядок сдвигается, объекты теряются или приходят дважды. Используйте endpoint синхронизации.

    Все endpoint экспорта и событий: Scope и endpoint: звонки, вебхуки, события, экспорт.