WhatsApp API: mesajın çatdırılma statusunu izləmək

Son yeniləmə: 11 oktyabr 2026 · 6 dəq oxunur

Addımlar

1. 1

   Statuslar

   • sent: Meta qəbul etdi, telefona yola düşdü
   • delivered: müştərinin telefonuna çatdı
   • read: müştəri açıb oxudu
   • failed: göndərilə bilmədi, səbəb external_error sahəsindədir

   Göndərişdən dərhal sonra gələn sent hələ çatdırıldı demək deyil.

2. 2

   Statusu sorğu ilə oxuyun

   curl -s "https://api.clomni.ai/v1/accounts/{account_id}/whatsapp/messages/{message_id}" \
     -H "Authorization: Bearer <API_ACARI>"

   message_id göndərişin cavabındakı id-dir. Cavabın quruluşu mesaj göndərişinin cavabı ilə eynidir. Bu sorğunu hesabın istənilən istifadəçisinin açarı ilə göndərmək olar. Dövri yoxlamaq (polling) mümkündür, amma webhook daha səmərəlidir.

3. 3

   Webhook qurun

   Paneldə Parametrlər › İş sahəsi parametrləri › İnteqrasiyalar səhifəsində Webhook kartında Konfiqurasiya et, sonra Yeni webhook əlavə et. Serverinizin ünvanını yazın, Hadisələr siyahısında Mesaj yeniləndi (message_updated) seçin və Webhook yarat basın. Addımlar ətraflı «Webhook qurmaq» məqaləsindədir.

4. 4

   Webhook-da nə gəlir

   {
     "event": "message_updated",
     "id": 918234,
     "status": "delivered",
     "message_type": "outgoing",
     "whatsapp_message_id": "wamid.HBgMOTk0NTAxMjM0NTY3...",
     "conversation": { "id": 1042 },
     "inbox": { "id": 159, "name": "Şirkət WhatsApp" },
     "sender": { "phone_number": "+994 50 123 45 67" }
   }

   • id göndərişin cavabındakı mesaj id-sidir, öz bazanızda bu id ilə saxlayın.
   • status: sent, delivered, read, failed. Uğursuz mesajda səbəb content_attributes.external_error sahəsində gəlir.
   • Clomni bu sorğunu bir dəfə göndərir və təkrar etmir. Serveriniz 5 saniyə ərzində 2xx qaytarmalıdır: sorğunu öz növbənizə yazıb dərhal cavab verin.
5. 5

   Hər mesaj üçün öz ünvanınıza xəbər (status_callback)

   Göndərişə status_callback bloku əlavə etsəniz, Clomni həmin mesajın vəziyyətini birbaşa sizin ünvanınıza göndərir. Paneldə heç nə qurmaq lazım deyil.

   {
     "channel_id": 159,
     "phone_number": "+994501234567",
     "template": { "name": "otp_code", "language": "az", "parameters": { "1": "4821" } },
     "source_reference": "otp-10422-1791700000",
     "status_callback": {
       "url": "https://example.com/whatsapp/status",
       "after_seconds": 8,
       "on_change": true,
       "secret": "<GIZLI_ACAR>"
     }
   }

   • url (tələb olunur): yalnız https://. Daxili şəbəkə ünvanları qəbul olunmur, yönləndirmə izlənmir.
   • after_seconds (1–3600): göndərişdən N saniyə sonra mesajın o andakı vəziyyəti bir dəfə göndərilir.
   • on_change (true/false): status hər dəyişəndə (delivered, read, failed) dərhal ayrıca xəbər gedir. Meta göndərişi qəbul etməsə (məsələn, səhv nömrə), failed də belə gəlir.
   • after_seconds və on_change-dən ən azı biri olmalıdır.
   • secret (istəyə bağlı): xəbər bu açarla imzalanır. Bizdə şifrələnmiş saxlanılır, cavablarda göstərilmir.

   Serverinizə gələn sorğu:

   {
     "event": "message_status",
     "trigger": "scheduled",
     "message_id": 918234,
     "source_reference": "otp-10422-1791700000",
     "phone_number": "+994501234567",
     "status": "delivered",
     "delivered": true,
     "read": false,
     "sent_at": "2026-10-11T08:00:01Z",
     "delivered_at": "2026-10-11T08:00:04Z",
     "read_at": null,
     "error": null,
     "after_seconds": 8,
     "checked_at": "2026-10-11T08:00:09Z"
   }

   • trigger: scheduled (after_seconds xəbəri) və ya status_change (on_change xəbəri).
   • delivered: true iki boz xətt deməkdir: mesaj telefona çatıb, telefonun interneti var idi.
   • N saniyədən sonra hələ sent qalıbsa, telefon oflayndır, interneti yoxdur və ya WhatsApp uzun müddət açılmayıb. Çatanda on_change ayrıca xəbər verəcək.
   • read yalnız müştəri oxuma bildirişini söndürməyibsə gəlir. Gəlməməsi "oxumayıb" demək deyil.
   • Meta statusları adətən 1–5 saniyəyə gəlir. after_seconds üçün 8–15 saniyə məsləhətdir.

   İmza və təkrar cəhd zəng webhook-ları ilə eynidir: X-ChatX-Delivery, X-ChatX-Timestamp, X-ChatX-Signature (sha256= + HMAC-SHA256(secret, "<timestamp>.<xam gövdə>")). Serveriniz 5 saniyə ərzində 2xx qaytarmalıdır. Bağlantı olmasa, vaxt bitsə, 429 və ya 5xx gəlsə, 10 saniyə və 1 dəqiqə sonra yenidən cəhd edirik. X-ChatX-Delivery hər təkrarda eynidir, onunla təkrarları süzün.

   Toplu göndərişdə də eyni blok işləyir: xəbər hər nömrə üçün ayrıca gedir, gecikmə həmin nömrəyə göndərişdən sayılır. GET /messages/{message_id} cavabında da delivered_at, read_at və status_callback (gizli açarsız) var.

6. 6

   Müştərinin cavabını da alın

   Mesaj yaradıldı (message_created) hadisəsini də seçsəniz, müştərinin cavabı və şablon düyməsinə toxunması sizin sistemə də gəlir. Məhz o an 24 saatlıq pəncərə açılır: növbəti bildirişləri pulsuz mətnlə göndərməyə buradan başlayın.