Pesan - Dokumentasi BGWA

Kirim pesan teks atau gambar, variasikan isi dengan spintax, kirim OTP, dan cek status pesan.

Kirim pesan

POST https://bgwa.web.id/api/v1/messages

Memasukkan satu pesan ke antrean pengiriman. Mendukung teks saja, atau gambar dengan teks sebagai keterangan.

Parameter

Field	Tipe	Keterangan
`to` wajib	string, maks. 30	Nomor tujuan. Boleh diawali `08`, `62`, atau `+62`; spasi dan tanda hubung diabaikan. Contoh: `081234567890`.
`text` wajib	string, maks. 4000	Isi pesan. Mendukung spintax dan variabel. Bila disertai gambar, teks menjadi keterangan gambar.
`image` opsional	file	Gambar JPG, PNG, atau WebP, maksimal 2 MB. Kirim sebagai `multipart/form-data`.
`vars` opsional	objek	Nilai untuk variabel `{nama}` di dalam `text`. Hanya nilai skalar (teks/angka).
`type` opsional	string	Isi `otp` untuk jalur OTP. Selain itu dianggap pesan biasa.

Format nomor

BGWA menormalkan nomor ke format internasional tanpa tanda plus. Semua contoh di bawah menjadi 6281234567890:

Input yang diterima

081234567890
6281234567890
+62 812-3456-7890
0812 3456 7890

Nomor harus berawalan kode negara Indonesia (62) dengan 8–13 digit setelahnya. Selain itu ditolak dengan 422.

Contoh: teks

cURL

curl -X POST https://bgwa.web.id/api/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "081234567890", "text": "Halo, pesanan Anda sudah kami proses."}'

Node.js

await fetch('https://bgwa.web.id/api/v1/messages', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.BGWA_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    to: '081234567890',
    text: 'Halo, pesanan Anda sudah kami proses.',
  }),
});

Python

requests.post("https://bgwa.web.id/api/v1/messages",
              headers={"Authorization": "Bearer " + API_KEY},
              json={"to": "081234567890", "text": "Halo, pesanan Anda sudah kami proses."})

Contoh: gambar dengan keterangan

Kirim sebagai multipart/form-data. Teks menjadi keterangan gambar dalam satu pesan.

cURL

curl -X POST https://bgwa.web.id/api/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "to=081234567890" \
  -F "text=Struk pembayaran Anda" \
  -F "image=@struk.png"

Node.js

import { openAsBlob } from 'node:fs';

const form = new FormData();
form.append('to', '081234567890');
form.append('text', 'Struk pembayaran Anda');
form.append('image', await openAsBlob('struk.png'), 'struk.png');

await fetch('https://bgwa.web.id/api/v1/messages', {
  method: 'POST',
  headers: { Authorization: 'Bearer ' + process.env.BGWA_API_KEY },
  body: form,
});

Python

with open("struk.png", "rb") as f:
    requests.post("https://bgwa.web.id/api/v1/messages",
                  headers={"Authorization": "Bearer " + API_KEY},
                  data={"to": "081234567890", "text": "Struk pembayaran Anda"},
                  files={"image": ("struk.png", f, "image/png")})

PHP

$ch = curl_init('https://bgwa.web.id/api/v1/messages');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('BGWA_API_KEY')],
    CURLOPT_POSTFIELDS => [
        'to' => '081234567890',
        'text' => 'Struk pembayaran Anda',
        'image' => new CURLFile('struk.png', 'image/png', 'struk.png'),
    ],
]);
echo curl_exec($ch);

Respons sukses

200 OK

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

Field	Keterangan
`ok`	`true` berarti pesan diterima ke antrean, belum tentu sudah sampai.
`status`	`queued` (antre untuk segera dikirim) atau `scheduled` (dijadwalkan nanti, mis. karena batas atau jam malam).
`id`	ID pesan. Simpan untuk cek status dan untuk mencocokkan webhook.
`to`	Nomor tujuan dalam format JID WhatsApp.
`wa_message_id`	ID pesan di WhatsApp. Masih `null` sampai pesan benar-benar terkirim.
`image`	`true` bila gambar ikut dikirim.
`eta_seconds`	Perkiraan detik sampai pesan dikirim. Hanya perkiraan.
`scheduled_for`	Waktu rencana pengiriman (ISO 8601).

Variasi isi pesan (spintax)

Agar setiap pesan tidak identik, tulis alternatif dengan {a|b|c}. BGWA memilih satu secara acak untuk tiap pesan. Variabel {nama} diisi dari objek vars.

Permintaan

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

Hasil yang mungkin diterima penerima:

"Halo Budi, tagihan November sudah terbit."
"Selamat pagi Budi, tagihan November sudah terbit."

Pesan OTP

Tambahkan "type": "otp" untuk kode verifikasi pendek. Pesan OTP mendapat jalur khusus: jeda lebih pendek, didahulukan dari antrean biasa, dan tidak tertahan jam malam.

Permintaan

{
  "to": "081234567890",
  "type": "otp",
  "text": "Kode verifikasi Anda: 482913. Berlaku 5 menit. Jangan bagikan ke siapa pun."
}

Cek status pesan

GET https://bgwa.web.id/api/v1/messages/{id}

Mengambil status satu pesan milik device Anda berdasarkan id dari respons pengiriman.

cURL

curl https://bgwa.web.id/api/v1/messages/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

200 OK

{
  "id": 123,
  "status": "sent",
  "to": "6281234567890@s.whatsapp.net",
  "wa_message_id": "3EB0A1B2C3D4",
  "reason": null,
  "queued_at": "2026-11-03T03:00:00+00:00",
  "scheduled_for": "2026-11-03T03:00:24+00:00",
  "sent_at": "2026-11-03T03:00:26+00:00"
}

Nilai status

Status	Arti	Final?
`queued`	Menunggu giliran dikirim.	Tidak
`scheduled`	Dijadwalkan pada `scheduled_for` (mis. menunggu batas harian atau jam malam).	Tidak
`sending`	Sedang dikirim ke WhatsApp.	Tidak
`sent`	Diterima server WhatsApp. Belum berarti sudah dibaca penerima.	Ya
`failed`	Gagal dan tidak dicoba lagi. Lihat `reason`.	Ya
`cancelled`	Dibatalkan sebelum dikirim. Lihat `reason`.	Ya

Nilai reason

Hanya terisi untuk failed dan cancelled.

Reason	Arti
`not_on_whatsapp`	Nomor tujuan tidak terdaftar di WhatsApp.
`send_failed`	WhatsApp menolak atau pengiriman gagal setelah dicoba.
`expired`	Pesan tertahan terlalu lama di antrean sehingga dibuang.
`recipient_opted_out`	Penerima membalas STOP/berhenti.
`account_inactive`	Langganan berakhir atau akun disuspend saat pesan masih antre.

Jika id tidak ditemukan atau bukan milik device Anda, API menjawab 404.