NgirimWA Docs
API

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):

FieldTipeWajibKeterangan
tostring✅Nomor tujuan atau ID grup, lihat format nomor
ref_idstring❌ID milik Anda, mis. nomor tagihan. 1–100 karakter ASCII, tidak harus unik
expires_ininteger❌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"
  }
}
FieldArti
tracking_idID untuk melacak pesan. Simpan untuk Cek Status Pesan; ikut di setiap webhook message.*
ref_idref_id yang Anda kirim, atau null
expires_atBatas waktu pesan boleh dikirim
statusqueued: pesan diterima dan masuk antrean
job_idID 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

FormatContohDikirim ke
Internasional (disarankan)628123456789628123456789
Lokal Indonesia08123456789628123456789
Tanpa awalan8123456789628123456789
Negara lain60123456789, 14155551234apa adanya (wajib dengan kode negara)
Grup WhatsApp120363123456789012@g.usgrup

Panjang 8–15 digit. Karakter +, -, dan spasi dibersihkan otomatis.

Pesan Teks & Media

POST /messages/send

Teks

{
  "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"
}
FieldTipeWajibKeterangan
messagestring✅ untuk teksIsi pesan, atau caption bila ada media
mediastring✅ untuk mediaURL HTTPS publik atau data:image/jpeg;base64,...
media_typestring✅ untuk mediaimage, video, audio, document. Tanpa ini media diabaikan
file_namestring❌Nama file dokumen
reply_toobject❌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
humanlikeobject❌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
TipeFormatMaks. ukuran
imageJPG, PNG, GIF16 MB
videoMP4, AVI, MOV64 MB
audioMP3, OGG (Opus), M4A/AAC16 MB
documentPDF, DOC, DOCX, XLS, XLSX100 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:

KomponenBatas
Tombol per pesan / per kartu3
Kartu carousel10
Section list / baris per section10 / 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-reply

Satu 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" }
  ]
}
FieldTipeWajibKeterangan
textstring✅Isi pesan
buttonsarray✅1–3 tombol
title, subtitle, footerstring❌Judul, sub-judul, footer
imageobject❌{ "url": "..." } atau { "base64": "...", "mimeType": "image/jpeg" }
kindField tambahanSaat ditekan
replyidMengirim id ke webhook Anda
urlurlMembuka tautan
callphoneMenelepon nomor
copycodeMenyalin kode

Pesan list

POST /messages/list

Menu 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" }
      ]
    }
  ]
}
FieldTipeWajibKeterangan
textstring✅Isi pesan
buttonTextstring✅Label tombol pembuka list
sectionsarray✅Tiap section wajib punya title dan rows
title, footerstring❌Judul, footer

Tiap baris: { title, rowId, description? }. Pilihan penerima masuk ke webhook sebagai list_reply dengan info.row_id.

POST /messages/carousel

Beberapa 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" } }
      ]
    }
  ]
}
FieldTipeWajibKeterangan
textstring✅Teks di atas carousel
cardsarray✅1–10 kartu: image, title, body, footer, buttons (maks. 3)
title, subtitle, footerstring❌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" } }
  ]
}
nameparams
quick_replydisplay_text, id
cta_urldisplay_text, url, merchant_url (isi sama dengan url)
cta_calldisplay_text, phone_number
cta_copydisplay_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/reaction

Beri 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": "👍"
}
FieldTipeWajibKeterangan
message.remote_jidstring✅Chat pribadi: <nomor>@s.whatsapp.net. Grup: metadata.group_id dari webhook
message.message_idstring✅message.id dari webhook message.received
message.from_meboolean❌true bila pesan itu Anda yang kirim. Default false
emojistring✅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 }
statePenerima melihat
composingsedang mengetik…
recordingmerekam audio…
pausedindikator berhenti
available / unavailableonline / 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-template

Kirim 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"
}
FieldTipeWajibKeterangan
template_idstring (UUID)✅ID template dari dashboard
variablesobject❌{ "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.

On this page