Broadcast

POST /api/broadcasts, izin send:broadcast. Satu template ke daftar nomor (1 sampai 5.000 per permintaan), dengan variabel per penerima.

Broadcast dari API bukan mesin kirim terpisah. Kareeb membuat kampanye bertanda source: "api" di antrean yang sama dengan kampanye dari layar, sehingga kiriman Anda muncul di halaman Kampanye lengkap dengan corongnya. Pengiriman selalu dari cabang Utama.

Contoh permintaan

curl -X POST https://kareeb.id/api/broadcasts \
  -H "Authorization: Bearer kt_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "template_name": "pengingat_kontrol",
    "template_language": "id",
    "recipients": [
      {"wa_id": "6281234567890", "params": {"1": "Budi", "2": "Selasa 10.00"}},
      {"wa_id": "6281234567891", "params": {"1": "Sari", "2": "Rabu 09.00"}}
    ],
    "idempotency_key": "kontrol-2026-11-05",
    "name": "Pengingat kontrol besok"
  }'

Isi permintaan

Kolom	Wajib	Keterangan
template_name	ya	Harus ada di Kareeb, di akun WhatsApp cabang Utama, dan berstatus APPROVED.
template_language	tidak	Kode bahasa template. Bawaan "id".
recipients	ya	1 sampai 5.000 penerima.
recipients[].wa_id	ya	Nomor WhatsApp, 7 sampai 20 digit format internasional. Tanda plus di depan dan spasi di tepi dibuang; selain itu ditolak. Selalu nomor telepon.
recipients[].params	tidak	Variabel badan berurutan {"1": ..., "2": ...}. Aturannya ada di Daftar template.
idempotency_key	ya	1 sampai 128 karakter, unik di semua broadcast organisasi Anda.
name	tidak	Nama di halaman Kampanye. Bawaan: API: diikuti nama template.
scheduled_at	tidak	Waktu kirim, lihat di bawah.

Penerima yang belum ada di Kareeb otomatis menjadi kontak WhatsApp baru. Broadcast hanya untuk WhatsApp, karena template yang disetujui hanya ada di WhatsApp.

Mengirim nanti dengan scheduled_at

Tanpa scheduled_at, kampanye langsung masuk antrean dan mulai dikirim. Dengan scheduled_at, kampanye menunggu sebagai draf dengan antrean yang sudah tersusun, lalu dijalankan penjadwal Kareeb pada waktu itu.

{
  "template_name": "pengingat_kontrol",
  "recipients": [{"wa_id": "6281234567890", "params": {"1": "Budi", "2": "Selasa 10.00"}}],
  "idempotency_key": "kontrol-2026-11-05-pagi",
  "scheduled_at": "2026-11-05T07:00:00+07:00"
}

• Waktu wajib menyertakan zona waktu, misalnya +07:00 untuk WIB. Tanpa zona, permintaan ditolak 422.
• Waktu yang sudah lewat ditolak, begitu juga waktu lebih dari 30 hari ke depan.
• Setiap jawaban membawa kolom scheduled_at: berisi waktu bila terjadwal, atau null bila langsung dikirim.

Jawaban

202 Accepted untuk kampanye baru, 200 OK bila kunci yang sama sudah pernah dipakai.

{
  "id": 42,
  "replay": false,
  "idempotency_key": "kontrol-2026-11-05",
  "template_name": "pengingat_kontrol",
  "template_language": "id",
  "scheduled_at": null,
  "accepted": [
    {"wa_id": "6281234567890", "contact_id": 8, "recipient_id": 901}
  ],
  "refused": [
    {"wa_id": "6281234567891", "reason": "param 1 must be a non-empty string"}
  ],
  "status": {"state": "sending", "targeted": 1, "queued": 1, "sent": 0, "failed": 0}
}

• 202, bukan 201: antrean ditulis saat itu juga, pengirimannya berjalan sesudahnya.
• accepted dan refused adalah keputusan permintaan ini.
• status selalu dibaca langsung dari antrean.
• Untuk melihat hasil per penerima, baca GET /api/export/campaigns/recipients?campaign_id=42 (izin read:campaigns). Webhook campaign.finished mengabarkan saat antrean habis.

Penolakan per penerima

Penerima yang ditolak masuk ke refused beserta alasannya, dan kiriman tetap berjalan untuk penerima lain. Alasannya ditulis dalam bahasa Inggris untuk dibaca orang:

• wa_id bukan 7 sampai 20 digit;
• nomor yang sama muncul dua kali dalam satu permintaan (ditolak, bukan digabung, karena biasanya kueri audiens Anda yang perlu diperbaiki);
• kunci params bukan angka posisi, atau tidak berurutan tanpa celah;
• nilai params kosong, terlalu panjang, atau berisi baris baru, tab, atau lebih dari empat spasi berurutan;
• pelanggan sudah meminta berhenti dikirimi pesan, atau belum memberi persetujuan yang diwajibkan instalasi.

Penolakan seluruh permintaan

Jawaban 422 tidak membuat kampanye apa pun, sehingga kuncinya tetap bebas: perbaiki datanya lalu kirim lagi dengan kunci yang sama. Bila detail berupa objek dengan code, bercabanglah pada code:

code	Arti dan yang perlu dilakukan
template_not_synced	Template belum ada di Kareeb. Admin menekan Sinkronkan di menu Template, lalu kirim lagi.
template_not_approved	Template belum disetujui Meta. Menyinkronkan ulang tidak membantu; tunggu persetujuan Meta.
template_other_account	Template hanya ada di akun WhatsApp yang tidak lagi dipakai organisasi ini. Sinkronkan; bila tidak muncul, template perlu dibuat di akun yang sekarang.
template_other_cabang	Template ada di akun WhatsApp cabang lain, padahal broadcast dikirim dari cabang Utama.
campaign_quality_red, campaign_quality_yellow, campaign_tier_budget	Nomor WhatsApp sedang tidak layak menerima broadcast sebesar ini, menurut penilaian kualitas atau kapasitas harian dari Meta. Baca kalimat di message, perbaiki, lalu kirim lagi.

Bila semua penerima ditolak, detail berisi error dan daftar refused:

{"detail": {"error": "no usable recipients in this request", "refused": [{"wa_id": "6281234567890", "reason": "param 1 must be a non-empty string"}]}}

Kunci yang sama, kiriman yang sama

Kiriman ulang dengan idempotency_key yang sama dijawab 200 dengan "replay": true, id kampanye pertama, accepted dan refused kosong, serta status terkini. Tidak ada yang dibuat atau dikirim lagi, walaupun daftar penerimanya berbeda. Bila Anda memang ingin mengirim daftar lain, pakai kunci baru. Penjelasan lengkapnya ada di Kirim ulang tanpa pesan ganda.