🚫 Anda tidak terhubung ke internet
Dokumentasi Web

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: id device (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:

6289685028129

Suffix @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 kirimMenjadi
08123456789628123456789
0812-3456-789628123456789
+62 812 3456 789628123456789
00628123456789628123456789
628123456789tidak berubah
14155552671 (AS)tidak berubah

Aturannya:

  • Hanya Indonesia yang punya format lokal berawalan 0. Nomor negara lain harus sudah membawa kode negaranya sendiri, 0 di depannya akan ditafsirkan sebagai nomor Indonesia.
  • Spasi, tanda hubung, kurung, dan tanda + diabaikan.
  • Awalan 00 diperlakukan 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

EndpointFungsiBody wajib
POST /v1/wa/send/messageKirim teksphone, message
POST /v1/wa/send/imageKirim gambarphone, salah satu image (file) / image_url
POST /v1/wa/send/audioKirim audio / voice notephone, salah satu audio (file) / audio_url
POST /v1/wa/send/fileKirim dokumenphone, salah satu file (file) / file_url
POST /v1/wa/send/stickerKirim stickerphone, salah satu sticker (file) / sticker_url
POST /v1/wa/send/videoKirim videophone, salah satu video (file) / video_url
POST /v1/wa/send/contactKirim kartu kontakphone, contact_name, contact_phone
POST /v1/wa/send/linkKirim link (dengan preview)phone, link
POST /v1/wa/send/locationKirim titik lokasiphone, latitude, longitude
POST /v1/wa/send/pollKirim pollingphone, question, options, max_answer
POST /v1/wa/send/presenceSet status online/offline akuntype (available/unavailable)
POST /v1/wa/send/chat-presenceKirim 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:

FieldTipeKeterangan
reply_message_idstringMembalas pesan tertentu (message ID)
is_forwardedbooleanTandai pesan sebagai "diteruskan"
durationintegerDisappearing message, dalam detik
mentionsarrayKhusus send/message, mention nomor atau @everyone
view_oncebooleanKhusus gambar/video, sekali lihat
compressbooleanKhusus gambar/video, kompresi otomatis
process_atstringJadwalkan 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 dengan 422.
  • 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

StatusArti
200Pesan langsung terkirim; data.message_id berisi ID pesan
202Pesan masuk antrian (lihat di atas)
400Header wajib (X-Device-Id) tidak ada, atau body/content-type tidak valid
401Token/API key tidak valid atau tidak dikirim
402Saldo tidak cukup
404X-Device-Id tidak cocok dengan device di akun ini
422Field wajib kosong, process_at sudah lewat, device belum login, atau nomor tujuan tidak terdaftar di WhatsApp
429Salah 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)
502WhatsApp menolak/gagal memproses (kode HTTP bisa 400/500/502)
503Antrean 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.

On this page