Öz sisteminizi (CRM, sayt, öz panel, AI, BI) Clomni ilə birləşdirmək: hansı yolu və scope-ları seçmək, developer.clomni.ai-da app yaratmaq, tokenlər, OAuth, endpoint nümunələri, webhook-lar, test kanalı, yoxlama, xətalar və limitlər.

Sənəddən yazılmış məqalələr

• Developer platforması: nədir və hansı yolu seçmək developer.clomni.ai öz proqramlarınızı (CRM, sayt, öz panel, BI) Clomni ilə API vasitəsilə birləşdirmək üçündür. Üç yol var: şəxsi API açarı (Profil parametrləri › API girişi, yalnız WhatsApp API üçün), daxili app (öz workspace-iniz üçün, scope və review ilə) və public app (başqa Clomni hesablarının OAuth ilə qoşduğu app). Hazır app-ı kod yazmadan Parametrlər › İş sahəsi parametrləri › App-lar səhifəsindən qoşursunuz.
• developer.clomni.ai-da app yaratmaq: addım-addım developer.clomni.ai-də «Clomni ilə daxil ol» basın, Developer Şərtlərini qəbul edin, «Yeni app» ilə ad, workspace və scope-ları seçin. App ayarlarında məxfilik siyasəti, dəstək e-poçtu, şirkət və VÖEN yazın, scope-ları review-a göndərin. Ən az bir scope təsdiqlənəndən sonra «Etimadnamələr» bölməsində token yaradın. App yaratmaq üçün workspace-də administrator olmaq lazımdır.
• Hansı scope lazımdır: istəyinizə görə scope və endpoint seçimi İstəyinizi tapın: mesajları CRM-ə və ya anbara çəkmək, WhatsApp bildirişi, öz AI botunuz, Clomni AI agenti öz saytınızda, Power BI hesabatı, ixrac, kampaniya, zəng qeydləri, axın, operator idarəsi, webhook və s. Hər istək üçün minimal scope-lar, risk, review və əsas endpoint-lər. Qayda: yalnız lazım olan scope-u istəyin, review tez keçir.
• Developer API-də tokenlər və autentifikasiya Hər sorğu https://api.clomni.ai/v1 ünvanına Authorization: Bearer <token> başlığı ilə gedir, token bir workspace-ə bağlıdır və ünvanda workspace nömrəsi yazılmır. Daxili app-da şəxsi token (clomni_pat_, «Etimadnamələr» › «Token yarat», 30-365 gün) və ya client_id və client_secret ilə alınan 1 saatlıq app tokeni (clomni_at_) işlədilir. Tokeni GET /v1/me ilə yoxlayın. Token yalnız bir dəfə göstərilir.
• Public app və OAuth: başqa hesabların app-ı qoşması Public app-ı başqa Clomni hesabları OAuth ilə qoşur: app administratoru https://my.clomni.co/oauth/developer/authorize ünvanına göndərir, administrator razılıq ekranında workspace seçib «İcazə ver» basır, app gələn kodu POST /v1/oauth/token ilə 1 saatlıq access token və 90 günlük refresh tokenə dəyişir. PKCE (S256) və state məcburidir, redirect URI hərfi-hərfinə uyğun gəlməlidir.
• Developer API endpoint-lərini işlətmək: nümunələr, səhifələmə, idempotency Endpoint metod və yoldur, məsələn GET https://api.clomni.ai/v1/conversations. Bütün endpoint-lər və lazım olan scope-lar developer.clomni.ai-dakı API reference-dədir. Adi siyahılar page ilə (söhbətlər 25-lik, kontaktlar 15-lik), məlumatı öz bazanıza köçürmək üçün /v1/sync/* updated_since və next_cursor ilə səhifələnir. POST-u təkrar edəndə Idempotency-Key göndərin.
• App webhook-ları və hadisələr: qurmaq, mövzular, imzanın yoxlanması App-ın «Webhook-lar» bölməsində https URL yazın, mövzuları seçin və whsec_ secret-i saxlayın. Clomni URL-ə webhook.verify göndərir: server 5 saniyədə challenge-i qaytarmalıdır. Hər sorğu webhook-id, webhook-timestamp və webhook-signature başlıqları ilə HMAC-SHA256 imzalanır (Standard Webhooks). Server 5 saniyədə 2xx verməlidir, yoxsa Clomni 7 dəfə yenidən göndərir.
• Test kanalı: app-ı real müştərisiz sınamaq Portalın «Test kanalı» bölməsində workspace-in yanında «Test kanalı yarat» basın: workspace-də «Developer test kanalı» adlı API kanal yaranır. POST https://api.clomni.ai/v1/test_channel/messages müştəri adından mesaj yazır, webhook-lar, hadisə lenti və avtomatlaşdırma onu real mesaj kimi görür. Cavablar heç yerə getmir. messages:send və ya conversations:write burada review-dan əvvəl də işləyir.
• Review: scope-ların yoxlanması və rədd səbəbləri Hər scope Clomni əməkdaşının yoxlamasından (review) keçir. Review formasında hər scope üçün ən az 100 simvolla nə edəcəyinizi, hansı funksiyanın işlətdiyini və hansı sahələri saxladığınızı, bir dəfə də istifadə ssenarisini, saxlama müddətini və test addımlarını yazırsınız. Qərar dörd cürdür: təsdiq, qismən təsdiq, düzəliş lazımdır, rədd. Rədd edilən scope-un yanında R01-R12 kodu olur.
• Developer API xətaları və sorğu limitləri Xəta cavabı { error: { code, message, required_scopes, request_id } } formasındadır: kodunuzda code-a baxın. 401 token problemidir, 403 insufficient_scope scope çatmadığını, 429 rate_limited limitin keçildiyini deyir. Limitlər: token üzrə dəqiqədə 300 sorğu, app üzrə 600, /sync/* və mesaj göndərmə 60, /oauth/token 20. 429-da Retry-After qədər gözləyin, 400, 401, 403, 404, 422 cavablarını təkrar etməyin.
• Paneldə App-lar: app qoşmaq, icazələr və ləğv etmək Parametrlər › İş sahəsi parametrləri › App-lar səhifəsində «Kataloq» Clomni-nin təsdiqlədiyi hazır app-ları, «Bağlı app-lar» isə workspace-ə qoşulanları göstərir. App-ın səhifəsində «Qoş» basın, razılıq ekranında workspace seçib icazələri oxuyun və «İcazə ver» basın. Ləğv etmək üçün «Bağlı app-lar»da «Ləğv et» seçin: app girişini dərhal itirir. App qoşmaq və ləğv etmək yalnız administratora açıqdır.
• Scope-lar və endpoint-lər: workspace, operatorlar, komandalar workspace:read, workspace:write, billing:read, audit_logs:read, agents:read, agents:manage, teams:read, teams:write: hər scope nə icazə verir, riski, yoxlaması, nəyi əlavə verir və açdığı 18 endpoint (metod, /v1 yolu, nə edir), curl nümunələri ilə.
• Scope-lar və endpoint-lər: inbox-lar və kanallar inboxes:read, inboxes:write, channels:read, channels:manage: hər scope nə icazə verir, riski, yoxlaması, nəyi əlavə verir və açdığı 12 endpoint (metod, /v1 yolu, nə edir), curl nümunələri ilə.
• Scope-lar və endpoint-lər: söhbətlər və mesajlar conversations:read, conversations:write, conversations:assign, conversations:delete, messages:read, messages:send, messages:send.template, messages:delete, notes:write: hər scope nə icazə verir, riski, yoxlaması, nəyi əlavə verir və açdığı 42 endpoint (metod, /v1 yolu, nə edir), curl nümunələri ilə.
• Scope-lar və endpoint-lər: kontaktlar, etiketlər, xüsusi sahələr, hazır cavablar contacts:read, contacts:write, contacts:import, contacts:delete, labels:read, labels:write, canned_responses:read, canned_responses:write, custom_attributes:read, custom_attributes:write: hər scope nə icazə verir, riski, yoxlaması, nəyi əlavə verir və açdığı 45 endpoint (metod, /v1 yolu, nə edir), curl nümunələri ilə.
• Scope-lar və endpoint-lər: hesabatlar, CSAT, SLA reports:read, csat:read, sla:read, sla:write: hər scope nə icazə verir, riski, yoxlaması, nəyi əlavə verir və açdığı 32 endpoint (metod, /v1 yolu, nə edir), curl nümunələri ilə.
• Scope-lar və endpoint-lər: kampaniyalar, axınlar, avtomatlaşdırma campaigns:read, campaigns:write, campaigns:send, flows:read, flows:write, flows:publish, automations:read, automations:write, automations:publish: hər scope nə icazə verir, riski, yoxlaması, nəyi əlavə verir və açdığı 39 endpoint (metod, /v1 yolu, nə edir), curl nümunələri ilə.
• Scope-lar və endpoint-lər: AI agentlər, bilik bazası, kömək mərkəzi ai_agents:read, ai_agents:write, ai_agents:train, ai_agents:publish, ai_agents:ask, knowledge:read, knowledge:write, ai_logs:read, help_center:read, help_center:write: hər scope nə icazə verir, riski, yoxlaması, nəyi əlavə verir və açdığı 63 endpoint (metod, /v1 yolu, nə edir), curl nümunələri ilə.
• Scope-lar və endpoint-lər: zənglər, webhook-lar, hadisələr, ixrac calls:read, webhooks:read, webhooks:write, events:read, exports:run: hər scope nə icazə verir, riski, yoxlaması, nəyi əlavə verir və açdığı 6 endpoint (metod, /v1 yolu, nə edir), curl nümunələri ilə.
• Resept: CRM ilə kontakt sinxronu Clomni kontaktlarını CRM ilə uyğun saxlamaq: scope-lar contacts:read, contacts:write, custom_attributes:read. Əvvəl GET /v1/sync/contacts ilə hamısını yükləyin, sonra updated_since ilə dəyişənləri götürün, contact.created və contact.updated webhook-ları ilə dərhal alın. CRM ID-ni identifier sahəsinə yazın, POST /v1/contacts və PATCH /v1/contacts/{contact_id} ilə Clomni-yə yazın.
• Resept: saytınızdan WhatsApp bildirişi və şablon göndərmək Saytınızdan və ya sisteminizdən WhatsApp Business API (Cloud) nömrəsi ilə təsdiq kodu, sifariş və kargo bildirişi göndərmək. Scope-lar messages:send.template, messages:send, channels:read, messages:read. GET /v1/whatsapp/channels, GET /v1/whatsapp/templates, POST /v1/whatsapp/messages, status üçün message.updated. QR nömrəsi bu API ilə göndərmir.
• Resept: AI agentdən cavab almaq, bilik bazası və öz botunuz Üç iş: Clomni AI agentindən öz saytınızda cavab almaq (ai_agents:read, ai_agents:ask, POST /v1/ai_agents/{ai_agent_id}/ask), bilik bazasını avtomatik yeniləmək (knowledge:write, POST /v1/knowledge) və öz AI botunuzu Clomni söhbətlərinə qoşmaq (messages:read, messages:send, conversations:assign, message.created webhook-u). Xərc AI kreditindən çıxılır.
• Resept: tarixçəni ixrac etmək və davamlı sinxron Söhbət, mesaj və kontakt tarixçəsini bir faylda almaq (exports:run, POST /v1/exports, GET /v1/exports/{export_id}, gzip JSONL) və sonra yalnız dəyişənləri sinxron endpoint-ləri (GET /v1/sync/messages, /sync/conversations, /sync/contacts) və webhook ilə götürmək. Limit: eyni anda 1 ixrac, 24 saatda 6. Hesabat rəqəmləri üçün reports:read.
• Resept: Clomni söhbətlərini öz panelinizdə göstərmək Clomni söhbətlərini şirkətin öz daxili panelində göstərmək: siyahı (GET /v1/conversations), mesajlar, cavab (POST /v1/conversations/{conversation_id}/messages), daxili qeyd, status, təyinat və webhook ilə canlı yeniləmə. «Öz panelimdə Clomni» hazır dəsti: conversations:read, conversations:write, conversations:assign, messages:read, messages:send, notes:write və s.