Kirim Pesan Teks & Media

Endpoint

POST /messages/send

Pembaruan 18 September 2026: respons sukses kini jujur soal antrean — message menjadi "Message queued for delivery" dan data berisi job_id + status (queued/sent). Perangkat yang sesinya berakhir dijawab 409 device_logged_out (sebelumnya 400) dengan pesan Inggris; media yang gagal diunduh dijawab 400 media_download_failed. Lihat Penanganan Error.

Base URL

https://dash.ngirimwa.com/api/v1

Headers

x-api-key: API_KEY_ANDA
Content-Type: application/json
Idempotency-Key: <uuid-unik-per-request>

Idempotency-Key opsional tapi sangat disarankan untuk production. Lihat Autentikasi → Idempotency-Key.

Kirim Pesan Teks

Kirim pesan teks sederhana ke nomor WhatsApp.

Request

{
  "to": "628123456789",
  "message": "Halo, terima kasih telah berbelanja di toko kami!"
}

Respon Sukses

{
  "success": true,
  "message": "Message queued for delivery",
  "data": {
    "job_id": "61503",
    "status": "queued"
  }
}

Field	Arti
`data.status`	`queued` — pesan diterima dan masuk antrean pengiriman (normal di produksi). `sent` — pesan langsung diserahkan ke WhatsApp (saat itu `job_id` bernilai `null`).
`data.job_id`	ID antrean internal untuk korelasi dengan log/support. Bukan `message.id` WhatsApp — ID pesan baru ada saat webhook `message.sent` datang.

Parameter

Parameter	Tipe	Wajib	Deskripsi
`to`	string	✅	Nomor telepon penerima
`message`	string	✅	Isi pesan
`reply_to`	object	❌	Balas (quote) pesan tertentu: `{ "remote_jid": "628xxx@s.whatsapp.net", "message_id": "..." }` — ambil dari webhook `message.received`
`humanlike`	object	❌	Efek mengetik, lihat di bawah

Endpoint kirim memproses pesan lewat antrean: 200 berarti pesan diterima dan dijadwalkan, bukan sudah sampai. Status pengiriman (sent, delivered, read, failed) dilaporkan lewat webhook — cocokkan berdasarkan message.to + waktu, karena job_id dan message.id adalah ID yang berbeda.

Bila perangkat hanya terputus sesaat, request tetap 200 queued dan dikirim saat koneksi pulih. Hanya bila sesi perangkat sudah berakhir (perlu scan QR) request ditolak di depan dengan 409 device_logged_out.

Format Nomor Penerima (field `to`)

Berlaku untuk semua endpoint kirim (/send, /send-template, /quick-reply, /interactive, /buttons, /list, /carousel):

Format	Contoh	Hasil normalisasi
Internasional Indonesia (rekomendasi)	`628123456789`	tetap `628123456789`
Lokal Indonesia	`08123456789`	`628123456789`
Tanpa awalan (10–12 digit)	`8123456789`	`628123456789`
Internasional non-Indonesia	`60123456789` (Malaysia), `14155551234` (US)	tetap (asal include country code)
ID grup WhatsApp	`120363123456789012@g.us`	tetap (kirim ke grup)

Panjang nomor valid: 8–15 digit (sesuai standar ITU-T E.164). Karakter selain digit (+, -, spasi) otomatis dibersihkan. Aturan yang sama berlaku di /contacts/verify.

Kirim Pesan dengan Efek Mengetik

Untuk membuat pesan terasa lebih natural (cocok untuk chatbot), gunakan opsi humanlike:

{
  "to": "628123456789",
  "message": "Terima kasih atas pertanyaannya! Berikut jawabannya...",
  "humanlike": {
    "enabled": true,
    "typing_duration": "auto"
  }
}

Parameter humanlike:

Parameter	Nilai	Deskripsi
enabled	true/false	Aktifkan efek mengetik
typing_duration	“auto”	Durasi otomatis berdasarkan panjang pesan
typing_duration	3000	Durasi manual dalam milidetik

Kirim Pesan Teks + Media

Kirim Gambar

{
  "to": "628123456789",
  "media": "https://domain-anda.com/images/produk.jpg",
  "media_type": "image",
  "message": "Produk terbaru kami!"
}

Kirim Video

{
  "to": "628123456789",
  "media": "https://domain-anda.com/videos/promo.mp4",
  "media_type": "video",
  "message": "Video promo spesial!"
}

Kirim Dokumen (PDF, Word, Excel)

{
  "to": "628123456789",
  "media": "https://domain-anda.com/files/invoice.pdf",
  "media_type": "document",
  "file_name": "Invoice_Desember_2025.pdf",
  "message": "Berikut invoice pesanan Anda"
}

Kirim Audio

{
  "to": "628123456789",
  "media": "https://domain-anda.com/audio/notification.mp3",
  "media_type": "audio"
}

Parameter Media Lengkap

Paramater	Tipe	Wajib	Deskripsi
to	string	✅	Nomor telepon penerima
media	string	✅	URL HTTPS publik, atau data base64 berbentuk data-URI (`data:image/jpeg;base64,...`)
media_type	string	✅	Tipe: image, video, audio, document. Wajib saat `media` diisi — tanpa `media_type`, `media` diabaikan dan hanya `message` yang dikirim sebagai teks
message	string	❌	Caption (opsional)
file_name	string	❌	Nama file untuk dokumen

Format Media yang Didukung

Tipe	Format	Ukuran Maks (batas WhatsApp)
image	JPG, PNG, GIF	16 MB
video	MP4, AVI, MOV	64 MB
audio	MP3, OGG, WAV	16 MB
document	PDF, DOC, DOCX, XLS, XLSX	100 MB

Ukuran dan format tidak divalidasi di sisi server — request tetap 200 queued. Media yang melebihi batas atau ditolak WhatsApp berakhir sebagai webhook message.failed. URL yang tidak bisa diunduh (host error / timeout 30 detik) dijawab 400 media_download_failed.

Batasan Teks (mengikuti limit WhatsApp)

Field	Batas karakter (perkiraan)
`message` (teks tanpa media)	~4.096
`message` (caption media)	~1.024
`file_name`	255

Sistem tidak memvalidasi karakter melebihi limit di atas — namun WhatsApp client akan memotong tampilan pesan yang terlalu panjang. Pakai limit ini sebagai pegangan agar pesan tampil utuh.

Contoh cURL

Kirim Pesan Teks

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!"
  }'

Kirim Gambar

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",
    "media": "https://domain-anda.com/gambar.jpg",
    "media_type": "image",
    "message": "Produk terbaru!"
  }'

Kirim Pesan Teks & Media

On this page