Kirim pesan WhatsApp lewat API

Cara mulai

1. Langganan paket di BGWA dan pastikan saldo dompet cukup.
2. Tambah device, lalu scan QR WhatsApp di menu Device.
3. Buka menu Device, klik ikon kunci pada device, lalu salin API key.
4. Pakai API key itu di server atau website Anda, seperti contoh di bawah.

Endpoint

Semua request wajib memakai header Authorization: Bearer <API_KEY>. Batas: 60 request per menit per API key.

Contoh: kirim pesan

curl -X POST https://bgwa.my.id/api/v1/messages \
  -H "Authorization: Bearer bgwa_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"to": "6281234567890", "text": "Halo dari website saya"}'

Nomor tujuan boleh diawali 08 atau 62.

Contoh respons

{"ok": true, "status": "queued", "id": 123, "to": "6281234567890@s.whatsapp.net",
 "wa_message_id": null, "eta_seconds": 24, "scheduled_for": "2026-11-03T03:00:00+00:00"}

Pesan diterima dan masuk antrean, lalu dikirim bertahap (lihat bagian di bawah). Jawaban ok: true berarti pesan diterima, bukan berarti sudah sampai. status bernilai queued atau scheduled (dijadwalkan nanti). Simpan id untuk memeriksa hasilnya.

Cek status pesan

curl https://bgwa.my.id/api/v1/messages/123 -H "Authorization: Bearer bgwa_xxxxxxxxxxxxxxxx"

{"id": 123, "status": "sent", "to": "6281234567890@s.whatsapp.net", "wa_message_id": "3EB0...",
 "reason": null, "queued_at": "...", "scheduled_for": "...", "sent_at": "..."}

Nilai status: queued, scheduled, sending, sent, failed, cancelled. Untuk failed/cancelled, reason menjelaskan sebabnya (misalnya not_on_whatsapp).

Cara BGWA mengirim pesan

Untuk melindungi nomor WhatsApp Anda dari pemblokiran, BGWA tidak menembakkan pesan sekaligus. Pesan dikirim satu per satu dengan jeda acak, indikator "sedang mengetik", dan istirahat berkala, seperti orang memakai WhatsApp. Karena itu pesan bisa tiba beberapa detik sampai beberapa menit setelah request, tergantung panjang antrean.

• Ada batas harian dan per jam untuk penerima baru (nomor yang belum pernah membalas). Device baru dibatasi lebih rendah dan naik bertahap.
• Pesan yang sama ke nomor yang sama dalam 10 menit ditolak, begitu juga teks identik ke banyak penerima baru. Variasikan isi pesan.
• Maksimal 2 tautan per pesan. Penerima yang membalas STOP atau berhenti tidak akan dikirimi lagi.
• Nomor yang tidak terdaftar di WhatsApp tidak dikirimi (status failed).

Variasi isi pesan

{"to": "081234567890",
 "text": "{Halo|Hai|Selamat pagi} {nama}, tagihan Anda sudah terbit.",
 "vars": {"nama": "Budi"}}

Bagian {a|b|c} dipilih acak per pesan, dan {nama} diisi dari vars.

Pesan OTP

Tambahkan "type": "otp" untuk kode verifikasi pendek: dikirim lebih dulu, tanpa tahanan jam malam. Maksimal 200 karakter, tanpa tautan, dan jumlahnya dibatasi per jam.

Webhook hasil pengiriman

Karena pesan dikirim bertahap, BGWA dapat memberi tahu server Anda saat hasil akhirnya diketahui, sehingga Anda tidak perlu memeriksa status satu per satu. Atur URL webhook sekali:

curl -X PUT https://bgwa.my.id/api/v1/webhook \
  -H "Authorization: Bearer bgwa_xxxxxxxxxxxxxxxx" -H "Content-Type: application/json" \
  -d '{"url": "https://situs-anda.com/hooks/bgwa"}'

{"ok": true, "url": "https://situs-anda.com/hooks/bgwa", "secret_set": true, "secret": "whsec_..."}

secret hanya ditampilkan sekali (saat pertama dibuat atau diganti lewat POST /api/v1/webhook/secret). Simpan untuk memverifikasi tanda tangan. Kirim POST /api/v1/webhook/test untuk menerima event ping uji, dan GET /api/v1/webhook untuk melihat 10 pengiriman terakhir.

Event

• message.sent: pesan sudah diterima server WhatsApp (belum berarti dibaca penerima).
• message.failed: pesan gagal dan tidak akan dicoba lagi (mis. send_failed, not_on_whatsapp, expired).
• message.cancelled: pesan dibatalkan (mis. recipient_opted_out, account_inactive).

POST https://situs-anda.com/hooks/bgwa
X-BGWA-Event: message.sent
X-BGWA-Delivery: 7d1f0c0e-....   (id unik; pakai untuk membuang duplikat)
X-BGWA-Timestamp: 1793626030
X-BGWA-Signature: sha256=3b7f...

{"event": "message.sent", "id": 123, "status": "sent", "to": "6281234567890",
 "wa_message_id": "3EB0...", "reason": null, "error": null, "attempts": 1,
 "queued_at": "...", "sent_at": "...", "device": {"id": 4, "name": "mynet"},
 "delivery_id": "7d1f0c0e-..."}

Verifikasi tanda tangan

// PHP
$ts   = $_SERVER['HTTP_X_BGWA_TIMESTAMP'];
$body = file_get_contents('php://input');
$sig  = 'sha256=' . hash_hmac('sha256', $ts . '.' . $body, $secret);
if (! hash_equals($sig, $_SERVER['HTTP_X_BGWA_SIGNATURE'])) { http_response_code(401); exit; }

• Tolak permintaan bila X-BGWA-Timestamp terlalu lama (misalnya lebih dari 5 menit) untuk mencegah pemutaran ulang.
• Jawab dengan status 2xx secepatnya. Selain 2xx, BGWA mengulang hingga 7 kali dengan jeda 30 detik, 2 menit, 10 menit, 30 menit, 2 jam, lalu 6 jam. Pengiriman bisa terjadi lebih dari sekali; gunakan delivery_id untuk membuang duplikat.
• Syarat URL: https dengan port 443 atau 8443, domain publik. Alamat internal/privat ditolak, dan redirect tidak diikuti.
• Isi pesan tidak dikirim lewat webhook.

Kode error

Respons error berisi error (penjelasan) dan, untuk penolakan penjaga, reason serta retry_after (detik) bila relevan.

• 401 API key salah atau dicabut
• 403 langganan tidak aktif atau akun disuspend
• 409 device belum terhubung
• 422 nomor tidak valid, pesan duplikat, isi terlalu seragam, terlalu banyak tautan, atau penerima berhenti
• 429 kuota habis, batas penerima baru tercapai, atau antrean penuh
• 503 pengiriman device dijeda sementara

Paket

Harga dan kuota bisa berubah. Lihat daftar paket terbaru di dashboard setelah login.