Cara Kirim Pesan WhatsApp lewat API (Official WABA)

Tim yang masih membalas pelanggan satu per satu lewat ponsel akan kewalahan begitu chat masuk ratusan sehari. Sekarang kita akan bahas cara kirim pesan WhatsApp lewat API memindahkan pekerjaan melelahkan itu ke sistemmu: satu panggilan ke gateway resmi, dan pesan langsung sampai ke ponsel pelanggan beserta bukti terkirim. Panduan ini menunjukkan endpoint, header, dan body yang kamu perlukan.

Cara kirim pesan WhatsApp lewat API: siapkan nomor dan API key dulu

Pengiriman berjalan di atas WhatsApp Business API resmi dari api.co.id, jadi nomor bisnismu harus sudah terdaftar di WABA sebelum kamu memakainya. Pastikan nomormu sudah terhubung ke dashboard lebih dulu, karena langkah onboarding-nya ada di panduan tersendiri. Setelah nomor aktif, salin API key dari dashboard lalu simpan sebagai variabel env supaya aman.

Satu hal yang sering bikin bingung: gateway WhatsApp ini punya API key sendiri. Key-nya berbeda dari yang kamu pakai untuk API api.co.id lain seperti cek ongkir atau OCR KTP, dan dikirim lewat header Authorization: Bearer ke base URL https://chat.api.co.id. Jadi ambil key-nya dari dashboard WhatsApp, meskipun kamu sudah punya key untuk produk api.co.id yang lain.

Contoh request kirim pesan teks

Begitu key siap, cara kirim pesan WhatsApp lewat API hanya butuh satu panggilan POST seperti contoh di bawah. Ganti YOUR_API_KEY dengan key milikmu dan 62812xxxxxxx dengan nomor penerima.

curl -X POST https://chat.api.co.id/api/v1/public/messages/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "62812xxxxxxx",
    "channel": "whatsapp",
    "message_type": "text",
    "content": "Halo! Ini pesan uji dari API."
  }'

Header dan parameter body

Request butuh dua header wajib. Header Authorization membawa autentikasi, sedangkan Content-Type: application/json menandai body berformat JSON. Isi body mengikuti tabel berikut.

Parameter	Wajib/Opsional	Tipe	Keterangan
phone_number	Wajib salah satu	string	Nomor penerima, format internasional diawali 62 tanpa tanda plus. Isi salah satu dari phone_number atau customer_id
customer_id	Wajib salah satu	string	ID pelanggan yang sudah tersimpan di akunmu, dipakai sebagai alternatif phone_number untuk mengirim ke kontak yang sudah ada
channel	Wajib	enum	whatsapp, instagram, atau messenger
message_type	Wajib	string	Untuk WhatsApp: text, image, document, audio, video, template, interactive
content	Opsional	string	Isi teks pesan, wajib saat message_type bernilai text. Maksimal 4096 karakter untuk WhatsApp
whatsapp_phone_number_id	Opsional	string	Memilih nomor pengirim kalau punya lebih dari satu nomor terhubung. Tanpa field ini gateway memakai nomor bawaan akun
media_url	Opsional	string (URL)	Wajib untuk image, document, audio, dan video
caption	Opsional	string	Teks pendamping untuk media visual maupun dokumen
filename	Opsional	string	Nama file saat mengirim document
reply_to_message_id	Opsional	string	Membalas pesan tertentu dalam percakapan

Respons yang kamu terima

Kalau request berhasil, gateway membalas dengan envelope success dan objek data:

{
  "success": true,
  "data": {
    "message_id": "clzr8k2p70001qa3b9f4d2x6m",
    "customer_id": "clzr7w9c10001qa3b2h8n4k1e",
    "customer_created": false,
    "whatsapp_phone_number_id": "clzp3t5a90001qa3b7d2m5k9f",
    "status": "sent",
    "channel": "whatsapp",
    "timestamp": "2026-10-07T04:15:32.871Z"
  }
}

Nilai status "sent" berarti pesan sudah diterima gateway. Status terkirim dan terbaca menyusul lewat webhook, jadi simpan message_id supaya kamu bisa mencocokkan update itu nanti. Sementara itu, field timestamp mencatat kapan gateway menerima pesan.

Kirim gambar, dokumen, dan media

Untuk gambar dan dokumen, bentuk request-nya tidak berubah, cukup ganti message_type ke tipe medianya lalu isi media_url dengan URL file yang bisa diakses publik. Misalnya, satu invoice PDF dikirim dengan message_type document, media_url yang menunjuk ke file-nya, dan filename seperti invoice-0921.pdf.

Kenapa pesan gagal terkirim

Kamu hanya bisa mengirim pesan non-template ke kontak yang sudah ada di akunmu. Kalau nomor tujuan belum pernah berinteraksi, gateway membalas bahwa kontaknya belum ada dan menyarankan kamu memakai message_type: "template", yang otomatis membuat kontak baru. Aturan ini mengikuti jendela layanan 24 jam dari Meta. Di luar 24 jam sejak pesan terakhir pelanggan, kamu hanya boleh mengirim template yang sudah lolos persetujuan Meta. Detail kategori percakapan ada di dokumentasi tipe percakapan Meta.

Error lain yang sering muncul:

• Teks lebih dari 4096 karakter. Gateway menolaknya dengan pesan bahwa content melebihi batas maksimum untuk WhatsApp.
• HTTP 401 berarti autentikasi gagal. Tanpa header, pesannya “API key required. Provide Bearer token in Authorization header.” Kalau format header salah, muncul “Invalid authorization format. Use: Bearer <api_key>”.
• HTTP 429 muncul setelah 10 kali gagal autentikasi beruntun dalam 5 menit. Gateway memblokir IP-mu selama 15 menit dan menyertakan header Retry-After pada respons.

Kasus lanjutan: kirim OTP dan broadcast

Pengiriman kode OTP tetap lewat endpoint /messages/send yang sama, hanya saja wajib memakai template yang sudah disetujui Meta, dan alur lengkapnya ada di panduan mengirim kode OTP. Untuk menjangkau banyak nomor sekaligus, api.co.id menyediakan endpoint terpisah, POST /api/v1/public/broadcast/send.

WhatsApp API resmi vs jalur tidak resmi

api.co.id mengirim pesan lewat WhatsApp Cloud API resmi milik Meta, jadi payload dan aturannya mengikuti acuan di panduan kirim pesan Cloud API. Banyak gateway lain menumpang aplikasi WhatsApp biasa lewat jalur tidak resmi. Cara itu memang lebih murah di awal, tetapi Meta bisa memblokir nomornya secara permanen dan pesannya tidak punya jaminan pengiriman.

Pertanyaan umum

Apa beda link wa.me dengan kirim lewat API?

Link wa.me hanya membuka jendela chat di perangkat pengguna lalu menunggu orang menekan tombol kirim. Dengan cara kirim pesan WhatsApp lewat API, server mengirim pesan langsung ke nomor tujuan tanpa ada yang menekan tombol, kemudian mengembalikan message_id yang bisa kamu lacak.

Apakah endpoint ini hanya untuk WhatsApp?

Endpoint yang sama menerima channel lain. Jadi, isi field channel dengan instagram atau messenger untuk mengirim ke platform itu. Panduan ini fokus ke WhatsApp, tetapi body request-nya mengikuti pola yang sama.