Panduan & Referensi API Broadcast

Mulai Cepat

Tiga langkah buat mulai kirim broadcast lewat API kamu sendiri.

1. Hubungkan nomor WhatsApp Business kamu. Kalau belum, hubungkan lewat halaman Nomor & WABA di dashboard — ini yang jadi sumber pengiriman semua pesanmu.
2. Bikin API key. Buka halaman API Key di dashboard, klik "Buat Key Baru". Key ini (diawali fvb_...) berlaku buat semua nomor WABA milik akunmu — cuma ditampilkan sekali saat dibuat, jadi simpan baik-baik.
3. Coba panggilan pertama. Panggil GET /api/broadcast/numbers buat mastiin key-nya jalan dan dapetin connection_id nomor kamu. Atau langsung coba interaktif lewat API Playground di dashboard tanpa nulis kode dulu.

Konsep Dasar

Template vs. Teks Bebas

Ada dua cara kirim pesan lewat WhatsApp Business Platform, dan itu bukan pilihan kami — itu aturan Meta:

• Template — pesan dengan format tetap yang sudah disetujui Meta sebelumnya. Ini satu-satunya cara memulai percakapan baru ke nomor yang belum pernah chat ke kamu. Dipakai oleh POST /send dan POST /send-to-group.
• Teks bebas — balasan bebas format, tapi cuma bisa dikirim dalam jendela 24 jam sejak pelanggan terakhir kali chat ke nomor kamu. Dipakai oleh POST /send-text.

Kenapa selalu butuh connection_id?

Satu API key berlaku buat semua nomor WhatsApp yang dimiliki akunmu — bukan cuma satu. Karena itu, tiap kali mau kirim, kamu wajib bilang mau kirim dari nomor yang mana lewat connection_id. Dapatkan daftarnya dari GET /api/broadcast/numbers.

Siapa Nyiapin Apa?

Ada 2 hal yang harus ADA sebelum bisa kirim, dan tempat nyiapinnya beda — ini yang paling sering bikin bingung integrator baru:

• Isi & tampilan pesan (Template) — wajib dibikin dan disetujui Meta dulu lewat dashboard kami, bukan lewat API. Ini bukan pilihan desain kami — persetujuan template itu review manual dari pihak Meta sendiri, gak ada platform manapun yang bisa bikin itu instan lewat panggilan API. Kabar baiknya: ini cuma sekali per jenis pesan, bukan tiap mau kirim — sekali promo_september approved, kamu bisa panggil dia berkali-kali lewat API kapan saja.
• Daftar penerima & datanya — ini 100% bisa dari sistem kamu sendiri, gak perlu nyentuh dashboard kami sama sekali: kirim langsung nomor + datanya lewat POST /send. Cuma kalau kamu memang mau manfaatin kontak yang sudah tersimpan & dikelompokkan di dashboard kami, baru pakai POST /send-to-group — itu opsional, bukan keharusan.

Cara Isi Variable Template ({{1}}, {{2}}, dst.)

Variable di template itu berdasarkan urutan/posisi, bukan nama field — Meta gak punya konsep "nama variable", cuma nomor urut. Caranya:

1. Panggil GET /api/broadcast/templates/{name}, baca teks body-nya buat ngerti maksud tiap nomor (misal "Halo {{1}}, promo {{2}}% khusus kamu!" — {{1}} = nama, {{2}} = diskon).
2. Isi array variables persis di urutan itu: ["Budi", "20"].

Penting kalau mau kirim personalized (nama/isi beda tiap orang): 1 panggilan POST /send memakai 1 array variables yang sama buat SEMUA nomor di request itu — bukan per-orang. Kalau tiap penerima harus dapet isian yang beda-beda, panggil POST /send berkali-kali, 1 panggilan per penerima, masing-masing dengan numbers (isi 1 nomor) dan variables miliknya sendiri — bukan sekali panggil buat semua orang sekaligus.

Skenario Umum

Tiga situasi paling sering dipakai integrasi lain lewat API kami — dan endpoint mana yang cocok buat masing-masing.

Autentikasi

Semua request ditandatangani lewat header Authorization pakai skema Bearer. Tempel API key kamu (yang diawali fvb_...) apa adanya, tanpa kutip tambahan:

Authorization: Bearer fvb_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Kalau header-nya hilang, key-nya salah, sudah dicabut, atau kedaluwarsa — semua endpoint balikin 401 dengan pesan error yang jelas, bukan diam-diam gagal.

Dashboard vs. API — Kapan Pakai yang Mana?

Keduanya kirim lewat jalur yang sama persis di belakang layar — bedanya cuma siapa yang memicu pengirimannya, dan beberapa fitur di dashboard memang belum kami buka lewat API.

• Dashboard cocok kalau kamu (atau tim kamu) yang manual pilih kontak/grup dan kirim broadcast langsung dari browser — nggak butuh kode sama sekali.
• API cocok kalau pengirimannya harus otomatis dipicu dari sistem lain — misalnya toko online kamu otomatis kirim notifikasi WhatsApp begitu ada pesanan baru, atau CRM kamu kirim reminder terjadwal sendiri.

Butuh CTA, media, atau kirim terjadwal lewat API? Fitur-fitur itu masih eksklusif dashboard buat sekarang — kabarin kami kalau butuh dibuka lewat API juga.

Webhook

Kebalikan dari semua endpoint di atas — bukan kamu yang manggil kami, tapi kami yang otomatis kirim data ke sistem kamu begitu ada kejadian, tanpa kamu perlu nembak API terus-menerus buat ngecek "ada yang baru belum?".

Bisa Dipakai Buat Apa?

Dua kejadian yang sekarang bisa didorong otomatis ke sistem kamu:

Webhook ini sifatnya opsional pelengkap, bukan pengganti — kalau sistem kamu udah cukup dengan cara nembak API biasa (polling), gak masalah, gak wajib pasang webhook sama sekali.

Cara Pasang — 1. Daftarkan URL kamu

Buka halaman API Key di dashboard, tempel 1 URL server kamu sendiri yang bisa nerima POST (wajib https://, gak boleh mengarah ke alamat internal/privat). Kami langsung kirim 1 permintaan verifikasi ke situ — endpoint kamu harus membalas kode acaknya persis biar statusnya jadi "Aktif". Ini buat mastiin kamu beneran pemilik URL itu, sama seperti Meta memverifikasi webhook mereka sendiri ke kami.

{
  "event": "webhook.verification",
  "sent_at": "2026-08-28T10:00:00+07:00",
  "data": { "challenge": "aB3xZ..." }
}

Balas dengan status 200 — boleh cuma teks polos berisi nilai challenge itu apa adanya, atau JSON {"challenge": "aB3xZ..."}. Salah satu cukup.

Cara Pasang — 2. Verifikasi tanda tangannya

Tiap permintaan (verifikasi maupun event beneran) dikirim dengan 2 header tambahan — pakai ini buat memastikan requestnya beneran dari kami, bukan orang lain yang menembak URL kamu:

X-Webhook-Event: message.received
X-Webhook-Signature: sha256=1a2b3c...

Secret buat verifikasi ini ada di halaman API Key yang sama (tombol "Lihat" di kartu Webhook) — jangan pernah ditaruh di kode sisi client/browser, cuma dipakai di server kamu. Cara ceknya: hitung ulang HMAC-SHA256 dari raw body permintaan (persis apa adanya, sebelum di-parse jadi objek) pakai secret itu, lalu bandingkan hasilnya dengan nilai setelah sha256= di header — pakai perbandingan yang aman dari timing attack (hash_equals), bukan == biasa.

$rawBody = file_get_contents('php://input'); // wajib RAW, bukan hasil json_decode
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$secret = 'whsec_...'; // ambil dari kartu Webhook di halaman API Key

$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);

if (! hash_equals($expected, $signature)) {
    http_response_code(403);
    exit;
}

// Lolos verifikasi — baru sekarang aman diproses.
$payload = json_decode($rawBody, true);
$event = $payload['event']; // 'message.received' / 'message.status_update' / 'webhook.verification'
$data = $payload['data'];

Detail Teknis — Bentuk Tiap Event

message.received — balasan baru masuk ke Inbox:

{
  "event": "message.received",
  "sent_at": "2026-08-28T10:05:00+07:00",
  "data": {
    "message_id": 1042,
    "wamid": "wamid.HBg...",
    "connection_id": 4,
    "from": "6281234567890",
    "contact_name": "Budi Santoso",
    "type": "text",
    "body": "Halo, saya mau tanya stok",
    "timestamp": "2026-08-28T10:05:00+07:00"
  }
}

message.status_update — status pesan yang kamu kirim berubah (field-nya sama persis dengan salah satu baris recipients di GET /broadcasts/{id}):

{
  "event": "message.status_update",
  "sent_at": "2026-08-28T10:06:00+07:00",
  "data": {
    "broadcast_id": 514,
    "phone": "6281234567890",
    "message_id": "wamid.HBg...",
    "status": "delivered",
    "error": null,
    "sent_at": "2026-08-28T10:05:50+07:00",
    "delivered_at": "2026-08-28T10:06:00+07:00",
    "read_at": null
  }
}

status naik bertahap sent → delivered → read, atau langsung failed (isi error dengan alasannya) — sama persis urutan yang dipakai GET /broadcasts/{id}, jadi kode yang sudah kamu tulis buat parsing endpoint itu bisa dipakai ulang.

Aturan pengiriman

• Balas 200 secepatnya (dalam 5 detik) — kalau server kamu lambat/tidak merespons, dianggap gagal.
• Gagal terkirim akan dicoba ulang otomatis 3x (jeda 30 detik, 2 menit, lalu 10 menit) sebelum menyerah.
• Riwayat tiap percobaan pengiriman (berhasil maupun gagal, lengkap dengan kode responsnya) bisa dilihat di kartu Webhook halaman API Key.
• 1 client cuma bisa punya 1 URL webhook aktif untuk sekarang — dipakai bersama buat semua event dan semua nomor WhatsApp kamu.

Endpoint yang Tersedia

Semua endpoint di bawah butuh header Authorization: Bearer fvb_... — dapatkan API key kamu dari halaman API Key di dashboard. Tanpa key yang valid, semua endpoint ini balikin 401.

Ada 2 bentuk error yang bisa kamu terima: field wajib yang kosong/salah tipe balikin 422 bentuk bawaan Laravel ({"message": "...", "errors": {"field": ["..."]}}), sedangkan error dari logika kami sendiri (template gak ketemu, jendela 24 jam abis, dll) balikin bentuk yang lebih simpel {"error": "..."} — kedua contoh di bawah tiap endpoint pakai bentuk yang kedua.

Daftar Nomor

Nomor WhatsApp mana aja yang bisa dipakai buat kirim lewat API key ini.

{
    "numbers": [
        {
            "connection_id": 4,
            "phone_number": "6281234567890",
            "label": "Nomor Utama",
            "waba_name": "Toko Maju Jaya"
        }
    ]
}

Daftar Template

Template yang sudah disetujui Meta dan dicentang "Bisa dipakai lewat API". Variabelnya diberi posisi {{1}}, {{2}}, dst. — urutan diisinya diserahkan ke sistem kamu sendiri.

{
    "templates": [
        {
            "name": "info_promo",
            "category": "MARKETING",
            "language": "id",
            "body": "Halo {{1}}, ada promo spesial buat kamu: {{2}}!",
            "variable_count": 2,
            "waba_name": "Toko Maju Jaya",
            "note": null
        },
        {
            "name": "otp_login",
            "category": "AUTHENTICATION",
            "language": "id",
            "body": "",
            "variable_count": 0,
            "waba_name": "Toko Maju Jaya",
            "note": "Kategori Authentication: teks pesan dibuat otomatis oleh Meta, tidak ada variabel bebas. Kirim lewat POST /send-otp dengan parameter code."
        }
    ]
}

Detail 1 Template

Struktur komponen lengkap satu template (HEADER/BODY/FOOTER/BUTTONS) — buat yang cuma butuh tau 1 template doang, bukan nge-list semuanya.

{
    "name": "info_promo",
    "category": "MARKETING",
    "language": "id",
    "variable_count": 2,
    "waba_name": "Toko Maju Jaya",
    "components": [
        {
            "type": "HEADER",
            "format": "IMAGE"
        },
        {
            "type": "BODY",
            "text": "Halo {{1}}, ada promo spesial buat kamu: {{2}}!"
        },
        {
            "type": "FOOTER",
            "text": "Balas STOP untuk berhenti menerima pesan promosi."
        }
    ],
    "note": null
}

{
    "error": "Template 'info_promo' tidak ditemukan atau belum bisa dipakai lewat API."
}

Daftar Grup Kontak

Semua grup kontak client ini, berlaku buat semua nomor (gak terikat 1 WABA) — inilah yang ngasih tau group_id buat dipakai di operasi "Kirim ke Grup Kontak" di bawah.

{
    "groups": [
        {
            "group_id": 12,
            "name": "Pelanggan VIP",
            "active_contacts_count": 48,
            "total_contacts_count": 50
        }
    ]
}

Daftar Kontak dalam Grup

Isi satu grup kontak — nama, nomor, custom field, dan status opt-out tiap kontak. Berguna buat preview isi grup sebelum manggil "Kirim ke Grup Kontak" di bawah.

{
    "group_id": 12,
    "name": "Pelanggan VIP",
    "contacts": [
        {
            "contact_id": 30,
            "name": "Andi Saputra",
            "phone": "6281234567890",
            "custom_fields": {
                "kota": "Bandung"
            },
            "opted_out": false
        }
    ]
}

{
    "error": "Grup kontak tidak ditemukan."
}

Kirim ke Nomor Langsung

Kirim broadcast pakai template langsung ke daftar nomor yang kamu kirim di request — nomornya tidak disimpan sebagai kontak kami, cocok kalau sistem kamu sendiri yang mengelola data pelanggan.

{
    "broadcast_id": 512,
    "status": "queued",
    "template": "info_promo",
    "total_recipients": 2
}

{
    "error": "Template 'info_promo' tidak ditemukan atau belum approved buat nomor ini."
}

Kirim ke Grup Kontak

Kirim ke satu grup kontak yang sudah ada di dashboard kami — grup itu harus sudah punya tepat 1 template yang di-mapping (lewat halaman Template) kecuali kamu sertakan template_name buat pilih salah satu.

{
    "broadcast_id": 513,
    "status": "queued",
    "template": "info_promo",
    "group": "Pelanggan VIP",
    "total_recipients": 48
}

{
    "error": "Grup \"Pelanggan VIP\" punya lebih dari 1 template ter-mapping \u2014 sertakan 'template_name' buat pilih salah satu.",
    "available_templates": [
        "info_promo",
        "reminder_bayar"
    ]
}

Balas Teks Bebas

Kirim pesan teks bebas (bukan template) — cuma jalan dalam jendela 24 jam Meta (nomor tujuan harus baru saja chat ke WABA ini). Dikirim langsung (synchronous), hasilnya dibalikin seketika, bukan diantre.

{
    "status": "sent",
    "message_id": "wamid.HBg...",
    "broadcast_id": 514
}

{
    "error": "(#131047) Message failed to send because more than 24 hours have passed since the customer last replied to this number.",
    "error_code": 131047,
    "broadcast_id": 514
}

Kirim Kode OTP

template_name wajib sudah approved, kategori Authentication, dan dicentang "Bisa dipakai lewat API" (lihat Daftar Template — template kategori ini juga muncul di situ, ditandai lewat field note).

{
    "status": "sent",
    "message_id": "wamid.HBg...",
    "broadcast_id": 515
}

{
    "error": "Template 'otp_login' tidak ditemukan, belum approved, bukan kategori Authentication, atau belum dicentang \"Bisa dipakai lewat API\"."
}

Cek Status Broadcast

Status keseluruhan (sent_count/delivered_count/read_count/failed_count) plus rincian per nomor penerima — status per-penerima naik bertahap pending → sent → delivered → read begitu Meta ngirim webhook callback-nya ke kami, atau langsung failed kalau gagal.

{
    "broadcast_id": 514,
    "status": "completed",
    "template": "info_promo",
    "group": null,
    "total_count": 2,
    "sent_count": 0,
    "delivered_count": 1,
    "read_count": 1,
    "failed_count": 1,
    "created_at": "2026-08-18T02:10:00+00:00",
    "recipients": [
        {
            "phone": "6281234567890",
            "status": "read",
            "message_id": "wamid.HBg...",
            "error": null,
            "sent_at": "2026-08-18T02:10:05+00:00",
            "delivered_at": "2026-08-18T02:10:08+00:00",
            "read_at": "2026-08-18T02:11:40+00:00"
        },
        {
            "phone": "6281298765432",
            "status": "failed",
            "message_id": null,
            "error": "Nomor Tidak Terdaftar di WhatsApp \u2014 (#131026) ...",
            "sent_at": null,
            "delivered_at": null,
            "read_at": null
        }
    ]
}

{
    "error": "Broadcast tidak ditemukan."
}