Resept: saytınızdan WhatsApp bildirişi və şablon göndərmək

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

Addımlar

1. 1

   Nə alırsınız

   • Sisteminizdən bir sorğu ilə WhatsApp bildirişi. Clomni kontaktı və söhbəti özü tapır və ya yaradır.
   • 24 saat pəncərəsi açıqdırsa pulsuz mətn, bağlıdırsa təsdiqlənmiş şablon. Clomni pəncərəni özü yoxlayır.
   • Mesajın sent, delivered, read, failed statusu, webhook ilə də.
   • Bildirişlər operatorların «Açıq» siyahısını doldurmur: söhbət default olaraq bağlı qalır, müştəri cavab yazanda açılır.
2. 2

   WhatsApp-ın iki növü

   • WhatsApp Business API (Cloud): Meta hesabı ilə qoşulur. 24 saat pəncərəsi var, pəncərədən kənarda yalnız təsdiqlənmiş şablon gedir və Meta onun üçün pul alır. /v1/whatsapp/* endpoint-ləri yalnız bu növdə işləyir.
   • WhatsApp QR: telefondakı WhatsApp QR kodla bağlanır. Pəncərə və şablon yoxdur, amma çox mesaj göndərən nömrə bloklana bilər. /v1/whatsapp/messages QR nömrəsindən göndərmir. QR-da yalnız açıq söhbətə cavab yazılır (6-cı addım).
3. 3

   Lazım olan scope-lar

   • messages:send.template (yüksək risk): şablon göndərmək və şablon siyahısı.
   • messages:send (yüksək risk): mətn göndərmək. text ilə fallback_template birlikdə göndərəndə hər iki scope lazımdır.
   • channels:read (aşağı risk): WhatsApp nömrələrinin siyahısı və channel_id.
   • messages:read (orta risk): pəncərəni və mesajın statusunu yoxlamaq, message.* webhook-ları.

   Review formasında gündəlik təxmini sayı, mesajı kimin yaratdığını (insan, sistem, AI) və marketinq mesajı üçün razılığı necə aldığınızı yazın: Review: scope-ların yoxlanması və rədd səbəbləri.

   Profil API açarı ilə işləyən WhatsApp API (WhatsApp API-yə başlamaq: API açarı, account_id və channel_id) ayrıca məhsuldur: orada yol /v1/accounts/{account_id}/whatsapp/...-dir. Developer tokeni ilə yolda workspace ID yoxdur: /v1/whatsapp/.... Toplu göndəriş (bulk_messages) yalnız o API-dədir.

4. 4

   1. Kanalı tapın

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

   Cavabda hər nömrənin channel_id-si və sendable sahəsi var. sendable: false QR nömrəsidir, bu API ondan göndərmir.

5. 5

   2. Şablonu seçin

   curl "https://api.clomni.ai/v1/whatsapp/templates?channel_id=5" \
     -H "Authorization: Bearer clomni_pat_xxx"

   Yalnız Meta-nın təsdiqlədiyi (APPROVED) şablonlar qayıdır. example_parameters şablonun gözlədiyi parametrlərin hazır skeletidir: onu kopyalayıb dəyərləri öz məlumatınızla əvəz edin. API şablon yaratmır: şablonu Meta-da yaradın, sonra paneldə WhatsApp kanalının ayarlarında şablonları sinxronlaşdırın. synced_at siyahının son dəfə nə vaxt alındığını göstərir.

6. 6

   3. 24 saat pəncərəsini anlayın

   Pəncərəni müştəri açır: o sizə yazan andan 24 saat ərzində istənilən mətn gedir. Sizin göndərdiyiniz şablon pəncərəni açmır, müştərinin cavabı və şablondakı sürətli cavab düyməsinə toxunması açır. Bir neçə bildiriş göndərəcəksinizsə, birinci şablona sürətli cavab düyməsi qoyun. Əvvəlcədən yoxlamaq üçün:

   curl "https://api.clomni.ai/v1/whatsapp/messages/window?channel_id=5&phone_number=%2B994501234567" \
     -H "Authorization: Bearer clomni_pat_xxx"

   open: false və last_inbound_at: null bu nömrənin sizə heç yazmadığını göstərir: ilk mesaj şablon olmalıdır.

7. 7

   4. Göndərin

   Təsdiq kodu (şablon):

   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": "verification_code", "language": "az", "parameters": {"body": {"1": "483920"}}}, "contact": {"name": "Leyla Həsənova", "identifier": "crm-10422"}, "source_reference": "otp-10422-1794120000"}'

   Kargo bildirişi (pəncərə açıqdırsa mətn, bağlıdırsa şablon):

   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", "text": "AZ-10422 nömrəli bağlamanız kuryerə verildi.", "fallback_template": {"name": "cargo_status", "language": "az", "parameters": {"body": {"1": "AZ-10422", "2": "kuryerdədir"}}}}'

   • Cavabda sent_as hansının getdiyini deyir: session (mətn) və ya template. Pəncərə bağlıdırsa və fallback_template yoxdursa, heç nə getmir və 422 qayıdır: ödənişli mesaj xəbəriniz olmadan getmir.
   • source_reference sizin unikal açarınızdır. 24 saat ərzində eyni açarla gələn sorğu yeni mesaj yaratmır, birincini qaytarır: müştəri iki kod almır, Meta-ya iki dəfə pul getmir.
   • conversation_status default resolved-dir: söhbət operator siyahısına düşmür. Operator dərhal görsün istəyirsinizsə, open göndərin.
   • Nömrə beynəlxalq formada olmalıdır, 8-15 rəqəm. Boşluq, defis və + silinir. 0501234567 ölkə kodu olmadığı üçün səhvdir.
   • Şablon parametrləri: body üçün {"1": "..."} və ya Meta-da verdiyiniz adlar, header üçün media_url və media_type (image, video, document), düymə üçün url və ya copy_code.
8. 8

   5. Statusu izləyin

   status: "sent" Meta-nın mesajı qəbul etdiyini göstərir, çatdığını yox. Son vəziyyəti oxumaq üçün:

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

   Statuslar: sent, delivered, read, failed (səbəb external_error sahəsində). Hər mesajı ayrıca soruşmaq əvəzinə message.updated webhook-una abunə olun. Müştərinin cavabını almaq üçün message.created əlavə edin. Bax: App webhook-ları və hadisələr: qurmaq, mövzular, imzanın yoxlanması.

9. 9

   6. Açıq söhbətə cavab (Cloud və QR)

   Söhbətin içində yazmaq üçün POST /v1/conversations/{conversation_id}/messages işlədin, {conversation_id} paneldə görünən nömrədir. Bu yol həm Cloud, həm QR kanalında işləyir. Cloud-da pəncərə bağlıdırsa template_params göndərin, bunun üçün messages:send.template lazımdır. Bu yolda göndərmə fonda olur: mesaj getməsə, sonra failed olur, səbəbi content_attributes.external_error-dadır. Avtomatik bildiriş üçün 4-cü addımdakı yol daha sadədir.

10. 10

    Tez-tez səhvlər

    • QR nömrəsindən /v1/whatsapp/messages göndərilir və 422 «This API requires a WhatsApp Cloud API inbox» gəlir. sendable-ı yoxlayın.
    • Şablon adı və ya dil kodu səhvdir, ya da şablon paneldə sinxronlaşdırılmayıb: 422 «No approved template named».
    • Parametr sayı şablonla uyğun deyil və Meta mesajı rədd edir: status failed. example_parameters ilə müqayisə edin.
    • source_reference olmadan təkrar göndərilir və müştəri iki kod alır.
    • sent «çatdı» kimi oxunur. Çatma delivered ilə bilinir.
    • QR-da 463 və ya recipient_restricted gəlir və avtomatik təkrar edilir. Təkrar etməyin: WhatsApp hər cəhdi ayrıca sayır və məhdudiyyəti uzadır.
    • Nömrəsi görünməyən kontakta (identifier @lid ilə bitir) ilk mesaj yazılır. Müştəri əvvəl yazmalı və ya nömrəsini paylaşmalıdır.
    • Razılıq alınmadan marketinq göndərilir. Şikayət nömrənin keyfiyyətini və gündəlik limitini aşağı salır.

    Bütün mesaj endpoint-ləri: Scope-lar və endpoint-lər: söhbətlər və mesajlar.