Apa Penyebab Pesan WhatsApp Gagal Terkirim dari API?

Oleh /

Pesan 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.

Apa Penyebab Pesan WhatsApp Gagal Terkirim dari API?

Alur pengiriman pesan melalui API secara umum:

Aplikasi
   ↓
Request API
   ↓
API WhatsApp
   ↓
Device WhatsApp
   ↓
Nomor Tujuan
   ↓
Status Pesan
`

Error dapat terjadi pada salah satu tahap tersebut.

1. Device WhatsApp Tidak Terhubung

Device merupakan bagian penting dalam pengiriman pesan melalui WhatsApp API.

Jika device sedang tidak terhubung, request pengiriman dapat gagal atau pesan tidak dapat diproses seperti biasa.

Periksa status device sebelum mencari masalah pada kode.

Contoh kondisi:

Device: CONNECTED

atau:

Device: DISCONNECTED

Jika device terputus, periksa koneksi device terlebih dahulu.

Untuk sistem yang menggunakan banyak device, pastikan API key yang digunakan memang terhubung dengan device yang sedang diperiksa.

2. API Key Salah

API key digunakan untuk mengakses API.

Jika API key salah, tidak valid, atau tidak sesuai dengan konfigurasi device, request tidak dapat diproses.

Contoh konfigurasi:

const payload = {
  apiKey: 'API_KEY_WHAPI',
  phone: '628123456789',
  message: 'Pesan dari API'
};

Jangan menambahkan spasi atau karakter lain ke API key.

Jika API key disimpan pada environment variable, periksa apakah nilai tersebut benar-benar terbaca oleh aplikasi.

Contoh:

const apiKey = process.env.WHAPI_API_KEY;

console.log(
  apiKey ? 'API key tersedia' : 'API key tidak ditemukan'
);

Jangan mencetak API key lengkap ke log production.

3. Nomor Tujuan Tidak Valid

Nomor tujuan merupakan salah satu penyebab umum pesan gagal dikirim.

Periksa:

  • Nomor memiliki kode negara.
  • Tidak ada karakter yang tidak diperlukan.
  • Nomor tidak tertukar dengan nomor lain.
  • Format nomor sesuai dengan format yang diterima API.

Contoh format nomor Indonesia:

628123456789

Bukan:

08123456789

Jika nomor berasal dari form atau database, lakukan validasi sebelum request dikirim.

Contoh:

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

Fungsi tersebut hanya contoh dasar. Aturan normalisasi perlu disesuaikan dengan format nomor yang digunakan sistem.

4. Request Tidak Sesuai Format API

Request API harus mengikuti format endpoint yang digunakan.

Misalnya pengiriman pesan menggunakan:

POST /api/sendMessage

maka method dan parameter harus mengikuti dokumentasi endpoint tersebut.

Contoh request menggunakan PHP:

$data = [
    'apiKey' => $apiKey,
    'phone' => $phone,
    'message' => $message
];

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));

Kesalahan pada nama parameter dapat membuat request gagal.

Contohnya:

phone

berbeda dengan:

phone_number

Jangan mengganti nama parameter berdasarkan asumsi. Gunakan parameter yang tersedia pada endpoint API yang digunakan.

5. Method HTTP Salah

Endpoint pengiriman pesan dapat membutuhkan method tertentu.

Jika endpoint membutuhkan POST tetapi aplikasi mengirim GET, request tidak akan diproses sesuai kebutuhan.

Contoh:

const response = await fetch(url, {
  method: 'POST',
  body: new URLSearchParams({
    apiKey,
    phone,
    message
  })
});

Periksa method, URL, dan body request ketika pengiriman gagal.

6. Content-Type Tidak Sesuai

Selain method, format body request juga perlu sesuai dengan endpoint.

Contohnya, API dapat menerima data dalam format form-encoded.

Pada PHP:

curl_setopt(
    $ch,
    CURLOPT_POSTFIELDS,
    http_build_query($data)
);

Pada Node.js:

const body = new URLSearchParams({
  apiKey,
  phone,
  message
});

Kesalahan Content-Type dapat menyebabkan API tidak membaca parameter yang dikirim.

Jika request menggunakan JSON, tetapi endpoint mengharapkan form data, parameter dapat dianggap tidak tersedia.

7. Pesan Kosong

API membutuhkan isi pesan jika endpoint yang digunakan adalah endpoint pengiriman pesan teks.

Contoh:

const message = '';

if (!message.trim()) {
  throw new Error('Pesan tidak boleh kosong');
}

Masalah ini sering terjadi ketika isi pesan diambil dari database, form, atau template.

Contohnya:

Nama: Budi
Pesan: [kosong]

Sebelum request dikirim, validasi data yang menjadi isi pesan.

8. Data Dinamis Tidak Tersedia

Pesan yang dibuat dari template dapat gagal karena salah satu variabel tidak memiliki nilai.

Contoh:

const message =
  `Halo ${name}, pesanan ${orderNumber} sudah diproses.`;

Jika name atau orderNumber tidak tersedia, pesan yang dikirim dapat menjadi tidak sesuai.

Gunakan validasi:

if (!name || !orderNumber) {
  throw new Error(
    'Data pelanggan atau nomor pesanan tidak tersedia'
  );
}

Validasi sebelum request membantu membedakan error data dengan error API.

9. Nomor Tidak Dapat Menerima Pesan

Format nomor yang benar tidak selalu berarti nomor tersebut dapat menerima pesan.

Nomor dapat sudah tidak aktif atau tidak tersedia pada layanan WhatsApp.

Karena itu, aplikasi tidak sebaiknya menganggap:

Nomor valid
=
Pesan pasti terkirim

Status pengiriman tetap perlu diperiksa dari response dan event yang diterima setelah request.

10. Device Berubah atau Logout

Pada sistem dengan banyak device, device dapat berubah status atau mengalami logout.

Contohnya:

Device 01
CONNECTED

kemudian:

Device 01
DISCONNECTED

Jika aplikasi masih mencoba mengirim menggunakan device tersebut, pengiriman dapat gagal.

Sistem sebaiknya memeriksa status device dan menyediakan monitoring untuk perubahan koneksi.

11. Request Mengalami Timeout

Pengiriman dapat gagal jika aplikasi tidak mendapatkan response dalam waktu yang diharapkan.

Contohnya:

Aplikasi
   ↓
Request API
   ↓
Menunggu
   ↓
Timeout

Periksa:

  • koneksi server;
  • DNS;
  • firewall;
  • koneksi internet;
  • konfigurasi timeout;
  • response API.

Pada aplikasi production, gunakan timeout agar proses tidak menunggu tanpa batas.

Contoh Node.js:

const controller = new AbortController();

const timeout = setTimeout(() => {
  controller.abort();
}, 10000);

try {
  const response = await fetch(url, {
    method: 'POST',
    body,
    signal: controller.signal
  });

  console.log(await response.text());

} finally {
  clearTimeout(timeout);
}

Nilai timeout perlu disesuaikan dengan kebutuhan aplikasi.

12. Server Tidak Dapat Mengakses API

Jika aplikasi berada di server dengan aturan jaringan yang ketat, request keluar dapat diblokir.

Contohnya:

Aplikasi
   ↓
Firewall
   X
API

Periksa konfigurasi firewall dan koneksi keluar dari server.

Masalah ini berbeda dengan error dari API. Jika request tidak pernah keluar dari server, response dari API juga tidak akan diterima.

13. Response API Menunjukkan Error

Jangan hanya memeriksa apakah request menghasilkan exception.

Simpan HTTP status code dan response body.

Contoh:

const response = await fetch(url, {
  method: 'POST',
  body
});

const responseBody = await response.text();

console.log('Status:', response.status);
console.log('Response:', responseBody);

Informasi tersebut membantu membedakan:

Request berhasil

dari:

Request diterima tetapi ditolak

dan:

Request tidak mendapatkan response

Ketiganya membutuhkan pemeriksaan yang berbeda.

14. Error 400 Bad Request

Status 400 biasanya menunjukkan request tidak sesuai dengan data yang dibutuhkan endpoint.

Periksa:

  • Parameter wajib.
  • Nama parameter.
  • Format nomor.
  • Isi pesan.
  • Format body.
  • Method HTTP.

Contoh:

POST /api/sendMessage

tetapi body tidak memiliki parameter yang diwajibkan.

Jangan langsung melakukan retry untuk error seperti ini. Perbaiki request terlebih dahulu.

15. Error 401 atau 403

Status 401 atau 403 berkaitan dengan akses atau autentikasi.

Periksa:

API key
↓
Device
↓
Permission
↓
Konfigurasi API

Jika API key tidak valid, melakukan retry dengan request yang sama tidak akan menyelesaikan masalah.

Perbaiki kredensial atau konfigurasi yang digunakan.

16. Error 404

Jika API mengembalikan 404 Not Found, periksa URL endpoint.

Contohnya:

https://gate.whapi.cloud/api/sendMessage

berbeda dengan endpoint lain yang tersedia pada dokumentasi versi API yang digunakan.

Pastikan endpoint yang digunakan benar-benar tersedia.

Jangan mengubah path endpoint berdasarkan perkiraan.

17. Error 429 atau Batas Request

Jika API atau infrastruktur yang digunakan menerapkan pembatasan request, pengiriman dalam jumlah besar dalam waktu singkat dapat ditolak.

Contohnya:

100 request
   ↓
dikirim dalam waktu sangat singkat
   ↓
sebagian request ditolak

Untuk sistem dengan volume tinggi, gunakan queue dan atur kecepatan pengiriman.

Contoh:

Database
   ↓
Queue
   ↓
Worker
   ↓
Pengiriman bertahap

Jangan menjalankan ribuan request secara bersamaan hanya karena aplikasi mampu membuat banyak koneksi.

18. Pesan Berhasil Diproses tetapi Gagal di Tahap Berikutnya

Request API yang berhasil tidak selalu berarti pesan sudah dibaca penerima.

Contoh:

HTTP request berhasil
        ↓
Pesan diproses
        ↓
Status pesan
        ↓
DELIVERED / READ / FAILED

Karena itu, aplikasi sebaiknya menyimpan identifier pesan dan memproses event status melalui webhook.

Dengan cara ini, status pesan dapat diperbarui setelah proses pengiriman berlangsung.

19. Jangan Retry Semua Error

Retry berguna untuk error sementara, tetapi tidak semua error perlu dicoba kembali.

Contoh yang biasanya perlu diperbaiki terlebih dahulu:

API key salah
Parameter salah
Nomor tidak valid
Endpoint salah

Retry tidak memperbaiki kesalahan tersebut.

Sebaliknya, error jaringan sementara dapat diproses dengan retry terbatas.

Contoh:

Request
   ↓
Gagal sementara
   ↓
Tunggu
   ↓
Retry 1
   ↓
Gagal
   ↓
Retry 2

Gunakan batas retry agar satu pesan tidak dikirim berulang kali tanpa kontrol.

20. Gunakan Log untuk Menemukan Penyebab

Simpan informasi penting dari setiap proses pengiriman.

Contoh:

console.log({
  phone,
  status: response.status,
  body: responseBody
});

Jangan mencatat API key atau data sensitif secara lengkap ke log.

Informasi yang berguna antara lain:

Waktu request
Endpoint
Nomor tujuan
HTTP status
Response API
Message ID
Status pesan

Dengan log tersebut, satu kegagalan dapat ditelusuri dari request sampai status akhirnya.

Cara Troubleshooting yang Sistematis

Ketika pesan gagal terkirim, periksa dengan urutan berikut:

1. Device CONNECTED?
        ↓
2. API key benar?
        ↓
3. Endpoint benar?
        ↓
4. Method benar?
        ↓
5. Content-Type benar?
        ↓
6. Parameter lengkap?
        ↓
7. Nomor tujuan benar?
        ↓
8. Request berhasil keluar dari server?
        ↓
9. HTTP status berapa?
        ↓
10. Response API apa?
        ↓
11. Message ID tersedia?
        ↓
12. Status webhook apa?

Urutan tersebut membantu menentukan apakah masalah berada di aplikasi, jaringan, API, device, atau nomor tujuan.

Contoh Fungsi Pengiriman dengan Penanganan Error

Contoh sederhana menggunakan Node.js:

async function sendWhatsAppMessage(
  apiKey,
  phone,
  message
) {
  if (!apiKey) {
    throw new Error('API key tidak tersedia');
  }

  if (!phone) {
    throw new Error('Nomor tujuan tidak tersedia');
  }

  if (!message || !message.trim()) {
    throw new Error('Pesan tidak boleh kosong');
  }

  const url = 'https://gate.whapi.cloud/messages/text';

  const body = new URLSearchParams({
    apiKey,
    phone,
    message
  });

  try {
    const response = await fetch(url, {
      method: 'POST',
      body
    });

    const responseBody = await response.text();

    if (!response.ok) {
      throw new Error(
        `API error ${response.status}: ${responseBody}`
      );
    }

    return JSON.parse(responseBody);

  } catch (error) {
    console.error(
      'Pengiriman WhatsApp gagal:',
      error.message
    );

    throw error;
  }
}

Fungsi tersebut melakukan validasi sebelum request dikirim dan memeriksa response setelah request selesai.

Struktur ini dapat dikembangkan dengan logging, retry terbatas, queue, dan penyimpanan status pesan.

Hubungkan Pengiriman dengan Webhook

Setelah request pengiriman berhasil, simpan identifier pesan yang diberikan API.

Kemudian gunakan webhook untuk menerima perubahan status.

Alurnya:

Aplikasi
   ↓
Kirim pesan
   ↓
Simpan message ID
   ↓
Webhook
   ↓
Terima status
   ↓
Update database

Dokumentasi endpoint pengiriman pesan dapat dilihat di:

Dokumentasi API Pengiriman Pesan Whapi

Dengan cara ini, sistem tidak hanya mengetahui apakah request berhasil, tetapi juga dapat mengikuti status pesan setelah request dikirim.

Kesimpulan

Pesan WhatsApp yang gagal terkirim dari API dapat disebabkan oleh berbagai hal, mulai dari device yang terputus sampai request yang tidak sesuai format.

Pemeriksaan utama meliputi:

  • Status device.
  • API key.
  • Endpoint.
  • HTTP method.
  • Content-Type.
  • Parameter request.
  • Nomor tujuan.
  • Isi pesan.
  • Koneksi server.
  • HTTP status.
  • Response API.
  • Status pesan melalui webhook.

Jangan langsung melakukan retry ketika pengiriman gagal. Periksa response API terlebih dahulu untuk mengetahui jenis error. Error pada API key, parameter, endpoint, atau nomor tujuan harus diperbaiki, sedangkan error jaringan sementara dapat ditangani dengan retry terbatas.

Untuk sistem production, simpan message ID setelah pengiriman dan gunakan webhook untuk menerima perubahan status pesan. Dengan cara ini, proses pengiriman dapat ditelusuri dari request awal sampai status akhirnya.

Artikel Populer

Scroll to Top