Scope-lar və endpoint-lər: kontaktlar, etiketlər, xüsusi sahələr, hazır cavablar

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

Addımlar

1. 1

   Bu məqaləni necə oxumaq

   • Yollar https://api.clomni.ai/v1-dən sonra yazılır: GET /v1/agents tam ünvanda https://api.clomni.ai/v1/agents deməkdir. Yolda workspace ID yoxdur, çünki token bir workspace-ə bağlıdır.
   • Hər sorğuda Authorization: Bearer clomni_pat_xxx başlığı olur. Tokeni necə almaq: Developer API-də tokenlər və autentifikasiya.
   • Risk: aşağı (şəxsi məlumat yoxdur), orta (müştəri məlumatını oxuyur və ya daxili məlumatı dəyişir), yüksək (müştəriyə göndərir, silir, toplu çıxarır, canlı ayarı dəyişir).
   • Hər scope review-dan keçir, public app-da da. Ətraflı: Review: scope-ların yoxlanması və rədd səbəbləri.
   • «Əlavə verir»: write və manage eyni resursun read-ini də verir. send, delete, publish, assign, run heç nə vermir.
   • Endpoint bir neçə scope ilə açılırsa, onlardan biri kifayətdir. Scope çatmasa, API 403 insufficient_scope və cavabda required_scopes qaytarır.
   • Hər POST Idempotency-Key başlığı qəbul edir: təkrar sorğu ikinci dəfə icra olunmur.
2. 2

   Kontaktları oxumaq (contacts:read)

   Kontaktları oxuyur: ad, telefon, e-poçt, identifier (sizin sistemdəki ID), xüsusi sahələr, etiketlər, qeydlər. Siyahı, axtarış, filtr, onlayn olanlar, mümkün dublikatlar, kontakta yazmaq olan inbox-lar və sinxron (/v1/sync/contacts) bu scope ilədir. contact.* webhook-ları da bunu istəyir.

   • Risk: orta.
   • Yoxlama: review-dan keçir. Bu icazə ilə hansı məlumatı, nə vaxt və nə üçün işlədəcəyinizi konkret yazın.
   • Əlavə verir: başqa scope vermir.

   Endpoint-lər:

   • GET /v1/companies: Şirkət siyahısı
   • GET /v1/companies/search: Şirkət axtarışı
   • GET /v1/companies/{company_id}: Şirkəti oxumaq
   • POST /v1/contact_inboxes/filter: Source ID ilə kontakt inbox-unu tapmaq
   • GET /v1/contacts: Kontakt siyahısı
   • GET /v1/contacts/active: Hazırda onlayn olan kontaktlar
   • POST /v1/contacts/filter: Kontaktları filtrləmək
   • GET /v1/contacts/search: Kontakt axtarışı
   • GET /v1/contacts/{contact_id}: Kontaktı oxumaq
   • GET /v1/contacts/{contact_id}/contactable_inboxes: Kontakta yazmaq olan inbox-lar
   • GET /v1/contacts/{contact_id}/labels: Kontaktın etiketləri
   • GET /v1/contacts/{contact_id}/merge_suggestions: Kontaktın mümkün dublikatları
   • GET /v1/contacts/{contact_id}/notes: Qeyd siyahısı
   • GET /v1/contacts/{contact_id}/notes/{note_id}: Qeydi oxumaq
   • GET /v1/search/contacts: Kontakt axtarışı (ümumi axtarış)
   • GET /v1/sync/contacts: Kontaktları sinxron etmək

   Nümunə:

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

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

3. 3

   Kontaktları dəyişmək (contacts:write)

   Kontakt yaradır və yeniləyir, iki kontaktı birləşdirir, etiket və qeyd yazır, kontaktı inbox-a bağlayır. PATCH-də custom_attributes köhnə dəyərlərlə birləşdirilir, göndərilməyən açarlar silinmir. Silmək üçün contacts:delete lazımdır.

   • Risk: orta.
   • Yoxlama: review-dan keçir. Bu icazə ilə hansı məlumatı, nə vaxt və nə üçün işlədəcəyinizi konkret yazın.
   • Əlavə verir: contacts:read də verir.

   Endpoint-lər:

   • POST /v1/actions/contact_merge: İki kontaktı birləşdirmək
   • POST /v1/companies: Şirkət yaratmaq
   • PATCH /v1/companies/{company_id}: Şirkəti yeniləmək
   • POST /v1/contacts: Kontakt yaratmaq
   • PATCH /v1/contacts/{contact_id}: Kontaktı yeniləmək
   • DELETE /v1/contacts/{contact_id}/avatar: Kontaktın şəklini silmək
   • POST /v1/contacts/{contact_id}/contact_inboxes: Kontaktı inbox-a bağlamaq
   • POST /v1/contacts/{contact_id}/destroy_custom_attributes: Kontaktdan xüsusi sahələri silmək
   • POST /v1/contacts/{contact_id}/labels: Kontaktın etiketlərini yazmaq
   • POST /v1/contacts/{contact_id}/notes: Qeyd yaratmaq
   • PATCH /v1/contacts/{contact_id}/notes/{note_id}: Qeydi yeniləmək
   • DELETE /v1/contacts/{contact_id}/notes/{note_id}: Qeydi silmək

   Nümunə:

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

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

4. 4

   Kontakt idxal etmək (contacts:import)

   CSV faylından kontaktları toplu idxal edir: fayl multipart/form-data ilə import_file sahəsində göndərilir, idxal fonda işləyir. Kontaktları bir-bir yaratmaq üçün contacts:write kifayətdir.

   • Risk: orta.
   • Yoxlama: review-dan keçir. Bu icazə ilə hansı məlumatı, nə vaxt və nə üçün işlədəcəyinizi konkret yazın.
   • Əlavə verir: başqa scope vermir.

   Endpoint-lər:

   • POST /v1/contacts/import: CSV faylından kontakt idxal etmək

   Nümunə:

   curl -X POST "https://api.clomni.ai/v1/contacts/import" \
     -H "Authorization: Bearer clomni_pat_xxx" \
     -F "[email protected]"

5. 5

   Kontakt silmək (contacts:delete)

   Kontaktı və onun söhbətlərini silir, geri qaytarmaq olmur. Şirkəti silmək də bu scope ilədir.

   • Risk: yüksək.
   • Yoxlama: review-dan keçir və daha diqqətlə yoxlanır. Ətraflı izah və funksiyanı göstərən qısa video lazımdır, hədəf müddət 2 iş günüdür.
   • Əlavə verir: başqa scope vermir.

   Endpoint-lər:

   • DELETE /v1/companies/{company_id}: Şirkəti silmək
   • DELETE /v1/contacts/{contact_id}: Kontaktı silmək

   Nümunə:

   curl -X DELETE "https://api.clomni.ai/v1/contacts/981" \
     -H "Authorization: Bearer clomni_pat_xxx"

6. 6

   Etiketləri görmək (labels:read)

   Etiketlərin siyahısını oxuyur. Söhbət və kontakt etiketlərini göstərmək, filtr qurmaq üçün.

   • Risk: aşağı.
   • Yoxlama: review-dan keçir, aşağı riskli scope-lara tez baxılır.
   • Əlavə verir: başqa scope vermir.

   Endpoint-lər:

   • GET /v1/labels: Etiket siyahısı
   • GET /v1/labels/{label_id}: Etiketi oxumaq

   Nümunə:

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

7. 7

   Etiketləri dəyişmək (labels:write)

   Etiket yaradır, dəyişir və silir. Söhbətə və ya kontakta etiket qoymaq bu scope ilə deyil: ona conversations:write və ya contacts:write lazımdır.

   • Risk: aşağı.
   • Yoxlama: review-dan keçir, aşağı riskli scope-lara tez baxılır.
   • Əlavə verir: labels:read də verir.

   Endpoint-lər:

   • POST /v1/labels: Etiket yaratmaq
   • PATCH /v1/labels/{label_id}: Etiketi yeniləmək
   • DELETE /v1/labels/{label_id}: Etiketi silmək

   Nümunə:

   curl -X POST "https://api.clomni.ai/v1/labels" \
     -H "Authorization: Bearer clomni_pat_xxx" \
     -H "Content-Type: application/json" \
     -d '{"title": "vip", "description": "Xüsusi müştərilər", "color": "#ff9f1c", "show_on_sidebar": true}'

8. 8

   Hazır cavabları görmək (canned_responses:read)

   Hazır cavabları oxuyur: qısa kod və mətn. Öz panelinizdə operatora hazır cavab seçimi vermək üçün.

   • Risk: aşağı.
   • Yoxlama: review-dan keçir, aşağı riskli scope-lara tez baxılır.
   • Əlavə verir: başqa scope vermir.

   Endpoint-lər:

   • GET /v1/canned_responses: Hazır cavab siyahısı

   Nümunə:

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

9. 9

   Hazır cavabları dəyişmək (canned_responses:write)

   Hazır cavab yaradır, dəyişir və silir. Məsələn, öz bilik sisteminizdəki mətnlərlə hazır cavabları avtomatik yeniləmək.

   • Risk: orta.
   • Yoxlama: review-dan keçir. Bu icazə ilə hansı məlumatı, nə vaxt və nə üçün işlədəcəyinizi konkret yazın.
   • Əlavə verir: canned_responses:read də verir.

   Endpoint-lər:

   • POST /v1/canned_responses: Hazır cavab yaratmaq
   • PATCH /v1/canned_responses/{canned_response_id}: Hazır cavabı yeniləmək
   • DELETE /v1/canned_responses/{canned_response_id}: Hazır cavabı silmək

   Nümunə:

   curl -X POST "https://api.clomni.ai/v1/canned_responses" \
     -H "Authorization: Bearer clomni_pat_xxx" \
     -H "Content-Type: application/json" \
     -d '{"short_code": "salam", "content": "Salam! Sizə necə kömək edə bilərik?"}'

10. 10

    Xüsusi sahələri görmək (custom_attributes:read)

    Xüsusi sahələrin tərifini oxuyur: açar, ad, növ, mümkün dəyərlər, kontakt və ya söhbət sahəsi olması. Dəyərlərin özü kontakt və söhbət obyektində gəlir.

    • Risk: aşağı.
    • Yoxlama: review-dan keçir, aşağı riskli scope-lara tez baxılır.
    • Əlavə verir: başqa scope vermir.

    Endpoint-lər:

    • GET /v1/custom_attribute_definitions: Xüsusi sahə siyahısı
    • GET /v1/custom_attribute_definitions/{custom_attribute_definition_id}: Xüsusi sahəni oxumaq

    Nümunə:

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

11. 11

    Xüsusi sahələri dəyişmək (custom_attributes:write)

    Xüsusi sahə yaradır, dəyişir və silir. Məsələn, CRM-dəki sahə üçün Clomni-də yeni açar açmaq.

    • Risk: orta.
    • Yoxlama: review-dan keçir. Bu icazə ilə hansı məlumatı, nə vaxt və nə üçün işlədəcəyinizi konkret yazın.
    • Əlavə verir: custom_attributes:read də verir.

    Endpoint-lər:

    • POST /v1/custom_attribute_definitions: Xüsusi sahə yaratmaq
    • PATCH /v1/custom_attribute_definitions/{custom_attribute_definition_id}: Xüsusi sahəni yeniləmək
    • DELETE /v1/custom_attribute_definitions/{custom_attribute_definition_id}: Xüsusi sahəni silmək

    Nümunə:

    curl -X POST "https://api.clomni.ai/v1/custom_attribute_definitions" \
      -H "Authorization: Bearer clomni_pat_xxx" \
      -H "Content-Type: application/json" \
      -d '{"attribute_display_name": "Müştəri səviyyəsi", "attribute_key": "customer_tier", "attribute_display_type": "list", "attribute_values": ["silver", "gold", "platinum"], "attribute_model": "contact_attribute"}'

12. 12

    Şirkətlər haqqında

    Şirkət endpoint-ləri (/v1/companies) contacts:* scope-ları ilə açılır və kataloqda qalır. «Şirkətlər» bölməsi isə 5 noyabr 2026-dan paneldə yoxdur, ona görə yeni inteqrasiyanı ona bağlamayın. Şirkət məlumatını kontaktın xüsusi sahəsində saxlamaq daha etibarlıdır.

13. 13

    Əlaqəli məqalələr

    • Hansı scope lazımdır: istəyinizə görə scope və endpoint seçimi
    • Resept: CRM ilə kontakt sinxronu
    • Developer API endpoint-lərini işlətmək: nümunələr, səhifələmə, idempotency