Ditinjau oleh Broadcast WhatsApp massal lewat API, dalam satu panggilan
Toko online kamu punya ratusan pelanggan yang sudah opt-in, dan menjelang flash sale kamu ingin mengirim satu pesan promo ke semuanya tanpa menekan kirim satu per satu di dashboard. Untuk broadcast WhatsApp massal lewat API resmi, kamu cukup mengirim satu POST /api/v1/public/broadcast/send berisi nama template yang sudah APPROVED, kode bahasa, dan daftar nomor dalam format E.164. api.co.id akan membuat satu broadcast job, mengirim pesannya di latar belakang dengan jeda yang kamu atur, lalu mereturn job_id yang bisa kamu pantau lewat GET /api/v1/public/broadcast/jobs/{id}. Satu job menampung sampai 1.000 nomor, dan tagihannya ikut nomor pengirim, Rp100.000 per bulan, sementara jumlah pesan di dalamnya tidak menambah biaya.
Cara ini berbeda dari fitur broadcast list di aplikasi WhatsApp biasa, yang hanya menjangkau orang yang sudah menyimpan nomormu dan tetap kamu kirim satu per satu dari layar ponsel. Lewat WhatsApp Official API dari api.co.id, satu api call menjangkau seluruh daftar nomor yang sudah opt-in, dan tiap pesan punya status yang terlacak sampai dibaca. Kalau kamu ingin kirim tanpa lebih dulu menyimpan kontaknya, pola broadcast tanpa menyimpan nomor juga jalan lewat endpoint yang sama.
Yang harus siap sebelum broadcast
Sebelum panggilan pertamamu berhasil, ada beberapa hal yang harus beres lebih dulu:
- Membuat akun di api.co.id
- Mengaktifkan produk WhatsApp Official API (Rp100.000 per nomor per bulan)
- Menghubungkan WhatsApp Business Account dan menyimpan API key
- Memiliki minimal satu template berstatus APPROVED di Meta
WhatsApp Business Account kamu hubungkan ke dashboard lebih dulu; langkahnya ada di panduan menghubungkan akun WhatsApp. Gateway ini memakai header Authorization: Bearer <API_KEY>, beda dari header x-api-co-id yang dipakai API inti api.co.id, jadi pastikan kamu memasang header yang benar. Kamu bisa cek dulu apakah key-mu dikenal lewat health check:
curl https://use.api.co.id/api/v1/public/health \
-H "Authorization: Bearer YOUR_API_KEY"{"success":true,"data":{"status":"ok","authenticated":true,"user_id":"<id>","timestamp":"..."}}Kalau authenticated bernilai true, key-mu valid dan kamu bisa lanjut. Kalau yang kembali 401, cek lagi nilai yang kamu salin dari dashboard sebelum menyiapkan daftar nomor.
Kenapa wajib template yang sudah disetujui
Di luar jendela 24 jam sejak pesan terakhir dari pelanggan, Meta hanya mengizinkan pesan berbasis template yang sudah disetujui. Broadcast promo hampir selalu jatuh di luar jendela itu, jadi endpoint ini menolak kirim kalau templatenya belum APPROVED. Aturan lengkap soal template bisa kamu baca di dokumentasi message template Meta, dan cara Meta mengirim template ada di panduan send message templates. Pola template yang sama juga kamu pakai saat mengirim OTP lewat WhatsApp.
Menemukan template yang bisa dipakai
Sebelum mengirim, kamu perlu tahu nama template dan kode bahasanya persis seperti yang terdaftar. Ambil daftarnya dengan filter status APPROVED:
curl "https://use.api.co.id/api/v1/public/templates?status=APPROVED" \
-H "Authorization: Bearer YOUR_API_KEY"Dari data[] kamu ambil template_name dan language untuk dipasang di request broadcast. variables memberi tahu berapa placeholder ({{1}}, {{2}}) yang harus kamu isi, dan content menampilkan teks template lengkap supaya kamu tahu nilai apa yang pas untuk tiap variabel. Kalau kamu belum punya template, pembuatan dan pengajuannya ke Meta jalan lewat endpoint terpisah yang ada di tabel bawah.
Mengirim broadcast lewat POST /broadcast/send
Setelah template siap, kamu kirim broadcast dalam satu api call. Di body kamu memasukkan template_name, language, dan phone_numbers dalam format E.164. Kalau templatemu punya variabel, isi components dengan nilainya, misalnya {"1":"pelanggan setia","2":"20%"}. Nilai di components dipakai sama untuk semua penerima, jadi lewat endpoint ini tiap nomor menerima isi variabel yang identik. Untuk isi yang beda per orang, kamu memakai jalur pesan satu per satu, di luar broadcast ini.
message_delay_ms mengatur jeda antar pengiriman di latar belakang, dari 0 sampai 30000 milidetik, dengan default 1000. Nilai seperti 1500 menahan laju kirim supaya tidak terkesan spam dan ikut menjaga blast tetap aman dari banned. Begitu request masuk, api.co.id membuat satu broadcast job, membalas 201 dengan job_id, lalu memproses pesan satu per satu di latar belakang sesuai jeda tadi, sementara kamu memantau progresnya lewat polling. Alurnya seperti ini:
curl -X POST https://use.api.co.id/api/v1/public/broadcast/send \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"template_name": "promo_akhir_tahun",
"language": "id",
"phone_numbers": ["+6281234567890", "+628551234567", "+6287812345678"],
"components": {"1": "pelanggan setia", "2": "20%"},
"message_delay_ms": 1500
}'{
"success": true,
"data": {
"job_id": "cm7bq...",
"template_name": "promo_akhir_tahun",
"status": "PENDING",
"total_recipients": 3,
"created_at": "..."
}
}Simpan job_id dari respons. Nilai itulah yang kamu pakai untuk memantau dan, kalau perlu, membatalkan job. Satu job menerima minimal 1 dan maksimal 1.000 nomor; kalau daftarmu lebih dari 1.000, pecah jadi beberapa job. Tiap nomor harus lolos format E.164 (^\+[1-9]\d{9,14}$), dengan spasi dan tanda hubung dibuang dulu sebelum divalidasi, jadi +62 812-3456-7890 tetap diterima. Kalau ada yang salah format, seluruh request ditolak dengan 400 dan details.invalid_phones menunjukkan sampai sepuluh nomor pertama yang bermasalah berikut details.total_invalid.
Memantau status job sampai selesai
Dengan job_id tadi, kamu polling detail jobnya sampai status menjadi COMPLETED:
curl https://use.api.co.id/api/v1/public/broadcast/jobs/cm7bq... \
-H "Authorization: Bearer YOUR_API_KEY"{
"success": true,
"data": {
"status": "COMPLETED",
"total_recipients": 3,
"sent_count": 3,
"delivered_count": 3,
"read_count": 1,
"success_count": 3,
"failed_count": 0,
"pending_count": 0,
"recipients": [
{"phone_number": "+6281234567890", "status": "read", "message_id": "wamid...", "error": null, "sent_at": "..."}
]
}
}Hitungan di respons membedakan tahap tiap pesan: sent_count yang sudah terkirim ke WhatsApp, delivered_count yang sampai ke ponsel penerima, dan read_count yang sudah dibaca. success_count dan failed_count merangkum hasil akhirnya. Yang paling berguna saat ada kegagalan adalah recipients[]: tiap entri memuat error kalau nomor itu gagal, jadi kamu tahu persis nomor mana yang perlu ditindaklanjuti.
Membatalkan broadcast yang sedang jalan
Kalau kamu salah pilih template atau ingin menghentikan kirim, batalkan jobnya selagi status masih PENDING atau PROCESSING:
curl -X POST https://use.api.co.id/api/v1/public/broadcast/jobs/cm7bq.../cancel \
-H "Authorization: Bearer YOUR_API_KEY"Begitu job sudah COMPLETED, FAILED, atau CANCELLED, endpoint ini membalas 400 dengan pesan bahwa hanya job PENDING atau PROCESSING yang bisa dibatalkan. Karena pengiriman berjalan bertahap mengikuti jeda tadi, pembatalan yang kamu kirim di awal bisa menyelamatkan sebagian besar nomor yang belum sempat dikirimi.
Error yang akan kamu temui
Sebelum atau saat broadcast dibuat, API bisa menolak requestmu. Ini yang paling sering muncul dan penyebabnya:
| Situasi | Status | Pesan |
|---|---|---|
| Template belum disetujui | 404 | Template not found or not approved |
| WABA belum terhubung | 400 | WhatsApp Business Account not connected or no phone number available |
| Ada nomor salah format | 400 | Some phone numbers have invalid format. Use E.164 format (e.g. +6281234567890) |
| Header auth tidak ada | 401 | API key required. Provide Bearer token in Authorization header. |
| API key salah atau kedaluwarsa | 401 | Invalid or expired API key. |
| Terlalu banyak gagal auth | 429 | Too many failed authentication attempts... |
Yang 429 muncul setelah 10 kegagalan auth dalam 5 menit: API mengirim header Retry-After: 900 dan memblokir IP-mu selama 15 menit. Kalau kamu kena ini saat mencoba key, hentikan percobaan dan perbaiki nilai key-nya dulu sebelum menunggu blokirnya lewat.
Contoh utuh: dari daftar nomor sampai laporan terkirim
Gabungkan semuanya. Template promo_akhir_tahun bahasa id sudah APPROVED dengan body Halo {{1}}, nikmati diskon {{2}} untuk belanja berikutnya. Kamu kirim ke tiga nomor +6281234567890, +628551234567, dan +6287812345678 dengan components {"1":"pelanggan setia","2":"20%"} dan message_delay_ms 1500, seperti request di atas. Responsnya memberi job_id cm7bq... dengan status PENDING dan total_recipients 3. Beberapa saat kemudian GET /broadcast/jobs/cm7bq... menghasilkan status COMPLETED, sent_count 3, delivered_count 3, read_count 1, success_count 3, dan failed_count 0.
Di skala nyata, toko fashion dengan 850 pelanggan opt-in menyusun daftar nomornya dalam E.164, memecahnya kalau melewati 1.000, memilih template MARKETING flash_sale_48jam yang sudah APPROVED, memanggil broadcast dengan message_delay_ms 1500, menyimpan job_id, lalu polling tiap beberapa detik sampai COMPLETED untuk tahu berapa yang terkirim dan dibaca. Kalau ternyata salah pilih template, jobnya dibatalkan selagi masih PROCESSING.
Biaya dan batas
Produk WhatsApp Official API ditagih per nomor pengirim, Rp100.000 per bulan atau Rp1.000.000 per tahun, dan berapa pun broadcast maupun pesan yang kamu kirim di dalamnya tidak menambah angka itu. Rincian biaya WhatsApp API Gateway per nomor ada di halaman tersendiri. Dari sisi batas teknis, satu broadcast menampung sampai 1.000 nomor dan message_delay_ms bergerak dari 0 sampai 30000 milidetik.
Endpoint lain yang tersedia
| Path | Guna | Catatan |
|---|---|---|
POST /api/v1/public/messages/send |
Kirim satu pesan ke satu nomor | Untuk balasan 1-on-1 |
GET /api/v1/public/phone-numbers |
Daftar nomor pengirim | Ambil whatsapp_phone_number_id |
POST /api/v1/public/templates + /templates/{id}/submit |
Buat dan ajukan template baru ke Meta | Approval lewat Meta, di luar alur kirim |
GET /api/v1/public/broadcast/jobs |
Daftar semua broadcast job | Filter status dan paging (limit, offset) |
GET /api/v1/public/conversations/{id}/messages |
Riwayat percakapan | Konteks CRM |
