Clomni

Scope-lar və endpoint-lər: söhbətlər və mesajlar

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

Söhbətləri oxumaq, dəyişmək, təyin etmək və mesaj göndərmək üçün scope-lar. Söhbətin API-dəki nömrəsi ({conversation_id}) paneldə görünən nömrə ilə eynidir. Sinxron obyektində isə id daxili ID-dir, panel nömrəsi number sahəsindədir.

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

    Söhbətləri oxumaq (conversations:read)

    Söhbətləri oxuyur: status, təyinat, komanda, etiketlər, xüsusi sahələr, son mesaj. Siyahı, axtarış, filtr, saylar və sinxron (/v1/sync/conversations) bu scope ilə işləyir. conversation.* webhook-ları da bunu istəyir. Mesajların tam mətni üçün ayrıca messages:read 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: başqa scope vermir.

    Endpoint-lər:

    • GET /v1/contacts/{contact_id}/conversations: Kontaktın söhbətləri
    • GET /v1/conversations: Söhbət siyahısı
    • POST /v1/conversations/filter: Söhbətləri filtrləmək
    • GET /v1/conversations/meta: Təyinata görə söhbət sayları
    • GET /v1/conversations/search: Söhbət axtarışı
    • GET /v1/conversations/{conversation_id}: Söhbəti oxumaq
    • GET /v1/conversations/{conversation_id}/labels: Söhbətin etiketləri
    • GET /v1/conversations/{conversation_id}/participants: Söhbətin iştirakçıları
    • GET /v1/search/conversations: Söhbət axtarışı (ümumi axtarış)
    • GET /v1/sync/conversations: Söhbətləri sinxron etmək

    Nümunə:

    curl "https://api.clomni.ai/v1/conversations?status=open&assignee_type=unassigned&page=1" \
  -H "Authorization: Bearer clomni_pat_xxx"
    curl "https://api.clomni.ai/v1/sync/conversations?updated_since=2026-11-10T00:00:00Z&limit=100" \
  -H "Authorization: Bearer clomni_pat_xxx"
  3. 3

    Söhbətləri dəyişmək (conversations:write)

    Söhbətin statusunu (açıq, bağlı, gözləyir, təxirə salınıb), prioritetini, etiketlərini və xüsusi sahələrini dəyişir, yeni söhbət başladır, söhbəti oxunmuş və ya oxunmamış edir. İlk mesajla söhbət başlatmaq üçün messages:send də lazımdır. Bu scope test kanalında review-dan əvvəl də işlə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: conversations:read də verir.

    Endpoint-lər:

    • POST /v1/conversations: Söhbət başlatmaq
    • PATCH /v1/conversations/{conversation_id}: Söhbəti yeniləmək
    • POST /v1/conversations/{conversation_id}/custom_attributes: Söhbətin xüsusi sahələrini yazmaq
    • POST /v1/conversations/{conversation_id}/labels: Söhbətin etiketlərini yazmaq
    • POST /v1/conversations/{conversation_id}/mute: Söhbəti səssizə almaq
    • POST /v1/conversations/{conversation_id}/toggle_priority: Söhbətin prioritetini dəyişmək
    • POST /v1/conversations/{conversation_id}/toggle_status: Söhbətin statusunu dəyişmək
    • POST /v1/conversations/{conversation_id}/toggle_typing_status: "Yazır..." göstəricisi
    • POST /v1/conversations/{conversation_id}/unmute: Söhbətin səsini açmaq
    • POST /v1/conversations/{conversation_id}/unread: Söhbəti oxunmamış etmək
    • POST /v1/conversations/{conversation_id}/update_last_seen: Söhbəti oxunmuş etmək
    • POST /v1/test_channel/messages: Müştəri mesajı simulyasiyası (test kanalı). messages:send və ya conversations:write kifayətdir, test kanalında review-dan əvvəl də işləyir

    Nümunə:

    curl -X POST "https://api.clomni.ai/v1/conversations/1042/toggle_status" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"status": "resolved"}'
    curl -X POST "https://api.clomni.ai/v1/conversations/1042/labels" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"labels": ["sifariş", "vip"]}'
  4. 4

    Söhbət təyin etmək (conversations:assign)

    Söhbəti operatora və ya komandaya təyin edir, söhbətə iştirakçı əlavə edir, söhbəti tokenin sahibinə götürür. Oxumağı vermir: söhbət siyahısı üçün conversations:read 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: başqa scope vermir.

    Endpoint-lər:

    • POST /v1/conversations/{conversation_id}/assignments: Söhbəti təyin etmək
    • POST /v1/conversations/{conversation_id}/participants: Söhbətə iştirakçı əlavə etmək
    • PATCH /v1/conversations/{conversation_id}/participants: Söhbət iştirakçılarını əvəz etmək
    • DELETE /v1/conversations/{conversation_id}/participants: Söhbətdən iştirakçı çıxarmaq
    • POST /v1/conversations/{conversation_id}/take: Söhbəti token sahibinə götürmək

    Nümunə:

    curl -X POST "https://api.clomni.ai/v1/conversations/1042/assignments" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"assignee_id": 12}'
    curl -X POST "https://api.clomni.ai/v1/conversations/1042/assignments" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"team_id": 3}'
  5. 5

    Söhbət silmək (conversations:delete)

    Söhbəti silir. Geri qaytarmaq olmur, ona görə yüksək riskdir. Söhbəti arxivə salmaq üçün silmək əvəzinə bağlayın (conversations:write).

    • 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/conversations/{conversation_id}: Söhbəti silmək

    Nümunə:

    curl -X DELETE "https://api.clomni.ai/v1/conversations/1042" \
  -H "Authorization: Bearer clomni_pat_xxx"
  6. 6

    Mesajları oxumaq (messages:read)

    Mesajların mətnini və fayllarını oxuyur: söhbətin mesajları, fayllar, mesaj axtarışı, mesaj sinxronu, WhatsApp mesajının statusu və 24 saat pəncərəsi. message.created və message.updated webhook-ları da bu scope-u 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/conversations/{conversation_id}/attachments: Söhbətin faylları
    • GET /v1/conversations/{conversation_id}/messages: Söhbətin mesajları
    • GET /v1/search/messages: Mesaj axtarışı
    • GET /v1/sync/messages: Mesajları sinxron etmək
    • GET /v1/whatsapp/messages/window: Nömrə üçün 24 saat pəncərəsini yoxlamaq
    • GET /v1/whatsapp/messages/{message_id}: WhatsApp mesajının statusu

    Nümunə:

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

    Mesaj göndərmək (messages:send)

    Müştəriyə istənilən kanalda mesaj göndərir: söhbətə cavab, mesajı düzəltmək, reaksiya, alınmayan mesajı təkrar göndərmək, nömrəyə WhatsApp mətni. Göndərmək oxumağı vermir: söhbəti görmək üçün messages:read da lazımdır. Söhbət mesajında private: true daxili qeyddir və notes:write istəyir, template_params olan mesaj messages:send.template istəyir. Bu scope test kanalında review-dan əvvəl də işləyir.

    • 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ə olaraq yazın: mesajı kim yaradır (insan, AI, avtomatlaşdırma), gündə təxminən neçə mesaj gedir, marketinq mesajı üçün razılıq necə alınır.
    • Əlavə verir: başqa scope vermir.

    Endpoint-lər:

    • POST /v1/conversations/{conversation_id}/messages: Mesaj göndərmək və ya daxili qeyd yazmaq. private: true olanda notes:write, template_params olanda messages:send.template lazımdır
    • PATCH /v1/conversations/{conversation_id}/messages/{message_id}: Mesajın çatdırılma statusunu bildirmək (API kanalı)
    • PATCH /v1/conversations/{conversation_id}/messages/{message_id}/edit_content: Göndərilmiş mesajı düzəltmək
    • POST /v1/conversations/{conversation_id}/messages/{message_id}/reaction: Mesaja reaksiya vermək
    • POST /v1/conversations/{conversation_id}/messages/{message_id}/retry: Alınmayan mesajı yenidən göndərmək
    • POST /v1/test_channel/messages: Müştəri mesajı simulyasiyası (test kanalı). messages:send və ya conversations:write kifayətdir, test kanalında review-dan əvvəl də işləyir
    • POST /v1/whatsapp/messages: Nömrəyə WhatsApp mesajı göndərmək. template olanda messages:send.template, fallback_template olanda messages:send və messages:send.template lazımdır

    Nümunə:

    curl -X POST "https://api.clomni.ai/v1/conversations/1042/messages" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Idempotency-Key: 6f1c2a9e-3b7d-4f0a-9c55-0e8b1d2a7f41" \
  -H "Content-Type: application/json" \
  -d '{"content": "Salam, sifarişiniz bu gün kuryerə veriləcək.", "content_attributes": {"client_echo_id": "crm-7f3a9c"}}'
  8. 8

    Şablon mesajı göndərmək (messages:send.template)

    WhatsApp şablon mesajı göndərir: 24 saat pəncərəsindən kənar da işləyir, Meta hər şablon üçün pul alır. POST /v1/whatsapp/messages-də template olanda, söhbət mesajında template_params olanda tələb olunur. fallback_template olanda messages:send ilə birlikdə lazımdır. Təsdiqlənmiş şablonların siyahısını da açır.

    • 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ə olaraq yazın: mesajı kim yaradır (insan, AI, avtomatlaşdırma), gündə təxminən neçə mesaj gedir, marketinq mesajı üçün razılıq necə alınır.
    • Əlavə verir: başqa scope vermir.

    Endpoint-lər:

    • POST /v1/whatsapp/messages: Nömrəyə WhatsApp mesajı göndərmək. template olanda messages:send.template, fallback_template olanda messages:send və messages:send.template lazımdır
    • GET /v1/whatsapp/templates: Təsdiqlənmiş WhatsApp şablonları. inboxes:read ilə də açılır

    Nümunə:

    curl "https://api.clomni.ai/v1/whatsapp/templates?channel_id=5" \
  -H "Authorization: Bearer clomni_pat_xxx"
    curl -X POST "https://api.clomni.ai/v1/whatsapp/messages" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"channel_id": 5, "phone_number": "+994501234567", "template": {"name": "order_ready", "language": "az", "parameters": {"body": {"1": "Leyla", "2": "A-1042"}}}, "source_reference": "order-A-1042-ready"}'
  9. 9

    Mesaj silmək (messages:delete)

    Mesajı silinmiş kimi işarələyir və fayllarını silir. WhatsApp QR-da mesaj müştərinin telefonunda da geri çəkilir.

    • 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/conversations/{conversation_id}/messages/{message_id}: Mesajı silmək

    Nümunə:

    curl -X DELETE "https://api.clomni.ai/v1/conversations/1042/messages/51240" \
  -H "Authorization: Bearer clomni_pat_xxx"
  10. 10

    Daxili qeyd yazmaq (notes:write)

    Söhbətə daxili qeyd yazır (private: true). Müştəri qeydi görmür. CRM, sifariş sistemi və ya öz botunuz operatora qeyd buraxmaq üçün işlədir. Aşağı riskdir.

    • 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:

    • POST /v1/conversations/{conversation_id}/messages: Mesaj göndərmək və ya daxili qeyd yazmaq. private: true olanda notes:write, template_params olanda messages:send.template lazımdır

    Nümunə:

    curl -X POST "https://api.clomni.ai/v1/conversations/1042/messages" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"content": "CRM: müştəri VIP-dir, ödəniş gecikir.", "private": true}'
  11. 11

    Əlaqəli məqalələr

Sənəd

Developer platforması: bələdçi v1.0 · 41 səhifə Aç Endir