WHAPI Documentation untuk Integrasi Notifikasi Webhook<\/a><\/p>\n8. Gunakan ID Pesan untuk Melacak Pengiriman<\/h2>\n
Jika response pengiriman menghasilkan ID pesan, simpan ID tersebut di database.<\/p>\n
Contoh struktur sederhana:<\/p>\n
messages\r\n\u251c\u2500\u2500 id<\/span>\r\n\u251c\u2500\u2500 phone\r\n\u251c\u2500\u2500 message\r\n\u251c\u2500\u2500 id_message\r\n\u251c\u2500\u2500 status\r\n\u251c\u2500\u2500 created_at\r\n\u2514\u2500\u2500 updated_at\r\n<\/code><\/pre>\nSaat request berhasil dibuat:<\/p>\n
status<\/span> = queued\r\n<\/code><\/pre>\nKemudian status dapat diperbarui berdasarkan event yang diterima dari webhook:<\/p>\n
queued\r\n\u2193\r\nsent\r\n\u2193\r\ndelivered\r\n\u2193\r\nread<\/span>\r\n<\/code><\/pre>\nJika pengiriman gagal:<\/p>\n
queued<\/span>\r\n\u2193\r\nfailed\r\n<\/code><\/pre>\nDengan cara ini, sistem tidak hanya mengetahui bahwa request API pernah dilakukan, tetapi juga dapat mengetahui perkembangan pengiriman pesan.<\/p>\n
9. Periksa Webhook Status Pesan<\/h2>\n
Webhook berguna untuk mengetahui perubahan status pesan setelah proses pengiriman dimulai.<\/p>\n
Pastikan webhook:<\/p>\n
\n- Menggunakan URL yang dapat diakses server.<\/li>\n
- Menerima HTTP POST.<\/li>\n
- Membaca payload dengan benar.<\/li>\n
- Mengaktifkan event status pesan.<\/li>\n
- Mengembalikan HTTP 200 setelah menerima data.<\/li>\n<\/ol>\n
Whapi menyediakan event message_ack<\/code> untuk status pesan dan change_state<\/code> untuk perubahan koneksi device. <\/p>\nContoh receiver sederhana:<\/p>\n
app.post('\/webhook\/whapi'<\/span>, (req, res)<\/span> =><\/span> {\r\n const payload = req.body;\r\n\r\n console<\/span>.log('Webhook:'<\/span>, payload);\r\n\r\n \/\/<\/span> Simpan atau proses status pesan di sini\r\n\r\n res.sendStatus(200<\/span>);\r\n});\r\n<\/code><\/pre>\nJangan menunggu seluruh proses bisnis selesai sebelum memberikan response kepada webhook jika proses tersebut membutuhkan waktu lama.<\/p>\n
Simpan event terlebih dahulu, berikan response yang sesuai, kemudian proses data melalui worker atau queue jika diperlukan.<\/p>\n
10. Jangan Langsung Retry Semua Pesan<\/h2>\n
Retry dapat membantu ketika terjadi gangguan sementara, tetapi retry tanpa aturan dapat membuat masalah semakin besar.<\/p>\n
Misalnya, sistem mengirim pesan berkali-kali karena tidak membedakan antara:<\/p>\n
\n- request timeout,<\/li>\n
- API error,<\/li>\n
- device offline,<\/li>\n
- nomor tidak valid,<\/li>\n
- dan pesan yang sebenarnya sudah diterima.<\/li>\n<\/ul>\n
Gunakan retry hanya untuk kondisi yang memang dapat dicoba kembali.<\/p>\n
Contoh sederhana:<\/p>\n
const<\/span> maxRetry = 3<\/span>;\r\n\r\nfor<\/span> (let attempt = 1<\/span>; attempt <= maxRetry; attempt++) {\r\n try<\/span> {\r\n const<\/span> response = await sendMessage<\/span>()<\/span><\/span>;\r\n\r\n if<\/span> (response.ok) {\r\n break<\/span>;\r\n }\r\n } catch<\/span> (error<\/span>) {\r\n if<\/span> (attempt === maxRetry) {\r\n throw<\/span> error<\/span>;\r\n }\r\n }\r\n}\r\n<\/code><\/pre>\nUntuk sistem produksi, retry sebaiknya menggunakan jeda antarpercobaan dan pencatatan status agar pesan tidak terkirim berulang kali.<\/p>\n
11. Periksa Timeout dan Koneksi Server<\/h2>\n
Request dapat gagal bukan karena WhatsApp, tetapi karena server aplikasi tidak berhasil menyelesaikan komunikasi dengan API.<\/p>\n
Periksa:<\/p>\n
\n- koneksi internet server,<\/li>\n
- DNS,<\/li>\n
- firewall,<\/li>\n
- outbound connection,<\/li>\n
- timeout HTTP client,<\/li>\n
- proxy,<\/li>\n
- dan konfigurasi SSL.<\/li>\n<\/ul>\n
Jika request membutuhkan waktu terlalu lama, aplikasi dapat menganggap request gagal meskipun proses di sisi API masih berjalan.<\/p>\n
Karena itu, status request dan status pesan perlu disimpan secara terpisah.<\/p>\n
Contoh:<\/p>\n
API request\r\n \u2193\r\naccepted\r\n \u2193\r\nmessage<\/span> ID\r\n \u2193\r\nmessage<\/span> status\r\n \u2193\r\ndelivered \/ read<\/span> \/ failed\r\n<\/code><\/pre>\nStruktur ini membuat sistem lebih mudah membedakan error komunikasi dengan status pengiriman pesan.<\/p>\n
12. Periksa Isi Pesan Dinamis<\/h2>\n
Pesan yang dibuat dari template atau database juga dapat menyebabkan masalah.<\/p>\n
Contoh:<\/p>\n
const<\/span> message = `Halo ${customer.name}<\/span>, pesanan ${order.id}<\/span> sudah diproses.`<\/span>;\r\n<\/code><\/pre>\nJika customer.name<\/code> atau order.id<\/code> tidak tersedia, hasilnya dapat menjadi:<\/p>\nHalo undefined<\/span>, pesanan undefined<\/span> sudah diproses.\r\n<\/code><\/pre>\nKarena itu, validasi data sebelum request.<\/p>\n
if<\/span> (!customer?.name || !order<\/span>?.id) {\r\n throw<\/span> new<\/span> Error('Data pesan tidak lengkap'<\/span>);\r\n}\r\n<\/code><\/pre>\nUntuk sistem notifikasi transaksi, validasi sebaiknya dilakukan sebelum pesan dimasukkan ke antrean pengiriman.<\/p>\n
13. Cek Apakah Device Logout Setelah Pesan Gagal<\/h2>\n
Jika sebelumnya pengiriman berjalan normal kemudian semua pesan mulai gagal, periksa status device.<\/p>\n
Jangan hanya memeriksa kode aplikasi.<\/p>\n
Device yang kehilangan koneksi dapat membuat seluruh request berikutnya gagal meskipun kode pengiriman tidak berubah.<\/p>\n
Status device dapat diperiksa melalui endpoint status koneksi atau webhook perubahan koneksi. Whapi menyediakan status seperti CONNECTED<\/code>, SERVICE_OFF<\/code>, SERVICE_SCAN<\/code>, dan PAIRING<\/code>.<\/p>\nJika masalah terjadi berulang setelah device kembali terhubung, lanjutkan pemeriksaan pada log device dan waktu terjadinya disconnect.<\/p>\n
14. Gunakan Urutan Troubleshooting yang Konsisten<\/h2>\n
Agar pemeriksaan tidak berputar-putar, gunakan urutan berikut:<\/p>\n
1. <\/span>Cek status device\r\n \u2193<\/span>\r\n2. <\/span>Tes kirim dari dashboard\r\n \u2193<\/span>\r\n3. <\/span>Cek API Key\r\n \u2193<\/span>\r\n4. <\/span>Cek nomor tujuan\r\n \u2193<\/span>\r\n5. <\/span>Cek endpoint dan HTTP method\r\n \u2193<\/span>\r\n6. <\/span>Cek Content-Type dan request body\r\n \u2193<\/span>\r\n7. <\/span>Cek HTTP response\r\n \u2193<\/span>\r\n8. <\/span>Simpan ID pesan\r\n \u2193<\/span>\r\n9. <\/span>Cek status melalui webhook\r\n \u2193<\/span>\r\n10. <\/span>Cek retry dan timeout\r\n \u2193<\/span>\r\n11. <\/span>Periksa log server\r\n<\/code><\/pre>\nUrutan ini membantu menentukan lokasi masalah sebelum perubahan kode dilakukan.<\/p>\n
15. Buat Log Pengiriman yang Mudah Dicari<\/h2>\n
Untuk aplikasi yang mengirim banyak pesan, log sederhana seperti:<\/p>\n
Pesan gagal dikirim<\/span>\r\n<\/code><\/pre>\ntidak cukup.<\/p>\n
Gunakan informasi seperti:<\/p>\n
{\r\n \"phone\"<\/span>: \"6281234567890\"<\/span>,\r\n \"message_id\"<\/span>: \"MESSAGE_ID\"<\/span>,\r\n \"status\"<\/span>: \"failed\"<\/span>,\r\n \"http_status\"<\/span>: 400<\/span>,\r\n \"created_at\"<\/span>: \"2026-10-04T10:30:00+07:00\"<\/span>\r\n}\r\n<\/code><\/pre>\nDengan data tersebut, satu pesan dapat dilacak dari request awal sampai status akhirnya.<\/p>\n
Untuk volume tinggi, simpan log pengiriman ke database atau sistem logging terpusat daripada hanya mengandalkan file log server.<\/p>\n
16. Buat Status Pengiriman di Database<\/h2>\n
Sistem produksi sebaiknya tidak hanya memiliki status:<\/p>\n
success\r\n<\/span>failed\r\n<\/code><\/pre>\nGunakan status yang menggambarkan proses secara lebih jelas.<\/p>\n
Contoh:<\/p>\n
pending\r\nsending\r\nsent\r\ndelivered\r\nread<\/span>\r\nfailed\r\n<\/code><\/pre>\nContohnya:<\/p>\n
pending\r\n \u2193\r\nsending\r\n \u2193\r\nsent\r\n \u2193\r\ndelivered\r\n \u2193\r\nread<\/span>\r\n<\/code><\/pre>\nJika terjadi kegagalan:<\/p>\n
sending<\/span>\r\n \u2193\r\nfailed\r\n<\/code><\/pre>\nStatus ini dapat digunakan untuk dashboard, laporan transaksi, retry, dan pemeriksaan pesan secara individual.<\/p>\n
17. Kapan Pesan Perlu Dikirim Ulang?<\/h2>\n
Pesan tidak selalu perlu dikirim ulang ketika statusnya gagal.<\/p>\n
Sebelum retry, periksa:<\/p>\n
\n- apakah device sudah CONNECTED,<\/li>\n
- apakah error bersifat sementara,<\/li>\n
- apakah request sebelumnya sudah menghasilkan ID pesan,<\/li>\n
- apakah status akhir sudah diterima melalui webhook,<\/li>\n
- dan apakah retry dapat menyebabkan pesan ganda.<\/li>\n<\/ul>\n
Untuk notifikasi transaksi, duplikasi pesan dapat lebih bermasalah daripada pesan yang terlambat.<\/p>\n
Gunakan ID transaksi atau ID pesan sebagai acuan untuk mencegah pengiriman yang sama diproses berkali-kali.<\/p>\n
Contoh:<\/p>\n
order_id <\/span>= INV-2026-00125\r\n\r\nJika <\/span>sudah pernah dikirim:\r\n<\/span>jangan <\/span>kirim ulang secara otomatis.\r\n<\/code><\/pre>\n18. Checklist Sebelum Mengubah Kode<\/h2>\n
Ketika pesan WhatsApp gagal terkirim, periksa checklist berikut:<\/p>\n
\n- [ ] Device berstatus
CONNECTED<\/code><\/li>\n- [ ] Pengiriman dari dashboard berhasil<\/li>\n
- [ ] API Key sesuai dengan device<\/li>\n
- [ ] Nomor tujuan sudah dinormalisasi<\/li>\n
- [ ] Endpoint benar<\/li>\n
- [ ] HTTP method benar<\/li>\n
- [ ] Content-Type sesuai<\/li>\n
- [ ] Request body lengkap<\/li>\n
- [ ] HTTP response sudah dicatat<\/li>\n
- [ ] ID pesan disimpan<\/li>\n
- [ ] Webhook status aktif<\/li>\n
- [ ] Event
message_ack<\/code> diterima<\/li>\n- [ ] Timeout tidak terlalu pendek<\/li>\n
- [ ] Retry tidak menyebabkan duplikasi<\/li>\n
- [ ] Log server dapat ditelusuri<\/li>\n<\/ul>\n
Jika semua pemeriksaan tersebut sudah dilakukan, lokasi masalah biasanya dapat dipersempit ke device, request aplikasi, koneksi server, atau proses pengiriman setelah request diterima.<\/p>\n
Kesimpulan<\/h2>\n
Cara mengatasi pesan WhatsApp gagal terkirim dari API sebaiknya dimulai dari pemeriksaan device, kemudian request API, response, dan status pesan.<\/p>\n
Jangan hanya melihat apakah HTTP request berhasil. Sistem pengiriman yang baik perlu membedakan antara request diterima API<\/strong> dan pesan benar-benar berhasil dikirim<\/strong>.<\/p>\nDengan menyimpan ID pesan, memantau message_ack<\/code> melalui webhook, mencatat error, dan menerapkan retry secara terkontrol, proses pengiriman WhatsApp menjadi lebih mudah dipantau dan diperbaiki ketika terjadi kegagalan.<\/p>\nUntuk masalah yang lebih spesifik, seperti pesan gagal karena device sering terputus atau logout, pemeriksaan perlu dilanjutkan pada sisi koneksi device.<\/p>\n
![\"Cara](\"https:\/\/whapi.id\/blog\/wp-content\/uploads\/2026\/10\/Cara-Mengatasi-Pesan-WhatsApp-Gagal-Terkirim.jpg\")
<\/p>\n