Broadcast

Kirim satu pesan ke banyak nomor sekaligus, dengan jeda acak antar pesan (anti-ban).

Menentukan penerima

Ada dua cara, pilih salah satu:

Cara	Kapan dipakai
recipients	Daftar nomor eksplisit
segment	Kontak tersimpan, disaring tag & status opt-in

Segmen secara bawaan hanya menyasar kontak yang sudah opt-in — lihat Kontak & Opt-in.

Hitung dulu, kirim kemudian

Sebelum mengirim, pastikan targetnya sesuai harapan. Endpoint ini tidak mengirim apa pun:

curl -X POST https://waq.karyawah.id/v1/broadcasts/preview \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"segment": {"opt_in_only": true, "tag": "pelanggan-juli"}}'

{ "total": 128, "capped_at": 5000, "sample": ["6281...", "6285..."] }

total: 0 biasanya berarti kontakmu belum ditandai opt-in.

Mengirim

curl -X POST https://waq.karyawah.id/v1/broadcasts \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{
    "device_id": "<device_id>",
    "name": "Promo Juli",
    "type": "text",
    "text": "Halo, ada promo spesial minggu ini!",
    "segment": {"opt_in_only": true, "tag": "pelanggan-juli"}
  }'

Kirim gambar — unggah dulu berkasnya (lihat Unggah Media), lalu:

{
  "device_id": "<device_id>",
  "type": "image",
  "image_url": "https://waq.karyawah.id/media/<nama-berkas>.jpg",
  "caption": "Keterangan gambar",
  "recipients": ["6281234567890"]
}

Caption gambar dibatasi WhatsApp

Caption maksimal 1.024 karakter, sedangkan pesan teks biasa 4.096. Untuk teks panjang berlampiran gambar, kirim dua broadcast berurutan: gambar dulu, lalu teksnya. Dashboard melakukan ini otomatis — lewat API, buat dua permintaan.

Membaca hasilnya

curl https://waq.karyawah.id/v1/broadcasts -H "Authorization: Bearer $TOKEN"

{
  "data": [{
    "id": "…", "name": "Promo Juli", "type": "text",
    "status": "partial",
    "total": 500, "queued": 100, "sent": 96, "failed": 4, "pending": 0,
    "stopped_reason": "Limit harian 100 pesan tercapai (warmup) — 400 nomor belum dikirim.",
    "created_at": "2026-07-28T04:00:00.000Z"
  }]
}

Status	Arti
processing	Nomor sedang dimasukkan ke antrean
done	Semua nomor masuk antrean
partial	Berhenti sebelum semua nomor masuk — alasannya di stopped_reason
cancelled	Dibatalkan pemilik akun

Penyebab partial yang paling sering: kuota harian device habis. Lihat Troubleshooting.

Membatalkan pengiriman

Menghentikan pesan yang belum keluar. Pesan yang sudah terkirim tidak terpengaruh.

curl -X POST https://waq.karyawah.id/v1/broadcasts/<broadcast_id>/cancel \
  -H "Authorization: Bearer $TOKEN"

{ "cancelled": 11, "still_sending": 1, "status": "cancelled" }

still_sending = pesan yang sudah di tangan pengirim dan tak bisa ditarik lagi.

Menarik pesan yang sudah terkirim

Meminta WhatsApp menghapus pesan dari perangkat penerima ("Hapus untuk semua orang").

curl -X POST https://waq.karyawah.id/v1/broadcasts/<broadcast_id>/revoke \
  -H "Authorization: Bearer $TOKEN"

{ "queued": 40, "estimated_seconds": 90 }

Penarikan diproses bertahap dengan jeda antar pesan. Pantau hasilnya:

curl https://waq.karyawah.id/v1/broadcasts/<broadcast_id>/revoke-status \
  -H "Authorization: Bearer $TOKEN"

{ "revocable": 40, "revoked": 38, "failed": 2, "last_error": "message is too old" }

Tidak dijamin berhasil

WhatsApp hanya mengizinkan penghapusan dalam batas waktu tertentu setelah pengiriman, dan pesan yang sudah terlanjur dibaca tetap sempat terbaca. Penerima akan melihat jejak "Pesan ini telah dihapus".

Batas

• Maksimal 5.000 penerima per broadcast; kelebihannya dipotong dan dilaporkan di stopped_reason.
• Kuota harian device tetap berlaku — broadcast berhenti begitu kuota habis.
• Kata terlarang (lihat menu Filter Kata di dashboard) diperiksa sekali di depan: aksi block menolak seluruh broadcast, aksi mask menyensor teks untuk semua penerima.