Cara Mengatasi Pesan WhatsApp Gagal Terkirim

Oleh /

Pesan WhatsApp yang gagal terkirim dari API dapat disebabkan oleh masalah pada koneksi device, request API, nomor tujuan, konfigurasi server, atau proses pengiriman. Cara Mengatasi Pesan WhatsApp Gagal Terkirim sebaiknya dilakukan secara berurutan agar masalah dapat ditemukan tanpa mengubah banyak konfigurasi sekaligus.

Artikel ini membahas langkah troubleshooting ketika sistem sudah memiliki fungsi pengiriman WhatsApp, tetapi pesan tidak sampai ke penerima.

Cara Mengatasi Pesan WhatsApp Gagal Terkirim

1. Pastikan Device WhatsApp Sudah Terhubung

Langkah pertama adalah memeriksa status device yang digunakan untuk mengirim pesan.

API membutuhkan device yang aktif dan terhubung sebelum pesan dapat dikirim. Jika device sedang terputus, request pengiriman tidak dapat diproses secara normal.

Periksa status device melalui dashboard atau API status perangkat.

Whapi menyediakan endpoint untuk mengambil status koneksi perangkat. Status CONNECTED menunjukkan device aktif dan siap digunakan untuk mengirim atau menerima pesan. :contentReference[oaicite:0]{index=0}

Jika status menunjukkan kondisi seperti SERVICE_OFF, SERVICE_SCAN, atau PAIRING, selesaikan proses koneksi terlebih dahulu.

Urutan pengecekan:

  1. Pastikan service device aktif.
  2. Pastikan nomor WhatsApp sudah terhubung.
  3. Pastikan status berubah menjadi CONNECTED.
  4. Setelah itu, lakukan pengiriman pesan kembali.

Jika device sering berubah menjadi terputus, masalahnya perlu diperiksa sebagai masalah koneksi device, bukan sekadar error pada request pengiriman.

2. Coba Kirim Pesan dari Dashboard

Sebelum memeriksa kode aplikasi, lakukan pengujian langsung dari dashboard.

Tujuannya untuk memisahkan masalah antara:

  • device WhatsApp,
  • konfigurasi API,
  • dan kode aplikasi sendiri.

Jika pesan dari dashboard berhasil tetapi pesan dari aplikasi gagal, kemungkinan masalah berada pada request yang dikirim aplikasi.

Sebaliknya, jika pengiriman dari dashboard juga gagal, pemeriksaan sebaiknya dimulai dari status device dan konfigurasi layanan.

Cara ini lebih cepat daripada langsung mengubah kode backend.

3. Periksa API Key

API Key digunakan untuk mengidentifikasi device yang digunakan dalam request.

Pastikan API Key yang dikirim oleh aplikasi:

  • berasal dari device yang benar,
  • masih aktif,
  • tidak tertukar dengan device lain,
  • tidak memiliki spasi tambahan,
  • dan benar-benar dikirim dalam request.

Simpan API Key sebagai konfigurasi server, bukan ditulis berulang kali di banyak bagian kode.

Contoh konfigurasi:

WHAPI_API_KEY=API_KEY_DEVICE
`

Kemudian gunakan konfigurasi tersebut saat melakukan request.

const apiKey = process.env.WHAPI_API_KEY;

Jika API Key yang digunakan berbeda dengan device yang diperiksa di dashboard, proses troubleshooting bisa menghasilkan kesimpulan yang salah.

4. Periksa Nomor Tujuan

Nomor tujuan juga perlu diperiksa sebelum mengubah kode pengiriman.

Pastikan nomor:

  • menggunakan format yang sesuai,
  • tidak memiliki karakter tambahan,
  • tidak menggunakan format nomor lokal yang salah,
  • dan merupakan nomor WhatsApp yang valid.

Contoh format nomor:

6281234567890

Hindari format seperti:

081234567890
+6281234567890
62812-3456-7890

Jika sistem menerima nomor dari database atau form pengguna, lakukan normalisasi sebelum nomor dikirim ke API.

Contoh sederhana:

function normalizePhone(phone) {
    return phone
        .replace(/\D/g, '')
        .replace(/^0/, '62');
}

Namun normalisasi harus disesuaikan dengan format nomor yang digunakan sistem. Jangan mengubah nomor secara otomatis jika sistem sudah menyimpan format internasional.

5. Periksa HTTP Method dan Request Body

Kesalahan pengiriman sering berasal dari request yang tidak sesuai dengan endpoint.

Periksa:

  • HTTP method,
  • URL endpoint,
  • Content-Type,
  • API Key,
  • nomor tujuan,
  • isi pesan,
  • dan parameter tambahan.

Whapi menyediakan Dokumentasi pengiriman pesan Whapi untuk endpoint pengiriman pesan. Gunakan dokumentasi tersebut sebagai acuan ketika memeriksa request.

Contoh request menggunakan application/x-www-form-urlencoded:

const params = new URLSearchParams();

params.append('apiKey', process.env.WHAPI_API_KEY);
params.append('phone', '6281234567890');
params.append('message', 'Pesan percobaan dari API');

const response = await fetch('ENDPOINT_PENGIRIMAN', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: params
});

const result = await response.json();

console.log(result);

Jangan langsung menyimpulkan device bermasalah sebelum memastikan request yang dikirim aplikasi memang sesuai dengan endpoint.

6. Tampilkan Response API di Log

Jangan hanya mencatat bahwa request gagal.

Simpan response dari API agar dapat diketahui bagian mana yang bermasalah.

Contoh:

try {
    const response = await fetch(url, options);
    const result = await response.json();

    console.log('HTTP Status:', response.status);
    console.log('API Response:', result);
} catch (error) {
    console.error('Request Error:', error);
}

Informasi yang sebaiknya dicatat:

Waktu request
Device
Nomor tujuan
HTTP status
Response API
ID pesan jika tersedia
Error dari client

Jangan mencatat API Key secara penuh ke log produksi.

Jika response memberikan informasi kesalahan, gunakan informasi tersebut sebagai dasar perbaikan. Hindari langsung melakukan retry tanpa mengetahui apakah error tersebut dapat dicoba kembali.

7. Bedakan Error Request dan Pesan Gagal Terkirim

Ada dua kondisi yang sering dianggap sama.

Request API gagal

Aplikasi tidak berhasil melakukan request atau API mengembalikan error.

Contohnya:

HTTP 400
HTTP 401
HTTP 403
HTTP 404
HTTP 429

Masalah pada kondisi ini perlu diperiksa dari request, autentikasi, endpoint, konfigurasi, atau batas penggunaan.

Request berhasil tetapi pesan gagal

Pada kondisi lain, API dapat menerima request dan menghasilkan ID pesan, tetapi proses pengiriman berikutnya gagal.

Karena itu, status HTTP response tidak selalu cukup untuk menentukan apakah pesan benar-benar sampai ke penerima.

Untuk kasus ini, gunakan webhook atau status pesan untuk memantau proses setelah request dikirim.

Whapi menyediakan event message_ack untuk perubahan status pesan seperti sent, delivered, read, dan faileddihalaman WHAPI Documentation untuk Integrasi Notifikasi Webhook

8. Gunakan ID Pesan untuk Melacak Pengiriman

Jika response pengiriman menghasilkan ID pesan, simpan ID tersebut di database.

Contoh struktur sederhana:

messages
├── id
├── phone
├── message
├── id_message
├── status
├── created_at
└── updated_at

Saat request berhasil dibuat:

status = queued

Kemudian status dapat diperbarui berdasarkan event yang diterima dari webhook:

queued
↓
sent
↓
delivered
↓
read

Jika pengiriman gagal:

queued
↓
failed

Dengan cara ini, sistem tidak hanya mengetahui bahwa request API pernah dilakukan, tetapi juga dapat mengetahui perkembangan pengiriman pesan.

9. Periksa Webhook Status Pesan

Webhook berguna untuk mengetahui perubahan status pesan setelah proses pengiriman dimulai.

Pastikan webhook:

  1. Menggunakan URL yang dapat diakses server.
  2. Menerima HTTP POST.
  3. Membaca payload dengan benar.
  4. Mengaktifkan event status pesan.
  5. Mengembalikan HTTP 200 setelah menerima data.

Whapi menyediakan event message_ack untuk status pesan dan change_state untuk perubahan koneksi device.

Contoh receiver sederhana:

app.post('/webhook/whapi', (req, res) => {
    const payload = req.body;

    console.log('Webhook:', payload);

    // Simpan atau proses status pesan di sini

    res.sendStatus(200);
});

Jangan menunggu seluruh proses bisnis selesai sebelum memberikan response kepada webhook jika proses tersebut membutuhkan waktu lama.

Simpan event terlebih dahulu, berikan response yang sesuai, kemudian proses data melalui worker atau queue jika diperlukan.

10. Jangan Langsung Retry Semua Pesan

Retry dapat membantu ketika terjadi gangguan sementara, tetapi retry tanpa aturan dapat membuat masalah semakin besar.

Misalnya, sistem mengirim pesan berkali-kali karena tidak membedakan antara:

  • request timeout,
  • API error,
  • device offline,
  • nomor tidak valid,
  • dan pesan yang sebenarnya sudah diterima.

Gunakan retry hanya untuk kondisi yang memang dapat dicoba kembali.

Contoh sederhana:

const maxRetry = 3;

for (let attempt = 1; attempt <= maxRetry; attempt++) {
    try {
        const response = await sendMessage();

        if (response.ok) {
            break;
        }
    } catch (error) {
        if (attempt === maxRetry) {
            throw error;
        }
    }
}

Untuk sistem produksi, retry sebaiknya menggunakan jeda antarpercobaan dan pencatatan status agar pesan tidak terkirim berulang kali.

11. Periksa Timeout dan Koneksi Server

Request dapat gagal bukan karena WhatsApp, tetapi karena server aplikasi tidak berhasil menyelesaikan komunikasi dengan API.

Periksa:

  • koneksi internet server,
  • DNS,
  • firewall,
  • outbound connection,
  • timeout HTTP client,
  • proxy,
  • dan konfigurasi SSL.

Jika request membutuhkan waktu terlalu lama, aplikasi dapat menganggap request gagal meskipun proses di sisi API masih berjalan.

Karena itu, status request dan status pesan perlu disimpan secara terpisah.

Contoh:

API request
   ↓
accepted
   ↓
message ID
   ↓
message status
   ↓
delivered / read / failed

Struktur ini membuat sistem lebih mudah membedakan error komunikasi dengan status pengiriman pesan.

12. Periksa Isi Pesan Dinamis

Pesan yang dibuat dari template atau database juga dapat menyebabkan masalah.

Contoh:

const message = `Halo ${customer.name}, pesanan ${order.id} sudah diproses.`;

Jika customer.name atau order.id tidak tersedia, hasilnya dapat menjadi:

Halo undefined, pesanan undefined sudah diproses.

Karena itu, validasi data sebelum request.

if (!customer?.name || !order?.id) {
    throw new Error('Data pesan tidak lengkap');
}

Untuk sistem notifikasi transaksi, validasi sebaiknya dilakukan sebelum pesan dimasukkan ke antrean pengiriman.

13. Cek Apakah Device Logout Setelah Pesan Gagal

Jika sebelumnya pengiriman berjalan normal kemudian semua pesan mulai gagal, periksa status device.

Jangan hanya memeriksa kode aplikasi.

Device yang kehilangan koneksi dapat membuat seluruh request berikutnya gagal meskipun kode pengiriman tidak berubah.

Status device dapat diperiksa melalui endpoint status koneksi atau webhook perubahan koneksi. Whapi menyediakan status seperti CONNECTED, SERVICE_OFF, SERVICE_SCAN, dan PAIRING.

Jika masalah terjadi berulang setelah device kembali terhubung, lanjutkan pemeriksaan pada log device dan waktu terjadinya disconnect.

14. Gunakan Urutan Troubleshooting yang Konsisten

Agar pemeriksaan tidak berputar-putar, gunakan urutan berikut:

1. Cek status device
       ↓
2. Tes kirim dari dashboard
       ↓
3. Cek API Key
       ↓
4. Cek nomor tujuan
       ↓
5. Cek endpoint dan HTTP method
       ↓
6. Cek Content-Type dan request body
       ↓
7. Cek HTTP response
       ↓
8. Simpan ID pesan
       ↓
9. Cek status melalui webhook
       ↓
10. Cek retry dan timeout
       ↓
11. Periksa log server

Urutan ini membantu menentukan lokasi masalah sebelum perubahan kode dilakukan.

15. Buat Log Pengiriman yang Mudah Dicari

Untuk aplikasi yang mengirim banyak pesan, log sederhana seperti:

Pesan gagal dikirim

tidak cukup.

Gunakan informasi seperti:

{
    "phone": "6281234567890",
    "message_id": "MESSAGE_ID",
    "status": "failed",
    "http_status": 400,
    "created_at": "2026-10-04T10:30:00+07:00"
}

Dengan data tersebut, satu pesan dapat dilacak dari request awal sampai status akhirnya.

Untuk volume tinggi, simpan log pengiriman ke database atau sistem logging terpusat daripada hanya mengandalkan file log server.

16. Buat Status Pengiriman di Database

Sistem produksi sebaiknya tidak hanya memiliki status:

success
failed

Gunakan status yang menggambarkan proses secara lebih jelas.

Contoh:

pending
sending
sent
delivered
read
failed

Contohnya:

pending
   ↓
sending
   ↓
sent
   ↓
delivered
   ↓
read

Jika terjadi kegagalan:

sending
   ↓
failed

Status ini dapat digunakan untuk dashboard, laporan transaksi, retry, dan pemeriksaan pesan secara individual.

17. Kapan Pesan Perlu Dikirim Ulang?

Pesan tidak selalu perlu dikirim ulang ketika statusnya gagal.

Sebelum retry, periksa:

  • apakah device sudah CONNECTED,
  • apakah error bersifat sementara,
  • apakah request sebelumnya sudah menghasilkan ID pesan,
  • apakah status akhir sudah diterima melalui webhook,
  • dan apakah retry dapat menyebabkan pesan ganda.

Untuk notifikasi transaksi, duplikasi pesan dapat lebih bermasalah daripada pesan yang terlambat.

Gunakan ID transaksi atau ID pesan sebagai acuan untuk mencegah pengiriman yang sama diproses berkali-kali.

Contoh:

order_id = INV-2026-00125

Jika sudah pernah dikirim:
jangan kirim ulang secara otomatis.

18. Checklist Sebelum Mengubah Kode

Ketika pesan WhatsApp gagal terkirim, periksa checklist berikut:

  • [ ] Device berstatus CONNECTED
  • [ ] Pengiriman dari dashboard berhasil
  • [ ] API Key sesuai dengan device
  • [ ] Nomor tujuan sudah dinormalisasi
  • [ ] Endpoint benar
  • [ ] HTTP method benar
  • [ ] Content-Type sesuai
  • [ ] Request body lengkap
  • [ ] HTTP response sudah dicatat
  • [ ] ID pesan disimpan
  • [ ] Webhook status aktif
  • [ ] Event message_ack diterima
  • [ ] Timeout tidak terlalu pendek
  • [ ] Retry tidak menyebabkan duplikasi
  • [ ] Log server dapat ditelusuri

Jika semua pemeriksaan tersebut sudah dilakukan, lokasi masalah biasanya dapat dipersempit ke device, request aplikasi, koneksi server, atau proses pengiriman setelah request diterima.

Kesimpulan

Cara mengatasi pesan WhatsApp gagal terkirim dari API sebaiknya dimulai dari pemeriksaan device, kemudian request API, response, dan status pesan.

Jangan hanya melihat apakah HTTP request berhasil. Sistem pengiriman yang baik perlu membedakan antara request diterima API dan pesan benar-benar berhasil dikirim.

Dengan menyimpan ID pesan, memantau message_ack melalui webhook, mencatat error, dan menerapkan retry secara terkontrol, proses pengiriman WhatsApp menjadi lebih mudah dipantau dan diperbaiki ketika terjadi kegagalan.

Untuk masalah yang lebih spesifik, seperti pesan gagal karena device sering terputus atau logout, pemeriksaan perlu dilanjutkan pada sisi koneksi device.

Artikel Populer

Scroll to Top