Mulai cepat
- Daftar dan verifikasi email.
- Menu Device → Tambah device → scan QR dari WhatsApp di HP.
- Menu API Keys → Buat key. Simpan, key hanya tampil sekali.
- Kirim pesan:
curl -X POST https://watsapbro.com/api/v1/messages/text \
-H "Authorization: Bearer wsb_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"to":"08123456789","message":"Halo dari WatsapBro"}'
Base URL: https://watsapbro.com/api/v1. Semua request dan response memakai JSON.
Autentikasi
Kirim API key di header Authorization: Bearer <API_KEY> (atau X-Api-Key: <API_KEY>). Rate limit: 60 request/menit per API key.
Format response selalu:
{ "success": true, "message": "...", "data": { ... } }
Bahasa message: Indonesia secara default. Tambahkan ?lang=en di URL untuk pesan bahasa Inggris, atau ganti bahasa akun di dashboard (tombol ID / EN) supaya semua respons API akun itu memakai bahasa tersebut.
Format nomor tujuan (to)
| Input | Keterangan |
|---|---|
08123456789 | Otomatis jadi 628123456789 |
628123456789 | Format internasional tanpa + |
120363xxxx@g.us | ID grup WhatsApp |
POST/messages/text
| Field | Tipe | Wajib | Keterangan |
|---|---|---|---|
to | string | Nomor tujuan | |
message | string | Maks 4096 karakter. Mendukung *tebal* _miring_ ~coret~ | |
device_id | int | Device pengirim. Kosong = device terhubung pertama | |
device_external_id | string | Pilih device pengirim lewat external_id Anda (alternatif device_id) | |
typing_time | int (ms) | Tampilkan "sedang mengetik" sebelum kirim, 0–10000 |
{
"to": "08123456789",
"message": "*Pembayaran diterima*\nInvoice INV-001 sebesar Rp150.000 sudah lunas.",
"typing_time": 1500
}
Response 200:
{
"success": true,
"message": "Pesan terkirim.",
"quota_remaining": 1874,
"data": { "log_id": 1024, "message_id": "3EB0B430A2B52B67D0", "device_id": 3, "to": "08123456789" }
}
quota_remaining = sisa kuota bulan ini, null kalau paket unlimited.
POST/messages/image
| Field | Tipe | Wajib | Keterangan |
|---|---|---|---|
to | string | ||
image_url | url | URL publik JPG/PNG | |
caption | string | Maks 1024 karakter | |
device_id, typing_time | Sama seperti teks |
{ "to": "08123456789", "image_url": "https://cdn.toko.com/promo.jpg", "caption": "Promo minggu ini" }
POST/messages/document
| Field | Tipe | Wajib | Keterangan |
|---|---|---|---|
to | string | ||
document_url | url | URL publik file | |
filename | string | Nama file yang tampil di WhatsApp | |
mimetype | string | Default application/pdf | |
caption | string |
{
"to": "08123456789",
"document_url": "https://app.toko.com/invoice/INV-001.pdf",
"filename": "INV-001.pdf",
"caption": "Invoice Oktober"
}
POST/numbers/check
Cek apakah nomor terdaftar di WhatsApp sebelum mengirim.
{ "phone": "08123456789", "device_id": 3 }
Device & scan QR dari aplikasi Anda
Platform Anda bisa membuat device, menampilkan QR, dan tahu kapan nomor terhubung tanpa pengguna Anda membuka dashboard WatsapBro. Cocok untuk SaaS yang tiap pelanggannya memakai nomor WhatsApp sendiri.
Akun & paket. Pelanggan di platform Anda tidak perlu akun WatsapBro. Semua nomor mereka menjadi device di bawah akun Anda dan memakai limit device serta kuota pesan paket Anda (pantau lewat GET /me). Untuk ratusan nomor, hubungi kami untuk paket integrasi.
Di semua endpoint device, {id} boleh berupa id angka atau ext:<external_id>, mis. /devices/ext:rt-12/qr.
Alur yang disarankan
POST /devicesdenganexternal_idmilik Anda (mis. id pelanggan). Aman dipanggil berulang: kalau sudah ada, device yang sama dikembalikan.- Tampilkan QR dengan salah satu cara: buka link scan (
connect_link: true), embed link itu sebagai iframe, atau ambil gambar QR sendiri dariGET /devices/{id}/qrtiap 3 detik. - Begitu discan, webhook
device.statusdenganstatus: "connected"dikirim kewebhook_url, dan link scan mengarahkan kereturn_url. - Kirim pesan dengan
device_external_idsehingga Anda tidak perlu menyimpan id device kami.
POST/devices
| Field | Tipe | Wajib | Keterangan |
|---|---|---|---|
name | string | Ya | Nama device, maks 60 karakter |
external_id | string | ID di sistem Anda, unik per akun. Huruf, angka, . _ : -, maks 100 | |
metadata | object | Data bebas milik Anda, maks 4 KB | |
webhook_url | url | Penerima event device.status & message. Secret dikembalikan di respons | |
connect_link | bool | Sekalian buat link scan | |
return_url | url | Tujuan setelah scan berhasil. Ditambah status, device_id, external_id | |
link_expires_in | int | Masa berlaku link scan dalam menit, 5–1440 (default 30) |
curl -X POST https://watsapbro.com/api/v1/devices \
-H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
-d '{"name":"RT 05 Melati","external_id":"rt-5","webhook_url":"https://app-anda.com/webhooks/wa",
"connect_link":true,"return_url":"https://app-anda.com/pengaturan/whatsapp"}'
HTTP 201
{
"success": true,
"created": true,
"data": {
"id": 41, "name": "RT 05 Melati", "external_id": "rt-5", "status": "connecting",
"phone": null, "webhook_url": "https://app-anda.com/webhooks/wa",
"webhook_secret": "whsec_…",
"qr_url": "https://watsapbro.com/api/v1/devices/41/qr",
"connect_link": { "url": "https://watsapbro.com/connect/wcl_…", "expires_at": "2026-10-23T10:30:00+07:00" }
}
}
Dengan external_id yang sudah ada, respons 200 dan "created": false. Kalau batas device paket tercapai, respons 402.
GET/devices/{id}/qr
Status terbaru + QR (PNG base64). Device yang terputus otomatis dihubungkan ulang, jadi QR baru muncul sendiri. Panggil tiap refresh_in detik sampai status = connected; QR berganti ±20 detik. Tambah ?format=png untuk menerima gambar langsung.
{
"success": true,
"data": {
"device_id": 41, "external_id": "rt-5", "status": "qr_ready", "label": "Perlu scan QR",
"phone": null, "qr": "data:image/png;base64,iVBORw0…", "qr_base64": "iVBORw0…", "refresh_in": 3
}
}
Link scan (tanpa login)
POST/devices/{id}/connect-link dengan return_url dan expires_in (menit) opsional menghasilkan URL halaman scan bermerek. Halaman ini bisa dibuka langsung, di-redirect, atau di-embed dengan ?embed=1:
<iframe src="https://…/connect/wcl_…?embed=1" style="width:100%;height:460px;border:0"></iframe>
<script>
window.addEventListener('message', function (e) {
if (e.data && e.data.source === 'watsapbro' && e.data.status === 'connected') {
location.reload(); // nomor sudah terhubung
}
});
</script>
Link baru membatalkan link lama, dan link berhenti berlaku 5 menit setelah nomor terhubung. DELETE/devices/{id}/connect-link untuk membatalkan lebih awal. Jangan bagikan link ke orang yang tidak berhak, karena siapa pun yang memegangnya bisa menautkan nomornya ke device ini.
Endpoint device lainnya
| Endpoint | Fungsi |
|---|---|
GET/devices | Daftar device. Filter ?external_id= dan ?status= |
GET/devices/{id} | Detail satu device |
PATCH/devices/{id} | Ubah name, external_id, metadata |
POST/devices/{id}/connect | Mulai ulang session (QR baru) |
POST/devices/{id}/logout | Keluarkan WhatsApp dari device; device tetap ada untuk discan nomor lain |
PUT/devices/{id}/webhook | {"url": "...", "rotate_secret": true}, atau {"url": null} untuk mematikan. Mengembalikan webhook_secret |
POST/devices/{id}/webhook/test | Kirim event test ke webhook |
DELETE/devices/{id} | Logout WhatsApp & hapus device |
| status | Arti |
|---|---|
connected | Siap kirim |
connecting | Sedang menyambung, coba lagi beberapa detik |
qr_ready | Menunggu scan QR |
disconnected | Terputus; sistem reconnect otomatis, atau scan ulang kalau WhatsApp di HP logout |
GET/me
Info akun: paket, tanggal berakhir, limit device, dan pemakaian kuota bulan ini. Kuota dihitung dari pesan yang berhasil terkirim (API, broadcast, dan pesan tes) dan direset tiap tanggal 1.
{
"success": true,
"data": {
"name": "Toko Budi",
"email": "budi@toko.com",
"plan": "Starter",
"plan_expires_at": "2026-11-17T10:00:00+07:00",
"device_limit": 1,
"devices": 1,
"can_add_device": false,
"quota_monthly": 2000,
"quota_used": 126,
"quota_remaining": 1874
}
}
Webhook pesan masuk
Isi URL webhook di halaman detail device (menu Device). WatsapBro mengirim POST JSON ke URL tersebut setiap ada pesan masuk ke nomor itu, dan saat status device berubah. Pesan yang Anda kirim sendiri tidak diteruskan.
| Header | Isi |
|---|---|
X-Webhook-Event | message, device.status, message.transcript, payment.proof, atau test |
X-Webhook-Delivery | UUID unik per event. Simpan untuk mencegah proses ganda saat retry. |
X-Webhook-Signature | sha256= + HMAC-SHA256 dari raw body memakai signing secret device |
Contoh body event message:
{
"event": "message",
"delivery_id": "6f1c2a0e-6c1e-4b0a-9a51-2d0f0b8e7c11",
"device": { "id": 3, "external_id": "rt-5", "name": "CS Toko", "phone": "628123456789", "status": "connected" },
"data": {
"id": "3EB0C767D26A8B4E1F",
"from": "6281298765432@c.us",
"text": "Halo, pesanan saya sudah dikirim?",
"timestamp": 1760668200
},
"timestamp": "2026-10-17T10:30:00+07:00"
}
Event device.status berisi data.status, data.previous, dan data.phone (nilai status sama dengan tabel status device di atas). Webhook bisa diatur di dashboard atau lewat API (webhook_url saat membuat device / PUT /devices/{id}/webhook).
Balas HTTP 2xx dalam 10 detik. Kalau URL Anda timeout, membalas 5xx, atau 429, event dikirim ulang hingga 4 kali (10 detik, 1 menit, 5 menit, 15 menit). Balasan 4xx lain dianggap ditolak dan tidak dikirim ulang. Proses berat sebaiknya dimasukkan ke queue di aplikasi Anda.
Verifikasi signature
// Laravel
$raw = $request->getContent();
$expected = 'sha256=' . hash_hmac('sha256', $raw, env('WEBHOOK_SECRET'));
abort_unless(hash_equals($expected, (string) $request->header('X-Webhook-Signature')), 401);
$event = $request->json('event');
if ($event === 'message') {
$from = $request->json('data.from'); // 6281298765432@c.us
$text = $request->json('data.text');
}
// Go
func verify(body []byte, sig, secret string) bool {
mac := hmac.New(sha256.New, []byte(secret))
mac.Write(body)
expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))
return hmac.Equal([]byte(expected), []byte(sig))
}
// Node.js (Express: pakai express.raw({ type: 'application/json' }))
const crypto = require('crypto');
const expected = 'sha256=' + crypto.createHmac('sha256', process.env.WEBHOOK_SECRET).update(req.body).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.get('X-Webhook-Signature') || ''));
GET/conversations
Daftar percakapan inbox (urut terbaru). Query opsional: device_id, unread=1, needs_human=1, per_page (maks 100), page.
{
"success": true,
"data": [
{ "id": 41, "device_id": 3, "chat_id": "6281298765432@s.whatsapp.net", "name": "Sari", "phone": "6281298765432",
"is_group": false, "unread": 2, "needs_human": false, "ai": "on",
"last_message": "Masih ada stok ukuran M?", "last_message_at": "2026-10-18T09:12:00+07:00" }
],
"meta": { "page": 1, "per_page": 30, "total": 128 }
}
GET/conversations/{id}/messages
Pesan dalam percakapan, urut lama ke baru. Query: limit (maks 100), before_id untuk halaman sebelumnya. Field source: contact (dari pelanggan), ai, autoreply, api, broadcast, dashboard, phone.
AI & auto reply
Balasan otomatis diatur dari dashboard, tidak perlu kode: Auto Reply (kata kunci) diperiksa dulu, lalu AI Agent yang dipasang di device. AI memakai API key milik Anda (OpenAI, Anthropic, Gemini, Groq, DeepSeek, OpenRouter, atau endpoint OpenAI-compatible) dan membaca Knowledge Base Anda. Balasan otomatis tercatat di inbox (bisa dibaca lewat /conversations) dan terhitung kuota pesan.
Otomasi berhenti sementara untuk sebuah chat ketika Anda membalas manual dari inbox atau dari HP, dan ketika pelanggan meminta CS manusia (handover).
Voice note dibaca AI
Nyalakan Baca voice note di AI agent. Pesan suara pelanggan ditranskrip memakai OpenAI Whisper, Groq Whisper, atau Gemini, lalu dijawab AI dan dicek aturan kata kunci seperti pesan teks biasa. Transkrip juga tampil di inbox.
- Webhook menerima event
message.transcript:{"message_id": "…", "chat_id": "…", "from": "62812…", "transcript": "…"}. GET /conversations/{id}/messagesmengembalikan fieldtranscript.- Provider utama tidak mendukung audio (mis. Claude)? Isi AI khusus suara & gambar di agent, mis. Groq yang murah.
Cek bukti transfer
Nyalakan Cek bukti transfer di AI agent dan isi rekening tujuan Anda. Setiap foto yang dikirim pelanggan dibaca AI. Kalau isinya bukti transfer, sistem mengecek:
| Cek | Hasil kalau tidak cocok |
|---|---|
Penerima adalah salah satu rekening Anda (nomor tersamar seperti ****7890 tetap dikenali) | Mencurigakan |
Nominal sama dengan tagihan (dari POST /payments/expected, atau "Total Rp…" terakhir yang Anda kirim di chat) | Mencurigakan |
| Tanggal transaksi tidak lebih lama dari batas (default 72 jam) dan tidak di masa depan | Mencurigakan |
| Gambar dan nomor referensi belum pernah dipakai di bukti lain | Mencurigakan |
| Status transaksi berhasil | Mencurigakan |
| AI melihat tanda gambar diedit, atau data tidak terbaca | Perlu dicek |
Pelanggan otomatis dibalas "bukti sudah kami terima, sedang kami cek". Chat yang mencurigakan atau perlu dicek ditandai Butuh CS. Status akhir: valid (Cocok), review (Perlu dicek), suspicious (Mencurigakan), lalu confirmed / rejected setelah Anda memutuskan. Screenshot bisa dipalsukan, jadi hasil "Cocok" bukan pengganti cek mutasi rekening.
POST/payments/expected
Daftarkan tagihan supaya nominal bukti transfer dari nomor itu dicocokkan. Memanggil ulang dengan reference yang sama akan memperbarui tagihan yang masih menunggu.
{ "phone": "08123456789", "amount": 475000, "reference": "INV-2291", "description": "2 kain batik", "expires_in_days": 7, "device_external_id": "toko-1" }
| Endpoint | Fungsi |
|---|---|
GET/payments/expected | Daftar tagihan. Filter ?status=pending|matched|cancelled, ?reference= |
DELETE/payments/expected/{id} | Batalkan tagihan |
GET/payment-proofs | Daftar bukti. Filter ?status=open|valid|review|suspicious|confirmed|rejected, ?phone=, ?since=2026-10-01 |
GET/payment-proofs/{id} | Detail bukti termasuk hasil setiap cek |
POST/payment-proofs/{id}/review | {"decision": "confirmed" | "rejected", "note": "…"} setelah Anda cek mutasi |
Webhook menerima event payment.proof saat bukti baru masuk dan saat diputuskan:
{
"event": "payment.proof",
"data": {
"id": 88, "status": "suspicious", "label": "Mencurigakan", "phone": "6281234567890",
"bank": "BCA", "amount": 200000, "expected_amount": 250000, "reference": "REF006",
"recipient_name": "TOKO LARAS", "recipient_account": "1234567890", "paid_at": "2026-10-24T18:02:00+07:00",
"checks": [ { "code": "amount", "ok": false, "label": "Nominal Rp200.000, seharusnya Rp250.000" }, … ],
"expected_payment": { "id": 12, "reference": "INV-77", "amount": 250000 }
}
}
Kode error
| HTTP | Arti | Retry? |
|---|---|---|
| 401 | API key tidak ada / tidak valid | Tidak |
| 402 | Paket tidak aktif atau device melebihi limit paket | Tidak, perpanjang paket |
| 403 | Email akun belum diverifikasi | Tidak |
| 404 | Device tidak ditemukan / tidak ada device terhubung | Tidak |
| 409 | Device belum terhubung | Ya, setelah device connected |
| 422 | Validasi gagal atau nomor tidak valid | Tidak |
| 429 | Rate limit terlampaui, atau kuota pesan bulan ini habis (lihat message) | Rate limit: ya, dengan jeda. Kuota: tidak, upgrade paket |
| 502 / 503 | Gateway WhatsApp sedang tidak tersedia | Ya, backoff 1s, 4s, 9s |
Contoh kode
Laravel
use Illuminate\Support\Facades\Http;
$res = Http::withToken(env('API_KEY'))
->retry(3, 1000, fn ($e) => $e instanceof \Illuminate\Http\Client\ConnectionException
|| in_array(optional($e->response)->status(), [409, 429, 502, 503]))
->post('https://watsapbro.com/api/v1/messages/text', [
'to' => '08123456789',
'message' => 'Kode OTP Anda: 482910',
]);
if (! $res->json('success')) {
logger()->error('WA gagal', $res->json());
}
Go
body, _ := json.Marshal(map[string]any{"to": "08123456789", "message": "Halo dari Go"})
req, _ := http.NewRequest("POST", "https://watsapbro.com/api/v1/messages/text", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+os.Getenv("API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
Node.js
const res = await fetch("https://watsapbro.com/api/v1/messages/text", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ to: "08123456789", message: "Halo dari Node" }),
});
const json = await res.json();
PHP native
$ch = curl_init('https://watsapbro.com/api/v1/messages/text');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('API_KEY'), 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode(['to' => '08123456789', 'message' => 'Halo']),
]);
$result = json_decode(curl_exec($ch), true);
Tips supaya nomor tidak diblokir
- Untuk kirim massal, pakai menu Broadcast (upload CSV, jeda acak otomatis) daripada loop API tanpa jeda.
- Pakai nomor khusus (sebaiknya WhatsApp Business), bukan nomor pribadi.
- Kirim ke orang yang memang kenal Anda: pelanggan, member, user aplikasi.
- Untuk banyak penerima, beri jeda minimal 3–5 detik antar pesan dan pakai
typing_time. - Hindari pesan identik ke ratusan nomor sekaligus; personalisasi dengan nama.
- Buka WhatsApp di HP utama minimal sekali tiap 2 minggu.
- Kirim lewat queue di aplikasi Anda, jangan di request user secara langsung.