Kirim Pesan WhatsApp via API
Endpoint WhatsApp API untuk kirim pesan teks, gambar, dokumen, lokasi, kontak, dan polling otomatis dari aplikasi atau server kamu.
Semua endpoint pengiriman pesan berada di bawah POST /v1/wa/send/*, dan dikirim lewat device WhatsApp milik kamu.
Coba langsung
Referensi endpoint interaktif (request builder + response schema) tersedia di API Reference.
Autentikasi & Header Wajib
Setiap request butuh dua header:
Authorization: Bearer <api_key>
X-Device-Id: <id_device_yang_sudah_terhubung>Authorization: API key Dilztify.X-Device-Id:iddevice (lihat Devices) yang mengirim pesan. Device harus berstatus terhubung (is_logged_in: true).
Format Nomor Tujuan (phone)
Cukup isi nomor dengan kode negara. Tidak perlu + dan tidak perlu suffix @s.whatsapp.net:
6289685028129Suffix @s.whatsapp.net (JID) boleh disertakan dan hasilnya sama, tapi tidak wajib. Untuk grup, JID wajib, lihat bagian Kirim ke Grup.
Nomor Lokal 08… Otomatis Diubah
WhatsApp hanya menerima nomor berformat kode negara. Kamu tidak perlu mengonversinya sendiri: nomor Indonesia yang ditulis dengan awalan 0 otomatis diubah ke 62 sebelum dikirim, jadi 08… maupun 628… sama-sama diterima tanpa error.
| Kamu kirim | Menjadi |
|---|---|
08123456789 | 628123456789 |
0812-3456-789 | 628123456789 |
+62 812 3456 789 | 628123456789 |
00628123456789 | 628123456789 |
628123456789 | tidak berubah |
14155552671 (AS) | tidak berubah |
Aturannya:
- Hanya Indonesia yang punya format lokal berawalan
0. Nomor negara lain harus sudah membawa kode negaranya sendiri,0di depannya akan ditafsirkan sebagai nomor Indonesia. - Spasi, tanda hubung, kurung, dan tanda
+diabaikan. - Awalan
00diperlakukan sebagai kode akses internasional dan cukup dibuang. - Konversi ini berlaku di seluruh sistem: API proxy, kontak, campaign, dan Bot Flow.
Pada daftar nomor yang dipisahkan koma, setiap nomor dinormalisasi sendiri-sendiri:
{ "phone": "08123456789,628987654321" }Kirim ke Grup
ID grup (120363…) bukan nomor telepon, jadi untuk grup kamu wajib menulis ID lengkap beserta suffix @g.us. ID ini diteruskan apa adanya, tidak dinormalisasi. Hal yang sama berlaku untuk channel (@newsletter) dan @broadcast. Nomor pribadi tidak butuh suffix.
{ "phone": "[email protected]", "message": "Halo semua!" }menjadi 628123456789,628987654321.
Broadcast ke Banyak Nomor Sekaligus
Semua endpoint send/* (kecuali send/presence) mendukung banyak nomor tujuan dipisahkan koma:
{
"phone": "6289685028129,628123456789,628987654321",
"message": "Pengumuman untuk semua tim"
}Setiap nomor dipecah menjadi task terpisah dan dijadwalkan otomatis lewat Dilztify Ban Guard System (lihat bagian Antrian & Rate Limiting di bawah).
Endpoint yang Tersedia
| Endpoint | Fungsi | Body wajib |
|---|---|---|
POST /v1/wa/send/message | Kirim teks | phone, message |
POST /v1/wa/send/image | Kirim gambar | phone, salah satu image (file) / image_url |
POST /v1/wa/send/audio | Kirim audio / voice note | phone, salah satu audio (file) / audio_url |
POST /v1/wa/send/file | Kirim dokumen | phone, salah satu file (file) / file_url |
POST /v1/wa/send/sticker | Kirim sticker | phone, salah satu sticker (file) / sticker_url |
POST /v1/wa/send/video | Kirim video | phone, salah satu video (file) / video_url |
POST /v1/wa/send/contact | Kirim kartu kontak | phone, contact_name, contact_phone |
POST /v1/wa/send/link | Kirim link (dengan preview) | phone, link |
POST /v1/wa/send/location | Kirim titik lokasi | phone, latitude, longitude |
POST /v1/wa/send/poll | Kirim polling | phone, question, options, max_answer |
POST /v1/wa/send/presence | Set status online/offline akun | type (available/unavailable) |
POST /v1/wa/send/chat-presence | Kirim status "typing…" | phone, action (start/stop) |
Contoh: Kirim Teks
curl -X POST https://api.dilztify.my.id/v1/wa/send/message \
-H "Authorization: Bearer $TOKEN" \
-H "X-Device-Id: $DEVICE_ID" \
-H "Content-Type: application/json" \
-d '{
"phone": "6289685028129",
"message": "selamat malam",
"reply_message_id": "3EB089B9D6ADD58153C561"
}'Contoh: Kirim Gambar (URL)
curl -X POST https://api.dilztify.my.id/v1/wa/send/image \
-H "Authorization: Bearer $TOKEN" \
-H "X-Device-Id: $DEVICE_ID" \
-F "phone=6289685028129" \
-F "image_url=https://example.com/image.jpg" \
-F "caption=selamat malam"Endpoint media (image, audio, file, sticker, video) menerima multipart/form-data dan salah satu wajib diisi: upload file langsung (field binary) atau field *_url berisi URL publik ke file tersebut.
Contoh: Kirim Poll
curl -X POST https://api.dilztify.my.id/v1/wa/send/poll \
-H "Authorization: Bearer $TOKEN" \
-H "X-Device-Id: $DEVICE_ID" \
-H "Content-Type: application/json" \
-d '{
"phone": "6289685028129",
"question": "Siapa Nama Avatar The Last Air Bender?",
"options": ["Zuko", "Aang", "Katara"],
"max_answer": 1
}'Field Opsional yang Umum
Sebagian besar endpoint (kecuali presence/chat-presence) menerima field tambahan berikut:
| Field | Tipe | Keterangan |
|---|---|---|
reply_message_id | string | Membalas pesan tertentu (message ID) |
is_forwarded | boolean | Tandai pesan sebagai "diteruskan" |
duration | integer | Disappearing message, dalam detik |
mentions | array | Khusus send/message, mention nomor atau @everyone |
view_once | boolean | Khusus gambar/video, sekali lihat |
compress | boolean | Khusus gambar/video, kompresi otomatis |
process_at | string | Jadwalkan eksekusi di waktu tertentu (RFC3339), lihat Menjadwalkan Pengiriman di bawah |
Antrian & Rate Limiting
Kirim beruntun (burst), termasuk ke nomor yang sama, tidak ditolak dengan 429. Sebagai gantinya, request umumnya langsung mengembalikan 202 Accepted dan pesan diproses di background lewat antrean Dilztify Ban Guard System, yang menjadwalkan waktu kirim secara otomatis per perangkat (X-Device-Id) tanpa perlu kamu konfigurasi. Waktu kirim tiap pesan bisa berbeda dan dilaporkan di delay_seconds / next_process_at.
Untuk broadcast (phone berisi banyak nomor), setiap nomor menjadi task terpisah dengan delay_seconds masing-masing dan dijadwalkan berurutan.
Pesan yang gagal dikirim akan dicoba ulang otomatis di background. Selama masih dicoba ulang, statusnya di Message Logs tetap pending; menjadi failed setelah percobaan ulang habis, dan saldo tidak terpotong untuk pesan yang gagal.
Batasan Ban Guard
Ban Guard adalah kontrol risiko tambahan pada sisi pengiriman. Ia tidak menjamin nomor WhatsApp kamu bebas dari pembatasan atau pemblokiran: WhatsApp tetap menilai nomor, konten, dan perilaku pengiriman kamu (misalnya laporan spam, penerima yang tidak mengenalmu, atau nomor baru yang langsung kirim dalam jumlah besar). Kirim hanya ke kontak yang mengenal bisnismu.
Menjadwalkan Pengiriman dengan process_at
Semua endpoint send/* (kecuali send/presence dan send/chat-presence) menerima field opsional process_at berupa timestamp RFC3339 (mis. "2026-04-17T12:30:00Z"). Jika diisi:
- Nilainya harus di masa depan (
>= now), jika tidak request akan ditolak dengan422. - Request otomatis diproses sebagai antrian (
202 Accepted), walau mode async queue sedang tidak aktif. - Pesan akan dieksekusi tepat pada waktu yang diminta, bukan lebih cepat maupun lebih lambat.
Gunakan process_at dengan hati-hati
process_at melewati sepenuhnya pengaturan waktu kirim Dilztify Ban Guard System di
atas. Pesan yang dijadwalkan lewat process_at dieksekusi tepat pada
waktu yang diminta tanpa penyesuaian otomatis, sehingga risiko
nomor WhatsApp kamu dibatasi atau diblokir jadi lebih tinggi jika dipakai
untuk kirim beruntun ke banyak nomor pada waktu yang sama atau
berdekatan. Gunakan process_at seperlunya (mis. menjadwalkan satu
pesan di waktu tertentu), bukan sebagai pengganti antrian broadcast
biasa.
Contoh response 202 Accepted untuk single number:
{
"success": true,
"message": "Request diproses lewat Dilztify Ban Guard System",
"data": {
"task_id": "7afcbf4de9e74f699a2b",
"task_type": "whatsapp:proxy:request",
"task_state": "scheduled",
"queue": "high",
"max_retry": 25,
"next_process_at": "2026-04-17T12:30:12Z",
"delay_seconds": 12
},
"meta": { "method": "POST", "path": "/send/message" }
}Contoh response 202 Accepted untuk broadcast banyak nomor:
{
"success": true,
"message": "Broadcast diproses lewat Dilztify Ban Guard System untuk 2 penerima",
"data": {
"total": 2,
"queued": [
{ "phone": "6289685028129", "task_id": "7afcbf4de9e74f699a2b", "task_state": "pending", "next_process_at": "2026-04-17T12:30:00Z", "delay_seconds": 0 },
{ "phone": "628123456789", "task_id": "8bfdcf5df0f85f7a0b3c", "task_state": "scheduled", "next_process_at": "2026-04-17T12:30:09Z", "delay_seconds": 9 }
]
},
"meta": { "method": "POST", "path": "/send/message" }
}Status pengiriman tiap task bisa dipantau lewat Message Logs di dashboard.
Kode Response
| Status | Arti |
|---|---|
200 | Pesan langsung terkirim; data.message_id berisi ID pesan |
202 | Pesan masuk antrian (lihat di atas) |
400 | Header wajib (X-Device-Id) tidak ada, atau body/content-type tidak valid |
401 | Token/API key tidak valid atau tidak dikirim |
402 | Saldo tidak cukup |
404 | X-Device-Id tidak cocok dengan device di akun ini |
422 | Field wajib kosong, process_at sudah lewat, device belum login, atau nomor tujuan tidak terdaftar di WhatsApp |
429 | Salah satu dari dua kasus: batas request API (lebih dari 100 request per menit per akun), atau kuota pesan harian/bulanan paket habis. Bukan karena kirim beruntun, dan bukan saldo kurang (itu 402) |
502 | WhatsApp menolak/gagal memproses (kode HTTP bisa 400/500/502) |
503 | Antrean pengiriman sedang tidak tersedia |
Semua error berbentuk { "success": false, "message": "...", "details": { ... } }. details hanya ada pada sebagian error (misalnya missing_fields). Andalkan kode HTTP, bukan teks message.
Saldo & biaya per pesan
Setiap pesan yang berhasil diproses akan memotong saldo akun sesuai price_per_message pada pricing tier yang berlaku. Pastikan saldo mencukupi sebelum mengirim dalam jumlah besar.
Hubungkan Nomor WhatsApp
Cara menambah, scan QR, dan mengelola banyak nomor WhatsApp (device) di WhatsApp Gateway Dilztify untuk dipakai lewat API.
WhatsApp Blast & Campaign
Kirim WhatsApp blast ke banyak kontak sekaligus tanpa coding: kelola kontak, buat segment, dan jalankan campaign pesan massal dari dashboard.