Resept: tarixçəni ixrac etmək və davamlı sinxron

Son yeniləmə: 11 noyabr 2026 · 10 dəq oxunur

Addımlar

1. 1

   Nə alırsınız

   • Söhbət, mesaj və kontaktlar bir gzip faylında, hər sətir bir obyekt.
   • Sonra yalnız dəyişən obyektlər, bir neçə dəqiqə gecikmə ilə, istəsəniz webhook ilə dərhal.
   • Server dayananda qaçan hadisələri son 30 gündən geri almaq imkanı.
2. 2

   Lazım olan scope-lar

   • exports:run (yüksək risk): toplu ixrac. Review-da məqsədi, faylın gedəcəyi sistemi, nə qədər tez-tez ixrac edəcəyinizi və faylı nə qədər saxlayıb necə siləcəyinizi yazın.
   • Davamlı sinxron üçün: conversations:read, messages:read, contacts:read (orta risk). Yalnız lazım olan resursu götürün.
   • Qaçan hadisələr üçün: events:read (orta risk), mövzunun oxuma scope-u ilə birlikdə.

   «Məlumat ixracı» hazır dəsti exports:run və events:read-i seçir.

3. 3

   1. İxracı başladın

   resources conversations, messages, contacts dəyərlərindən birini və ya bir neçəsini alır, yazılmasa üçü də ixrac olunur. since və until ISO 8601 vaxtdır və updated_at üzrə süzür.

   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"}'

   Cavab 202 Accepted və işin id-sidir, status: "queued".

4. 4

   2. Hazır olmasını gözləyin

   Hər 15-30 saniyədən bir yoxlayın:

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

   status: queued, running, done, failed. done olanda cavabda download_url və download_expires_at olur. Link 1 saat işləyir: vaxt keçibsə ixracı yenidən oxuyun, yeni link gələcək. failed olanda səbəb error sahəsindədir.

5. 5

   3. Faylı oxuyun

   Fayl gzip ilə sıxılmış JSON Lines-dır: hər sətir {"type": ..., "data": {...}}. type conversation, message və ya contact olur, data sinxron endpoint-lərinin obyekti ilə eynidir. Faylı sətir-sətir oxuyun, bütöv yaddaşa yükləməyin:

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

   Mesajdakı attachments[].url qısa ömürlü linkdir. Fayllar lazımdırsa, ixrac hazır olan kimi endirin. Link köhnəlibsə, mesajı GET /v1/conversations/{conversation_id}/messages ilə yenidən oxuyub təzə link alın.

6. 6

   4. Sonra yalnız dəyişənləri götürün

   İxracı hər gün təkrarlamayın. Faylı yüklədikdən sonra sinxron endpoint-lərini işlədin:

   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 obyektləri (updated_at, id) sırası ilə qaytarır.
   • Növbəti səhifə üçün next_cursor-u after ilə göndərin, has_more: false olanda bitdi.
   • Ən böyük updated_at-ı saxlayın, növbəti dəfə ondan 2 dəqiqə əvvəlki vaxtla başlayın, obyektləri id ilə yazın.
   • 5-15 dəqiqədən bir işlətmək kifayətdir. Limit token üzrə dəqiqədə 60 sorğudur, limit=100 işlədin.

   Yeni mesajı dərhal almaq üçün message.created webhook-u əlavə edin, sinxron isə boşluğu doldursun. Bax: App webhook-ları və hadisələr: qurmaq, mövzular, imzanın yoxlanması.

7. 7

   5. Qaçan hadisələri geri alın

   Serveriniz dayanıbsa, son 30 günün hadisələrini lentdən webhook-dakı eyni id-lərlə götürün:

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

   Hər mövzunun oxuma scope-u da lazımdır: təkcə events:read boş siyahı qaytarır. Hadisələr yalnız workspace-də aktiv developer tokeni və ya quraşdırması olanda yazılır, token yaradılmamışdan əvvəlki hadisələr lentdə yoxdur.

8. 8

   Hesabat paneli üçün

   Power BI və ya başqa BI aləti üçün yalnız toplu rəqəmlər lazımdırsa, ixrac əvəzinə reports:read (aşağı risk) işlədin: söhbət sayı, ilk cavab və həll müddəti, operator, inbox, komanda üzrə yekunlar. Vaxtlar Unix saniyəsi ilə verilir:

   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"

   Bütün hesabat endpoint-ləri: Scope-lar və endpoint-lər: hesabatlar, CSAT, SLA.

9. 9

   Limitlər və məlumatın qorunması

   • Workspace üzrə eyni anda 1 ixrac işləyir: ikinci sorğu 409 conflict alır.
   • 24 saatda 6 ixrac: limit keçəndə 429 rate_limited. Avtomatik təkrar etməyin.
   • Tanınmayan resurs və ya səhv vaxt formatı 400 invalid_request qaytarır.
   • Faylda müştərilərin şəxsi məlumatı və mesajları var. Şifrəli saxlayın, çıxışı məhdudlaşdırın, review-da yazdığınız müddətdən sonra silin. App silinəndə Clomni-dən alınmış məlumat 30 gün ərzində silinməlidir.
10. 10

    Tez-tez səhvlər

    • İxrac hər gün təkrarlanır və gündəlik limit bitir. Bir dəfə ixrac edin, sonra sinxron işlədin.
    • Fayl bütöv yaddaşa yüklənir. Sətir-sətir oxuyun.
    • download_url vaxtı keçəndən sonra işlədilir. GET /v1/exports/{export_id} yeni link verir.
    • Sinxron obyektində söhbətin id-si panel nömrəsi sanılır. Daxili ID id-də, panel nömrəsi number-də (mesajda conversation_number) olur.
    • /v1/sync/messages-in conversation_id parametrinə panel nömrəsi yazılır. Ora sinxron söhbət obyektinin daxili id-si yazılır.
    • ISO 8601 və Unix saniyəsi qarışdırılır: sinxron və ixrac ISO 8601, köhnə siyahılar və hesabatlar Unix saniyəsi işlədir.
    • Adi siyahılar (GET /v1/conversations) səhifə-səhifə gəzilərək tam köçürülür. Səhifələr arasında sıra sürüşür, obyektlər itir və ya iki dəfə gəlir. Sinxron endpoint-lərini işlədin.

    Bütün ixrac və hadisə endpoint-ləri: Scope-lar və endpoint-lər: zənglər, webhook-lar, hadisələr, ixrac.