Dukungan Webhook & API - FAQ
FAQ penggunaan API Chakra Chat dan webhook masuk.
Mencakup webhook peristiwa masuk (pass-through dan format Chakra), penandatanganan HMAC, pemulihan riwayat pesan, Coexistence, dan idempotensi pengiriman.
1. Perilaku Umum Webhook
Apakah webhook mendukung percobaan ulang, antrean, atau pengelompokan? Berapa batas waktu respons dan isi respons yang diperlukan agar pengakuan berhasil?
Tidak ada kebijakan percobaan ulang atau antrean pada webhook Pass through maupun Chakra. Pengakuan berhasil berupa HTTP 200 tanpa perlu isi respons, dan harus dikirim dalam waktu kurang dari 200 ms. Referensi: Dokumentasi Webhook Peristiwa Masuk
Apakah peristiwa webhook dapat dikelompokkan, diduplikasi, atau dikirim dengan urutan yang berbeda? Apakah pengiriman duplikat identik byte demi byte, dan apakah setiap pengiriman ditandatangani dengan HMAC secara terpisah?
Pengelompokan tidak didukung, dan peristiwa dapat tiba tidak berurutan. Referensi: Webhook Peristiwa Masuk — bagian Validasi HMAC
Batas ukuran isi webhook, ukuran kelompok, konkurensi, dan throughput pengiriman apa yang berlaku?
Tidak ada batas yang dipublikasikan. Penggunaan yang wajar diharapkan.
Berapa latensi peristiwa webhook saat berlangganan webhook?
Latensi historis terukur antara peristiwa Meta yang masuk ke Chakra Webhook dan upaya pengiriman peristiwa tersebut adalah sekitar 10-50 ms.
2. Memulihkan Peristiwa yang Terlewat
Jika webhook terlewat, endpoint apa yang dapat mencantumkan pesan masuk, status pengiriman, dan gema Business App yang terlewat?
Tidak ada endpoint khusus untuk "peristiwa yang terlewat". Pesan masuk yang terlewat dapat dipulihkan melalui API riwayat chat, dengan filter berdasarkan ID plugin dan ID nomor telepon WhatsApp. Pencarian serupa untuk status pengiriman atau gema Business App—serta jangka waktu penyimpanan atau angka penundaan konsistensi—tidak dibahas dalam dokumentasi yang dipublikasikan dan sebaiknya dianggap belum tersedia saat ini hingga ada konfirmasi internal. Referensi: Daftar chat | Daftar pesan chat | Daftar pesan sebelumnya untuk nomor telepon
3. Payload & Identifikasi Peristiwa
Di mana saya dapat menemukan payload saat ini yang telah disunting secara lengkap untuk message, status, message_echo, dan smb_message_echo, termasuk status gagal dengan semua kolom error?
Contoh payload dipublikasikan di referensi Inbound Events Webhook. Referensi: Inbound Events Webhook — contoh payload
Untuk event status, message_echo, dan smb_message_echo , kolom mana yang mengidentifikasi plugin, WABA, dan nomor telepon bisnis penerima jika satu akun memiliki beberapa nomor?
Untuk event berformat pass-through/Meta, nomor penerima terdapat di value.metadata.phone_number_id / display_phone_number, sedangkan ID WABA terdapat di entry[].id.
- Contoh event pesan teks masuk: apidocs.chakrahq.com/doc-919167#sample-inbound-text-message-event
- Struktur objek event masuk: apidocs.chakrahq.com/doc-919167#inbound-event-object-structure
Referensi: Inbound Events Webhook
Pesan Business App apa saja yang menghasilkan smb_message_echo, dan apakah ada jenis atau perangkat pendamping yang tidak didukung?
Semua pesan teks dan media dari Business App menghasilkan event smb_message_echo . Jenis pesan yang tidak didukung adalah:
- Polling
- Pesan sementara
- Pesan yang dihapus
Event/kolom apa saja yang di-subscribe oleh WABA kami?
Event berikut di-subscribe dan tersedia melalui webhook pass-through
Webhook account_alerts memberi tahu Anda tentang perubahan pada batas pengiriman pesan, profil bisnis, dan status Official Business Account dari nomor telepon bisnis. | |
Webhook account_review_update memberi tahu Anda saat WhatsApp Business Account telah ditinjau berdasarkan pedoman kebijakan kami. | |
Webhook account_update memberi tahu Anda tentang perubahan pada pengajuan verifikasi bisnis yang dipimpin mitra untuk WhatsApp Business Account, kelayakannya untuk tarif autentikasi internasional , atau lokasi bisnis utamanya saat dibagikan dengan Solution Partner, pelanggaran kebijakan atau ketentuan, pelepasan, penyambungan kembali, atau penghapusannya. | |
Webhook automatic_events memberi tahu Anda saat kami mendeteksi pembelian atau prospek dalam utas chat antara Anda dan pengguna WhatsApp yang mengirim pesan kepada Anda melalui iklan Click to WhatsApp, jika Anda telah memilih untuk ikut serta dalam pelaporan Automatic Events . | |
Webhook business_capability_update memberi tahu Anda tentang perubahan kemampuan WhatsApp Business Account atau portofolio bisnis (batas pengiriman pesan, batas nomor telepon, dll.). | |
Webhook calls memberi tahu Anda tentang event panggilan untuk panggilan yang dimulai pengguna dan panggilan yang dimulai bisnis, seperti saat panggilan tersambung atau diakhiri. | |
Webhook history digunakan untuk menyinkronkan riwayat chat aplikasi WhatsApp Business milik pelanggan bisnis yang telah di-onboard oleh penyedia solusi. | |
Webhook message_template_components_update memberi tahu Anda tentang perubahan pada komponen template. | |
Webhook message_template_quality_update memberi tahu Anda tentang perubahan pada skor kualitas. | |
Webhook message_template_status_update memberi tahu Anda tentang perubahan status template yang sudah ada. | |
Webhook messages menjelaskan pesan yang dikirim oleh pengguna WhatsApp kepada bisnis serta status pesan yang dikirim oleh bisnis kepada pengguna WhatsApp. | |
Webhook partner_solutions menjelaskan perubahan status Multi-Partner Solution. | |
Webhook payment_configuration_update memberi tahu Anda tentang perubahan konfigurasi pembayaran untuk Payments API India dan Payments API Brazil. | |
Webhook phone_number_name_update memberi tahu Anda tentang hasil verifikasi nama tampilan nomor telepon bisnis. | |
Webhook phone_number_quality_update memberi tahu Anda tentang perubahan tingkat throughput. | |
Webhook security memberi tahu Anda tentang perubahan pengaturan keamanan nomor telepon bisnis. | |
Webhook smb_app_state_sync digunakan untuk menyinkronkan kontak dari pengguna aplikasi WhatsApp Business yang telah di-onboard melalui penyedia solusi. | |
Webhook smb_message_echoes memberi tahu Anda tentang pesan yang dikirim melalui aplikasi WhatsApp Business atau perangkat pendamping (”perangkat tertaut”) oleh pelanggan bisnis yang telah di-onboard ke Cloud API melalui penyedia solusi. | |
Webhook template_category_update memberi tahu Anda tentang perubahan pada kategori. | |
Webhook user_preferences memberi tahu Anda tentang perubahan preferensi pesan pemasaran. |
4. Kontrol Pesan Keluar
Apakah akun kami mencakup webhook pass-through, webhook kustom, HMAC, dan echo Coexistence?
Setiap akun Chakra Chat mendukung webhook pass-through, webhook kustom, HMAC, dan echo Coexistence.
5. Secret HMAC & Rotasi
Apakah kami menyediakan secret HMAC, atau Chakra yang membuatnya?
Anda yang menyediakannya, dengan mengaturnya di Admin > Team > Secrets. Referensi: Inbound Events Webhook — Validasi HMAC
Membuat ulang rahasia HMAC tim akan langsung membatalkan rahasia sebelumnya. Prosedur peralihan apa yang mencegah webhook hilang selama rotasi, dan apakah tanda tangan lama dan baru dapat digunakan secara bersamaan untuk sementara? Mekanisme rotasi telah didokumentasikan (rahasia ditetapkan di Admin > Team > Secrets dan dikirim melalui header X-Chakra-Signature-256 ), tetapi prosedur peralihan atau periode penggunaan tanda tangan secara bersamaan tidak didukung. Referensi: Webhook Peristiwa Masuk — Validasi HMAC
Apakah callback dan rahasia yang sama dapat menerima pesan pass-through, status, message_echo, dan peristiwa smb_message_echo ?
Semua peristiwa berformat Chakra dan pass-through (message, status, message_echo, smb_message_echo) menggunakan satu URL callback dan satu rahasia HMAC. Feed pass-through Meta menggunakan URL terpisah, dan penandatanganan HMAC khusus untuk feed tersebut tidak didokumentasikan. Referensi: Webhook Peristiwa Masuk
6. Konfigurasi URL Callback
Di mana URL callback webhook dikonfigurasi — di dasbor atau melalui API? Di dasbor Chakra: halaman WhatsApp Setup → tab "Lainnya" → kolom "URL webhook pass-through" (format Meta) dan kolom "URL webhook Chakra" (format Chakra).
URL ini juga dapat diatur secara terprogram melalui API konfigurasi plugin: apidocs.chakrahq.com/api-33925592
Referensi: Inbound Events Webhook
Apakah callback berlaku untuk seluruh tim, WABA/plugin, atau khusus untuk setiap nomor telepon?
Berlaku per plugin. Setiap instans plugin WhatsApp Setup memiliki kolom URL webhook pass-through dan Chakra sendiri — tidak ada webhook tingkat tim. Dalam satu plugin, webhook khusus WABA/nomor telepon dapat dikonfigurasi. Referensi: Webhook Peristiwa Masuk
7. Idempotensi API
Apakah ada endpoint pengiriman yang mendukung kunci idempotensi klien atau mekanisme pencegahan duplikat? Setelah terjadi timeout, bagaimana kami dapat memastikan apakah pesan diterima?
Parameter kunci idempotensi tidak didukung pada endpoint pengiriman. Pengiriman yang berhasil akan mengembalikan ID pesan WhatsApp (wamid) secara sinkron di isi respons. Langkah terdokumentasi setelah timeout adalah memeriksa riwayat chat/pesan dan mencocokkan dengan wamid tersebut — tidak ada mekanisme kunci idempotensi atau pencegahan duplikat pada panggilan pengiriman itu sendiri. Referensi: Kirim pesan sesi WhatsApp | Daftar pesan chat
8. Pemutusan Koneksi Coexistence
SLA pelepasan dan eskalasi di sisi penyedia apa yang berlaku saat memutuskan koneksi Coexistence, termasuk untuk hubungan partner/penagihan yang masih tersisa?
Pelanggan memberikan detail penagihannya sendiri langsung kepada Meta, sehingga tidak mungkin ada masalah penagihan yang tersisa. Referensi: Putuskan Koneksi Akun WABA | Batalkan pendaftaran nomor telepon bisnis WhatsApp