Kirim Pesan
Kirim teks, media, tombol, list, carousel, reaksi, dan pesan template lewat API.
Semua cara mengirim pesan WhatsApp lewat API ada di halaman ini: teks dan media, pesan interaktif (tombol, list, carousel), reaksi, tanda dibaca, indikator mengetik, dan pesan dari template.
Pembaruan 9 Oktober 2026: semua endpoint kirim menerima ref_id dan expires_in, dan respons membawa tracking_id untuk Cek Status Pesan. Bila perangkat terputus, pesan kini ditahan sampai expires_in (sebelumnya gagal setelah ±90 detik). Template bertombol, list, dan carousel kini terkirim lengkap dengan tombol dan kartunya.
Dasar
Base URL https://dash.ngirimwa.com/api/v1
x-api-key: API_KEY_ANDA
Content-Type: application/json
Idempotency-Key: <uuid-unik-per-request> (opsional, sangat disarankan)Idempotency-Key mencegah pesan terkirim dua kali saat request diulang. Lihat Autentikasi.
Field umum
Berlaku untuk semua endpoint kirim (teks, media, interaktif, template):
| Field | Tipe | Wajib | Keterangan |
|---|---|---|---|
to | string | ✅ | Nomor tujuan atau ID grup, lihat format nomor |
ref_id | string | ❌ | ID milik Anda, mis. nomor tagihan. 1–100 karakter ASCII, tidak harus unik |
expires_in | integer | ❌ | Batas waktu kirim dalam detik, 30–86400. Default 3600 (1 jam) |
Respons
{
"success": true,
"message": "Message queued for delivery",
"data": {
"job_id": "61503",
"status": "queued",
"tracking_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx1",
"ref_id": "INV-2026-0042",
"expires_at": "2026-10-09T11:00:00.000Z"
}
}| Field | Arti |
|---|---|
tracking_id | ID untuk melacak pesan. Simpan untuk Cek Status Pesan; ikut di setiap webhook message.* |
ref_id | ref_id yang Anda kirim, atau null |
expires_at | Batas waktu pesan boleh dikirim |
status | queued: pesan diterima dan masuk antrean |
job_id | ID antrean untuk support. Jangan dipakai untuk melacak, pakai tracking_id |
200 berarti pesan diterima, belum berarti sampai. Hasil akhirnya (sent → delivered → read, atau failed) dicek lewat Cek Status Pesan atau webhook.
Bila sesi perangkat di NgirimWA terputus (gangguan jaringan, pemeliharaan server), pesan ditahan dan dicoba lagi sampai expires_at, lalu gagal dengan kode expired. HP Anda mati tidak membuat pesan tertahan: nomor terhubung sebagai perangkat tertaut. Bila sesi perangkat sudah berakhir dan perlu scan QR, request langsung ditolak dengan device_logged_out. Daftar lengkap: Penanganan Error.
Format nomor
| Format | Contoh | Dikirim ke |
|---|---|---|
| Internasional (disarankan) | 628123456789 | 628123456789 |
| Lokal Indonesia | 08123456789 | 628123456789 |
| Tanpa awalan | 8123456789 | 628123456789 |
| Negara lain | 60123456789, 14155551234 | apa adanya (wajib dengan kode negara) |
| Grup WhatsApp | 120363123456789012@g.us | grup |
Panjang 8–15 digit. Karakter +, -, dan spasi dibersihkan otomatis.
Pesan Teks & Media
POST /messages/sendTeks
{
"to": "628123456789",
"message": "Tagihan INV-2026-0042 sebesar Rp150.000 jatuh tempo hari ini.",
"ref_id": "INV-2026-0042",
"expires_in": 3600
}Media
Isi media dengan URL HTTPS publik atau data-URI base64, lalu tentukan media_type. message menjadi caption.
{
"to": "628123456789",
"media": "https://domain-anda.com/files/invoice.pdf",
"media_type": "document",
"file_name": "Invoice_Oktober.pdf",
"message": "Berikut invoice pesanan Anda"
}| Field | Tipe | Wajib | Keterangan |
|---|---|---|---|
message | string | ✅ untuk teks | Isi pesan, atau caption bila ada media |
media | string | ✅ untuk media | URL HTTPS publik atau data:image/jpeg;base64,... |
media_type | string | ✅ untuk media | image, video, audio, document. Tanpa ini media diabaikan |
file_name | string | ❌ | Nama file dokumen |
reply_to | object | ❌ | Balas dengan mengutip pesan masuk: { "remote_jid": "628222222222@s.whatsapp.net", "message_id": "3EB0C12345ABCDEF" }. message_id = message.id dari webhook message.received; grup: remote_jid = metadata.group_id. Bisa dipakai 24 jam sejak pesan masuk. Lewat dari itu, pesan tetap terkirim tanpa kutipan |
humanlike | object | ❌ | Tampilkan "sedang mengetik…" dulu, baru kirim. Tanpa field ini pesan langsung dikirim. { "enabled": true, "typing_duration": "auto" }: auto menyesuaikan panjang pesan, atau isi milidetik (500–3000). Pesan terkirim ±1–4,5 detik lebih lambat |
| Tipe | Format | Maks. ukuran |
|---|---|---|
| image | JPG, PNG, GIF | 16 MB |
| video | MP4, AVI, MOV | 64 MB |
| audio | MP3, OGG (Opus), M4A/AAC | 16 MB |
| document | PDF, DOC, DOCX, XLS, XLSX | 100 MB |
- Body request maksimal 25 MB (cukup untuk base64 sampai ±16 MB). Untuk video dan dokumen besar, kirim lewat URL.
- URL yang tidak bisa diunduh dalam 30 detik ditolak dengan
media_download_failed. - Audio diterima sebagai file audio, bukan voice note. Konversi WAV dari text-to-speech ke MP3/OGG dulu.
- Panjang teks: ±4.096 karakter, caption ±1.024 karakter. Teks yang lebih panjang tetap terkirim, tapi bisa terpotong di layar penerima.
curl -X POST https://dash.ngirimwa.com/api/v1/messages/send \
-H "x-api-key: API_KEY_ANDA" \
-H "Content-Type: application/json" \
-d '{ "to": "628123456789", "message": "Halo dari NgirimWA!", "ref_id": "TES-001" }'Pesan Interaktif
Batas dari WhatsApp:
| Komponen | Batas |
|---|---|
| Tombol per pesan / per kartu | 3 |
| Kartu carousel | 10 |
| Section list / baris per section | 10 / 10 |
| Teks tombol | ±20 karakter |
| Judul, footer | ±60 karakter |
| Judul / deskripsi baris list | ±24 / ±72 karakter |
Footer hanya tampil pada pesan yang punya tombol. Saat penerima menekan tombol atau memilih baris list, jawabannya masuk ke webhook message.received dengan info.button_id atau info.row_id.
Pesan dengan tombol
POST /messages/quick-replySatu endpoint untuk empat jenis tombol, boleh dicampur:
{
"to": "628123456789",
"title": "Konfirmasi Pesanan",
"text": "Pesanan ORD-12345 sudah kami siapkan.",
"footer": "Toko XYZ",
"image": { "url": "https://domain-anda.com/banner.jpg" },
"buttons": [
{ "kind": "reply", "text": "Konfirmasi", "id": "confirm_12345" },
{ "kind": "url", "text": "Lihat invoice", "url": "https://domain-anda.com/inv/12345" },
{ "kind": "copy", "text": "Salin kode", "code": "PROMO20" }
]
}| Field | Tipe | Wajib | Keterangan |
|---|---|---|---|
text | string | ✅ | Isi pesan |
buttons | array | ✅ | 1–3 tombol |
title, subtitle, footer | string | ❌ | Judul, sub-judul, footer |
image | object | ❌ | { "url": "..." } atau { "base64": "...", "mimeType": "image/jpeg" } |
kind | Field tambahan | Saat ditekan |
|---|---|---|
reply | id | Mengirim id ke webhook Anda |
url | url | Membuka tautan |
call | phone | Menelepon nomor |
copy | code | Menyalin kode |
Pesan list
POST /messages/listMenu pilihan bersection, cocok untuk katalog atau FAQ.
{
"to": "628123456789",
"text": "Pilih kategori produk:",
"title": "Katalog Toko",
"buttonText": "Pilih kategori",
"sections": [
{
"title": "Elektronik",
"rows": [
{ "title": "Laptop", "rowId": "cat_laptop", "description": "Laptop & aksesoris" },
{ "title": "Smartphone", "rowId": "cat_phone" }
]
}
]
}| Field | Tipe | Wajib | Keterangan |
|---|---|---|---|
text | string | ✅ | Isi pesan |
buttonText | string | ✅ | Label tombol pembuka list |
sections | array | ✅ | Tiap section wajib punya title dan rows |
title, footer | string | ❌ | Judul, footer |
Tiap baris: { title, rowId, description? }. Pilihan penerima masuk ke webhook sebagai list_reply dengan info.row_id.
Pesan carousel
POST /messages/carouselBeberapa kartu yang bisa digeser, masing-masing dengan gambar dan sampai 3 tombol.
{
"to": "628123456789",
"text": "Cek produk terbaru kami:",
"cards": [
{
"image": { "url": "https://domain-anda.com/produk1.jpg" },
"title": "Sepatu Sport",
"body": "Ringan dan nyaman, Rp350.000",
"buttons": [
{ "name": "cta_url", "params": { "display_text": "Beli", "url": "https://domain-anda.com/p/1", "merchant_url": "https://domain-anda.com/p/1" } }
]
}
]
}| Field | Tipe | Wajib | Keterangan |
|---|---|---|---|
text | string | ✅ | Teks di atas carousel |
cards | array | ✅ | 1–10 kartu: image, title, body, footer, buttons (maks. 3) |
title, subtitle, footer | string | ❌ | Di level pesan |
Tombol kartu memakai format name + params, lihat tabel di bawah.
Endpoint tombol lainnya
POST /messages/interactive: kontrol penuh atas tombol dengan format name + params. Field sama dengan quick-reply (text, title, subtitle, footer, image, buttons).
{
"to": "628123456789",
"text": "Ada yang bisa kami bantu?",
"buttons": [
{ "name": "quick_reply", "params": { "display_text": "Tanya", "id": "ask" } },
{ "name": "cta_call", "params": { "display_text": "Telepon CS", "phone_number": "62811223344" } }
]
}name | params |
|---|---|
quick_reply | display_text, id |
cta_url | display_text, url, merchant_url (isi sama dengan url) |
cta_call | display_text, phone_number |
cta_copy | display_text, copy_code |
POST /messages/buttons: format lama untuk 1–3 tombol balasan, tetap didukung. Untuk integrasi baru pakai quick-reply.
{
"to": "628123456789",
"text": "Puas dengan layanan kami?",
"footer": "Pilih salah satu",
"buttons": [
{ "buttonId": "rate_5", "displayText": "Sangat puas" },
{ "buttonId": "rate_1", "displayText": "Kurang" }
]
}Reaksi
POST /messages/reactionBeri reaksi emoji pada pesan, milik penerima atau milik Anda sendiri. Kirim emoji kosong ("") untuk menghapus reaksi.
{
"to": "628222222222",
"message": {
"remote_jid": "628222222222@s.whatsapp.net",
"message_id": "3EB0C12345ABCDEF",
"from_me": false
},
"emoji": "👍"
}| Field | Tipe | Wajib | Keterangan |
|---|---|---|---|
message.remote_jid | string | ✅ | Chat pribadi: <nomor>@s.whatsapp.net. Grup: metadata.group_id dari webhook |
message.message_id | string | ✅ | message.id dari webhook message.received |
message.from_me | boolean | ❌ | true bila pesan itu Anda yang kirim. Default false |
emoji | string | ✅ | Satu emoji, atau "" untuk menghapus |
Reaksi dihitung sebagai pesan (memakai kuota).
Read Receipt & Indikator Mengetik
Kedua endpoint ini butuh perangkat yang sedang tersambung. Bila tidak, request ditolak dengan device_not_connected. Keduanya tidak memakai kuota pesan.
Tandai dibaca: POST /messages/mark-read. Memunculkan centang biru, mis. bila auto-read di pengaturan perangkat dimatikan.
{
"to": "628123456789",
"messages": [
{ "remote_jid": "628123456789@s.whatsapp.net", "message_id": "ABC123" }
]
}messages berisi 1–50 pesan; tiap item boleh membawa from_me dan participant (untuk grup). Respons: { "count": 1, "job_id": "..." }. Pesan yang terlalu lama atau sudah dihapus mungkin tidak bisa ditandai.
Indikator mengetik: POST /messages/presence.
{ "to": "628123456789", "state": "composing", "duration_ms": 3000 }state | Penerima melihat |
|---|---|
composing | sedang mengetik… |
recording | merekam audio… |
paused | indikator berhenti |
available / unavailable | online / offline |
duration_ms (maks. 30000) mengakhiri indikator otomatis.
Bila sistem Anda menyusun balasan sendiri (mis. dengan AI), kirim composing saat mulai memproses, lalu panggil /messages/send tanpa humanlike begitu balasan siap. Indikator hilang saat pesan masuk, dan balasan tidak tertunda. humanlike hanya untuk menambah jeda mengetik pada pesan yang sudah siap.
Field jobId di respons mark-read dan presence sudah usang dan dihapus setelah 31 Oktober 2026. Pakai job_id.
Kirim Pesan dengan Template
POST /messages/send-templateKirim template yang sudah dibuat di dashboard (teks, media, tombol, list, atau carousel), dengan variabel yang diganti per penerima.
{
"to": "628123456789",
"template_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"variables": { "nama": "Budi Santoso", "total": "Rp150.000" },
"ref_id": "INV-2026-0042"
}| Field | Tipe | Wajib | Keterangan |
|---|---|---|---|
template_id | string (UUID) | ✅ | ID template dari dashboard |
variables | object | ❌ | { "nama_variabel": "nilai" }, nilai berupa teks |
Template Halo {{nama}}, total Anda {{total}}. dengan request di atas terkirim sebagai Halo Budi Santoso, total Anda Rp150.000.
- Template bermedia, bertombol, list, dan carousel terkirim sesuai bentuknya di dashboard.
- Variabel yang tidak diisi: pada template teks tetap tampil sebagai
{{nama}}; pada template bertombol, list, dan carousel dikosongkan. - Template yang tidak ada ditolak dengan
template_not_found.
Buka Template di dashboard NgirimWA.
Klik ikon Salin di kolom Aksi untuk menyalin template_id.
Lihat badge di bawah nama template untuk daftar variabelnya, mis. {{nama}} {{total}}, lalu isi semuanya di variables.