Resept: CRM ilə kontakt sinxronu

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

Addımlar

1. 1

   Nə alırsınız

   • CRM-də hər müştərinin Clomni kontaktı: ad, telefon, e-poçt, xüsusi sahələr.
   • Clomni-də yaranan və dəyişən kontakt bir neçə saniyəyə CRM-ə düşür.
   • CRM-də dəyişən məlumat (məsələn müştəri səviyyəsi) Clomni-yə yazılır və operator söhbətdə görür.
   • İstəsəniz, CRM-də müştərinin söhbət tarixçəsi.
2. 2

   Lazım olan scope-lar

   • contacts:read (orta risk): kontaktları oxumaq və contact.* webhook-ları.
   • contacts:write (orta risk): CRM-dən Clomni-yə yazmaq. Yalnız Clomni-dən CRM-ə köçürürsünüzsə, bunu istəməyin.
   • custom_attributes:read (aşağı risk): xüsusi sahələrin siyahısı.
   • conversations:read və messages:read (orta risk): yalnız CRM-də söhbət tarixçəsini göstərəcəksinizsə.

   App yaradanda «CRM sinxronu» hazır dəstini seçə bilərsiniz, sonra lazım olmayanı silin. contacts:write contacts:read-i də verir, amma webhook mövzusu seçmək üçün contacts:read ayrıca təsdiqlənməlidir. App və token: developer.clomni.ai-da app yaratmaq: addım-addım, Developer API-də tokenlər və autentifikasiya.

3. 3

   1. Bütün kontaktları bir dəfə yükləyin

   GET /v1/sync/contacts kontaktları (updated_at, id) sırası ilə, ən köhnə dəyişiklikdən başlayaraq qaytarır. limit 1-100 arasındadır. Növbəti səhifə üçün cavabdakı next_cursor-u after ilə göndərin. has_more: false olanda hamısını almısınız.

   curl "https://api.clomni.ai/v1/sync/contacts?limit=100" \
     -H "Authorization: Bearer clomni_pat_xxx"

   {
     "data": [
       {
         "id": 981,
         "name": "Leyla Həsənova",
         "email": "[email protected]",
         "phone_number": "+994501234567",
         "identifier": "crm-10422",
         "custom_attributes": { "customer_tier": "gold" },
         "created_at": "2026-07-25T11:02:00.000Z",
         "updated_at": "2026-11-08T09:14:03.120Z"
       }
     ],
     "next_cursor": "MjAyNi0xMS0wOFQwOToxNDowM1p8OTgx",
     "has_more": true
   }

   next_cursor-u açmağa və ya özünüz qurmağa çalışmayın, olduğu kimi geri göndərin.

4. 4

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

   İlk yükləmədən sonra ən böyük updated_at dəyərini saxlayın. Növbəti dəfə updated_since ilə ondan sonra dəyişənləri alın:

   curl "https://api.clomni.ai/v1/sync/contacts?updated_since=2026-11-08T09:12:00Z&limit=100" \
     -H "Authorization: Bearer clomni_pat_xxx"

   • Saxladığınız vaxtdan 1-2 dəqiqə geri gedin ki, eyni anda yazılan qeydlər itməsin.
   • Kontaktı id ilə yazın (upsert): eyni kontakt iki dəfə gəlsə, yenisi köhnəsinin üstünə yazılır.
   • has_more: true olanda after ilə davam edin, updated_since-i dəyişməyin.
   • Yeni vaxtı yalnız bütün səhifələr uğurla yazılandan sonra saxlayın.

   Sinxron endpoint-ləri token üzrə dəqiqədə 60 sorğu ilə məhdudlaşır. Bunu bir neçə dəqiqədən bir işlətmək kifayətdir.

5. 5

   3. Dəyişiklikləri dərhal alın

   Developer portalında app-ın «Webhook-lar» bölməsində HTTPS ünvanınızı yazın və contact.created, contact.updated mövzularını seçin. Hadisədə kontaktın tam obyekti gəlir. Webhook dublikat gələ bilər və sıra zəmanətli deyil: updated_at-ı yoxlayın, CRM-dəki qeyd daha yenidirsə köhnə hadisəni atın. Webhook işləməyən vaxt üçün 2-ci addımı da saxlayın, məsələn saatda bir dəfə. Quraşdırma və imza yoxlaması: App webhook-ları və hadisələr: qurmaq, mövzular, imzanın yoxlanması.

6. 6

   4. CRM-dən Clomni-yə yazın

   Kontaktın identifier sahəsinə CRM-dəki ID-ni yazın: bu sahə workspace daxilində unikaldır. Əvvəl kontaktın Clomni-də olub-olmadığını axtarın (ad, e-poçt, telefon və identifier üzrə axtarır):

   curl "https://api.clomni.ai/v1/contacts/search?q=crm-10422" \
     -H "Authorization: Bearer clomni_pat_xxx"

   Yoxdursa, yaradın:

   curl -X POST "https://api.clomni.ai/v1/contacts" \
     -H "Authorization: Bearer clomni_pat_xxx" \
     -H "Content-Type: application/json" \
     -d '{"name": "Leyla Həsənova", "email": "[email protected]", "phone_number": "+994501234567", "identifier": "crm-10422", "custom_attributes": {"customer_tier": "gold"}}'

   Varsa, yeniləyin. PATCH yalnız göndərdiyiniz sahələri dəyişir, custom_attributes köhnə dəyərlərlə birləşdirilir:

   curl -X PATCH "https://api.clomni.ai/v1/contacts/981" \
     -H "Authorization: Bearer clomni_pat_xxx" \
     -H "Content-Type: application/json" \
     -d '{"custom_attributes": {"customer_tier": "platinum"}}'

   Telefon nömrəsi beynəlxalq formada olmalıdır: + və ölkə kodu ilə, boşluqsuz. Eyni e-poçt və ya telefonla ikinci kontakt yaratmaq 422 qaytarır.

7. 7

   5. Xüsusi sahələri uyğunlaşdırın

   custom_attributes açarları workspace-də əvvəlcədən təyin olunmalıdır. Siyahı:

   curl "https://api.clomni.ai/v1/custom_attribute_definitions?attribute_model=contact_attribute" \
     -H "Authorization: Bearer clomni_pat_xxx"

   CRM sahələrini bu açarlara bir dəfə uyğunlaşdırın. Təyin olunmamış açar paneldə görünmür. Yeni açarı paneldə yaradın və ya API ilə (custom_attributes:write).

8. 8

   6. Sonsuz dövrəyə düşməyin

   İki tərəfli sinxronda öz yazdığınız dəyişiklik webhook kimi geri qayıdır. Onu yenidən CRM-ə yazsanız, dövrə yaranır. Clomni-yə yazanda cavabdakı updated_at-ı saxlayın və eyni updated_at ilə gələn hadisəni atın. Və ya sinxronlaşdırdığınız sahələrin hash-ini saxlayın: dəyişməyibsə heç nə etməyin.

9. 9

   Tez-tez səhvlər

   • updated_since üst-üstə düşmədən saxlanır və eyni saniyədə dəyişən kontaktlar itir. 1-2 dəqiqə geri gedin.
   • Səhifələr arasında updated_since dəyişdirilir. Səhifələri yalnız after ilə gəzin.
   • Kontaktın olub-olmadığı yoxlanmadan yaradılır və 422 gəlir. Əvvəl axtarın, sonra yeniləyin.
   • Telefon 0501234567 kimi, ölkə kodu olmadan yazılır.
   • custom_attributes-ə workspace-də olmayan açar yazılır və paneldə görünmür.
   • contacts:write təsdiqlənib, contacts:read yoxdur və contact.* webhook-u seçilmir.
   • 429 alanda dərhal təkrar edilir. Retry-After başlığındakı saniyə qədər gözləyin.
   • Vaxtlar qarışdırılır: sinxron endpoint-ləri ISO 8601 (UTC), köhnə siyahılar Unix saniyəsi qaytarır.

   Bütün kontakt endpoint-ləri: Scope-lar və endpoint-lər: kontaktlar, etiketlər, xüsusi sahələr, hazır cavablar.