![\"Apa](\"https:\/\/whapi.id\/blog\/wp-content\/uploads\/2026\/10\/Apa-Penyebab-Pesan-WhatsApp-Gagal-Terkirim-dari-API.jpg\")
<\/p>\nPesan WhatsApp dapat gagal terkirim dari API karena device tidak terhubung, nomor tujuan tidak valid, request tidak sesuai format, API key bermasalah, atau server mengalami error. Pemeriksaan perlu dilakukan dari proses request sampai status pesan untuk menemukan bagian yang menyebabkan pengiriman gagal.<\/p>\n
<\/p>\n
Alur pengiriman pesan melalui API secara umum:<\/p>\n
Aplikasi\r\n \u2193\r\nRequest API\r\n \u2193\r\nAPI WhatsApp\r\n \u2193\r\nDevice WhatsApp\r\n \u2193\r\nNomor Tujuan\r\n \u2193\r\nStatus Pesan\r\n`\r\n<\/code><\/pre>\nError dapat terjadi pada salah satu tahap tersebut.<\/p>\n
1. Device WhatsApp Tidak Terhubung<\/h2>\n
Device merupakan bagian penting dalam pengiriman pesan melalui WhatsApp API.<\/p>\n
Jika device sedang tidak terhubung, request pengiriman dapat gagal atau pesan tidak dapat diproses seperti biasa.<\/p>\n
Periksa status device sebelum mencari masalah pada kode.<\/p>\n
Contoh kondisi:<\/p>\n
Device:<\/span> CONNECTED\r\n<\/code><\/pre>\natau:<\/p>\n
Device:<\/span> DISCONNECTED\r\n<\/code><\/pre>\nJika device terputus, periksa koneksi device terlebih dahulu.<\/p>\n
Untuk sistem yang menggunakan banyak device, pastikan API key yang digunakan memang terhubung dengan device yang sedang diperiksa.<\/p>\n
2. API Key Salah<\/h2>\n
API key digunakan untuk mengakses API.<\/p>\n
Jika API key salah, tidak valid, atau tidak sesuai dengan konfigurasi device, request tidak dapat diproses.<\/p>\n
Contoh konfigurasi:<\/p>\n
const payload<\/span> = {\r\n apiKey: 'API_KEY_WHAPI'<\/span>,\r\n phone: '628123456789'<\/span>,\r\n message: 'Pesan dari API'<\/span>\r\n};\r\n<\/code><\/pre>\nJangan menambahkan spasi atau karakter lain ke API key.<\/p>\n
Jika API key disimpan pada environment variable, periksa apakah nilai tersebut benar-benar terbaca oleh aplikasi.<\/p>\n
Contoh:<\/p>\n
const<\/span> apiKey = process<\/span>.env.WHAPI_API_KEY;\r\n\r\nconsole.log(\r\n apiKey ? 'API key tersedia'<\/span> : 'API key tidak ditemukan'<\/span>\r\n);\r\n<\/code><\/pre>\nJangan mencetak API key lengkap ke log production.<\/p>\n
3. Nomor Tujuan Tidak Valid<\/h2>\n
Nomor tujuan merupakan salah satu penyebab umum pesan gagal dikirim.<\/p>\n
Periksa:<\/p>\n
\n- Nomor memiliki kode negara.<\/li>\n
- Tidak ada karakter yang tidak diperlukan.<\/li>\n
- Nomor tidak tertukar dengan nomor lain.<\/li>\n
- Format nomor sesuai dengan format yang diterima API.<\/li>\n<\/ul>\n
Contoh format nomor Indonesia:<\/p>\n
628123456789<\/span>\r\n<\/code><\/pre>\nBukan:<\/p>\n
08123456789<\/span>\r\n<\/code><\/pre>\nJika nomor berasal dari form atau database, lakukan validasi sebelum request dikirim.<\/p>\n
Contoh:<\/p>\n
function<\/span> normalizePhone<\/span>(phone<\/span>) <\/span>{\r\n return<\/span> phone\r\n .replace(\/\\D\/g<\/span>, ''<\/span>)\r\n .replace(\/^0\/<\/span>, '62'<\/span>);\r\n}\r\n<\/code><\/pre>\nFungsi tersebut hanya contoh dasar. Aturan normalisasi perlu disesuaikan dengan format nomor yang digunakan sistem.<\/p>\n
4. Request Tidak Sesuai Format API<\/h2>\n
Request API harus mengikuti format endpoint yang digunakan.<\/p>\n
Misalnya pengiriman pesan menggunakan:<\/p>\n
POST \/api\/<\/span>sendMessage\r\n<\/code><\/pre>\nmaka method dan parameter harus mengikuti dokumentasi endpoint tersebut.<\/p>\n
Contoh request menggunakan PHP:<\/p>\n
$data = [\r\n 'apiKey'<\/span> => $apiKey,\r\n 'phone'<\/span> => $phone,\r\n 'message'<\/span> => $message\r\n];\r\n\r\ncurl_setopt($ch, CURLOPT_POST, true<\/span>);\r\ncurl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));\r\n<\/code><\/pre>\nKesalahan pada nama parameter dapat membuat request gagal.<\/p>\n
Contohnya:<\/p>\n
phone<\/span>\r\n<\/code><\/pre>\nberbeda dengan:<\/p>\n
phone_number\r\n<\/code><\/pre>\nJangan mengganti nama parameter berdasarkan asumsi. Gunakan parameter yang tersedia pada endpoint API yang digunakan.<\/p>\n
5. Method HTTP Salah<\/h2>\n
Endpoint pengiriman pesan dapat membutuhkan method tertentu.<\/p>\n
Jika endpoint membutuhkan POST<\/code> tetapi aplikasi mengirim GET<\/code>, request tidak akan diproses sesuai kebutuhan.<\/p>\nContoh:<\/p>\n
const<\/span> response = await<\/span> fetch(url<\/span>, {\r\n method<\/span>: 'POST'<\/span>,\r\n body<\/span>: new<\/span> URLSearchParams({\r\n apiKey,\r\n phone,\r\n message\r\n })\r\n});\r\n<\/code><\/pre>\nPeriksa method, URL, dan body request ketika pengiriman gagal.<\/p>\n
6. Content-Type Tidak Sesuai<\/h2>\n
Selain method, format body request juga perlu sesuai dengan endpoint.<\/p>\n
Contohnya, API dapat menerima data dalam format form-encoded.<\/p>\n
Pada PHP:<\/p>\n
curl_setopt(\r\n $ch,\r\n CURLOPT_POSTFIELDS,\r\n http_build_query($data)\r\n);<\/span>\r\n<\/code><\/pre>\nPada Node.js:<\/p>\n
const<\/span> body<\/span> = new<\/span> URLSearchParams({\r\n apiKey,\r\n phone,\r\n message\r\n});\r\n<\/code><\/pre>\nKesalahan Content-Type<\/code> dapat menyebabkan API tidak membaca parameter yang dikirim.<\/p>\nJika request menggunakan JSON, tetapi endpoint mengharapkan form data, parameter dapat dianggap tidak tersedia.<\/p>\n
7. Pesan Kosong<\/h2>\n
API membutuhkan isi pesan jika endpoint yang digunakan adalah endpoint pengiriman pesan teks.<\/p>\n
Contoh:<\/p>\n
const<\/span> message = ''<\/span>;\r\n\r\nif<\/span> (!message.trim()) {\r\n throw<\/span> new<\/span> Error<\/span>('Pesan tidak boleh kosong'<\/span>);\r\n}\r\n<\/code><\/pre>\nMasalah ini sering terjadi ketika isi pesan diambil dari database, form, atau template.<\/p>\n
Contohnya:<\/p>\n
Nama:<\/span> Budi\r\nPesan:<\/span> [kosong]\r\n<\/code><\/pre>\nSebelum request dikirim, validasi data yang menjadi isi pesan.<\/p>\n
8. Data Dinamis Tidak Tersedia<\/h2>\n
Pesan yang dibuat dari template dapat gagal karena salah satu variabel tidak memiliki nilai.<\/p>\n
Contoh:<\/p>\n
const<\/span> message =\r\n `Halo ${name}<\/span>, pesanan ${orderNumber}<\/span> sudah diproses.`<\/span>;\r\n<\/code><\/pre>\nJika name<\/code> atau orderNumber<\/code> tidak tersedia, pesan yang dikirim dapat menjadi tidak sesuai.<\/p>\nGunakan validasi:<\/p>\n
if<\/span> (!name || !orderNumber) {\r\n throw<\/span> new<\/span> Error<\/span>(\r\n 'Data pelanggan atau nomor pesanan tidak tersedia'<\/span>\r\n );\r\n}\r\n<\/code><\/pre>\nValidasi sebelum request membantu membedakan error data dengan error API.<\/p>\n
9. Nomor Tidak Dapat Menerima Pesan<\/h2>\n
Format nomor yang benar tidak selalu berarti nomor tersebut dapat menerima pesan.<\/p>\n
Nomor dapat sudah tidak aktif atau tidak tersedia pada layanan WhatsApp.<\/p>\n
Karena itu, aplikasi tidak sebaiknya menganggap:<\/p>\n
Nomor valid\r\n=\r\nPesan pasti terkirim\r\n<\/code><\/pre>\nStatus pengiriman tetap perlu diperiksa dari response dan event yang diterima setelah request.<\/p>\n
10. Device Berubah atau Logout<\/h2>\n
Pada sistem dengan banyak device, device dapat berubah status atau mengalami logout.<\/p>\n
Contohnya:<\/p>\n
Device 01<\/span>\r\nCONNECTED\r\n<\/code><\/pre>\nkemudian:<\/p>\n
Device 01<\/span>\r\nDISCONNECTED\r\n<\/code><\/pre>\nJika aplikasi masih mencoba mengirim menggunakan device tersebut, pengiriman dapat gagal.<\/p>\n
Sistem sebaiknya memeriksa status device dan menyediakan monitoring untuk perubahan koneksi.<\/p>\n
11. Request Mengalami Timeout<\/h2>\n
Pengiriman dapat gagal jika aplikasi tidak mendapatkan response dalam waktu yang diharapkan.<\/p>\n
Contohnya:<\/p>\n
Aplikasi\r\n \u2193\r\nRequest API\r\n \u2193\r\nMenunggu\r\n \u2193\r\nTimeout<\/span>\r\n<\/code><\/pre>\nPeriksa:<\/p>\n
\n- koneksi server;<\/li>\n
- DNS;<\/li>\n
- firewall;<\/li>\n
- koneksi internet;<\/li>\n
- konfigurasi timeout;<\/li>\n
- response API.<\/li>\n<\/ul>\n
Pada aplikasi production, gunakan timeout agar proses tidak menunggu tanpa batas.<\/p>\n
Contoh Node.js:<\/p>\n
const<\/span> controller = new<\/span> AbortController();\r\n\r\nconst<\/span> timeout = setTimeout(()<\/span> =><\/span> {\r\n controller.abort();\r\n}, 10000<\/span>);\r\n\r\ntry<\/span> {\r\n const<\/span> response = await<\/span> fetch(url, {\r\n method<\/span>: 'POST'<\/span>,\r\n body,\r\n signal<\/span>: controller.signal\r\n });\r\n\r\n console<\/span>.log(await<\/span> response.text());\r\n\r\n} finally<\/span> {\r\n clearTimeout(timeout);\r\n}\r\n<\/code><\/pre>\nNilai timeout perlu disesuaikan dengan kebutuhan aplikasi.<\/p>\n
12. Server Tidak Dapat Mengakses API<\/h2>\n
Jika aplikasi berada di server dengan aturan jaringan yang ketat, request keluar dapat diblokir.<\/p>\n
Contohnya:<\/p>\n
Aplikasi<\/span>\r\n \u2193\r\nFirewall\r\n X\r\nAPI\r\n<\/code><\/pre>\nPeriksa konfigurasi firewall dan koneksi keluar dari server.<\/p>\n
Masalah ini berbeda dengan error dari API. Jika request tidak pernah keluar dari server, response dari API juga tidak akan diterima.<\/p>\n
13. Response API Menunjukkan Error<\/h2>\n
Jangan hanya memeriksa apakah request menghasilkan exception.<\/p>\n
Simpan HTTP status code dan response body.<\/p>\n
Contoh:<\/p>\n
const<\/span> response = await<\/span> fetch(url<\/span>, {\r\n method<\/span>: 'POST'<\/span>,\r\n body\r\n});\r\n\r\nconst<\/span> responseBody = await<\/span> response.text();\r\n\r\nconsole<\/span>.log('Status:'<\/span>, response.status);\r\nconsole<\/span>.log('Response:'<\/span>, responseBody);\r\n<\/code><\/pre>\nInformasi tersebut membantu membedakan:<\/p>\n
Request berhasil<\/span>\r\n<\/code><\/pre>\ndari:<\/p>\n
Request diterima tetapi ditolak<\/span>\r\n<\/code><\/pre>\ndan:<\/p>\n
Request<\/span> tidak mendapatkan response<\/span>\r\n<\/code><\/pre>\nKetiganya membutuhkan pemeriksaan yang berbeda.<\/p>\n
14. Error 400 Bad Request<\/h2>\n
Status 400<\/code> biasanya menunjukkan request tidak sesuai dengan data yang dibutuhkan endpoint.<\/p>\nPeriksa:<\/p>\n
\n- Parameter wajib.<\/li>\n
- Nama parameter.<\/li>\n
- Format nomor.<\/li>\n
- Isi pesan.<\/li>\n
- Format body.<\/li>\n
- Method HTTP.<\/li>\n<\/ul>\n
Contoh:<\/p>\n
POST \/api\/<\/span>sendMessage\r\n<\/code><\/pre>\ntetapi body tidak memiliki parameter yang diwajibkan.<\/p>\n
Jangan langsung melakukan retry untuk error seperti ini. Perbaiki request terlebih dahulu.<\/p>\n
15. Error 401 atau 403<\/h2>\n
Status 401<\/code> atau 403<\/code> berkaitan dengan akses atau autentikasi.<\/p>\nPeriksa:<\/p>\n
API key<\/span>\r\n\u2193\r\nDevice\r\n\u2193\r\nPermission\r\n\u2193\r\nKonfigurasi API\r\n<\/code><\/pre>\nJika API key tidak valid, melakukan retry dengan request yang sama tidak akan menyelesaikan masalah.<\/p>\n
Perbaiki kredensial atau konfigurasi yang digunakan.<\/p>\n
16. Error 404<\/h2>\n
Jika API mengembalikan 404 Not Found<\/code>, periksa URL endpoint.<\/p>\nContohnya:<\/p>\n
https:\/\/g<\/span>ate.whapi.cloud\/api\/<\/span>sendMessage\r\n<\/code><\/pre>\nberbeda dengan endpoint lain yang tersedia pada dokumentasi versi API yang digunakan.<\/p>\n
Pastikan endpoint yang digunakan benar-benar tersedia.<\/p>\n
Jangan mengubah path endpoint berdasarkan perkiraan.<\/p>\n
17. Error 429 atau Batas Request<\/h2>\n
Jika API atau infrastruktur yang digunakan menerapkan pembatasan request, pengiriman dalam jumlah besar dalam waktu singkat dapat ditolak.<\/p>\n
Contohnya:<\/p>\n
100<\/span> request\r\n \u2193\r\ndikirim <\/span>dalam waktu sangat singkat\r\n \u2193\r\nsebagian <\/span>request ditolak<\/span>\r\n<\/code><\/pre>\nUntuk sistem dengan volume tinggi, gunakan queue dan atur kecepatan pengiriman.<\/p>\n
Contoh:<\/p>\n
Database\r\n \u2193\r\nQueue<\/span>\r\n \u2193\r\nWorker\r\n \u2193\r\nPengiriman bertahap\r\n<\/code><\/pre>\nJangan menjalankan ribuan request secara bersamaan hanya karena aplikasi mampu membuat banyak koneksi.<\/p>\n
18. Pesan Berhasil Diproses tetapi Gagal di Tahap Berikutnya<\/h2>\n
Request API yang berhasil tidak selalu berarti pesan sudah dibaca penerima.<\/p>\n
Contoh:<\/p>\n
HTTP<\/span> request berhasil\r\n<\/span> \u2193\r\nPesan<\/span> diproses\r\n \u2193\r\nStatus<\/span> pesan\r\n \u2193\r\nDELIVERED<\/span> \/ READ \/ FAILED\r\n<\/code><\/pre>\nKarena itu, aplikasi sebaiknya menyimpan identifier pesan dan memproses event status melalui webhook.<\/p>\n
Dengan cara ini, status pesan dapat diperbarui setelah proses pengiriman berlangsung.<\/p>\n
19. Jangan Retry Semua Error<\/h2>\n
Retry berguna untuk error sementara, tetapi tidak semua error perlu dicoba kembali.<\/p>\n
Contoh yang biasanya perlu diperbaiki terlebih dahulu:<\/p>\n
API key salah\r\nParameter<\/span> salah\r\nNomor tidak valid<\/span>\r\nEndpoint salah<\/span>\r\n<\/code><\/pre>\nRetry tidak memperbaiki kesalahan tersebut.<\/p>\n
Sebaliknya, error jaringan sementara dapat diproses dengan retry terbatas.<\/p>\n
Contoh:<\/p>\n
Request\r\n \u2193\r\nGagal sementara\r\n \u2193\r\nTunggu\r\n \u2193\r\nRetry 1<\/span>\r\n \u2193\r\nGagal\r\n \u2193\r\nRetry 2<\/span>\r\n<\/code><\/pre>\nGunakan batas retry agar satu pesan tidak dikirim berulang kali tanpa kontrol.<\/p>\n
20. Gunakan Log untuk Menemukan Penyebab<\/h2>\n
Simpan informasi penting dari setiap proses pengiriman.<\/p>\n
Contoh:<\/p>\n
console.log<\/span>({\r\n phone,\r\n status<\/span>: response.status<\/span>,\r\n body: responseBody\r\n});\r\n<\/code><\/pre>\nJangan mencatat API key atau data sensitif secara lengkap ke log.<\/p>\n
Informasi yang berguna antara lain:<\/p>\n
Waktu request\r\nEndpoint\r\nNomor tujuan\r\nHTTP status<\/span>\r\nResponse API\r\nMessage ID\r\nStatus<\/span> pesan\r\n<\/code><\/pre>\nDengan log tersebut, satu kegagalan dapat ditelusuri dari request sampai status akhirnya.<\/p>\n
Cara Troubleshooting yang Sistematis<\/h2>\n
Ketika pesan gagal terkirim, periksa dengan urutan berikut:<\/p>\n
1.<\/span> Device CONNECTED?\r\n \u2193\r\n2.<\/span> API key<\/span> benar?\r\n \u2193\r\n3.<\/span> Endpoint benar?\r\n \u2193\r\n4.<\/span> Method benar?\r\n \u2193\r\n5.<\/span> Content-Type benar?\r\n \u2193\r\n6.<\/span> Parameter lengkap?\r\n \u2193\r\n7.<\/span> Nomor tujuan benar?\r\n \u2193\r\n8.<\/span> Request berhasil keluar dari server?\r\n \u2193\r\n9.<\/span> HTTP status berapa?\r\n \u2193\r\n10.<\/span> Response API apa?\r\n \u2193\r\n11.<\/span> Message ID tersedia?\r\n \u2193\r\n12.<\/span> Status webhook apa?\r\n<\/code><\/pre>\nUrutan tersebut membantu menentukan apakah masalah berada di aplikasi, jaringan, API, device, atau nomor tujuan.<\/p>\n
Contoh Fungsi Pengiriman dengan Penanganan Error<\/h2>\n
Contoh sederhana menggunakan Node.js:<\/p>\n
async<\/span> function<\/span> sendWhatsAppMessage<\/span>(\r\n apiKey,\r\n phone,\r\n message\r\n<\/span>) <\/span>{\r\n if<\/span> (!apiKey) {\r\n throw<\/span> new<\/span> Error<\/span>('API key tidak tersedia'<\/span>);\r\n }\r\n\r\n if<\/span> (!phone) {\r\n throw<\/span> new<\/span> Error<\/span>('Nomor tujuan tidak tersedia'<\/span>);\r\n }\r\n\r\n if<\/span> (!message || !message.trim()) {\r\n throw<\/span> new<\/span> Error<\/span>('Pesan tidak boleh kosong'<\/span>);\r\n }\r\n\r\n const<\/span> url<\/span> = 'https:\/\/gate.whapi.cloud\/messages\/text'<\/span>;\r\n\r\n const<\/span> body =