Dokumentasi API

REST API untuk mengirim pesan, membaca inbox, dan menerima webhook. Semua contoh bisa langsung dicoba dengan API key Anda.

Mulai cepat

  1. Daftar dan verifikasi email.
  2. Menu Device → Tambah device → scan QR dari WhatsApp di HP.
  3. Menu API Keys → Buat key. Simpan, key hanya tampil sekali.
  4. 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)

InputKeterangan
08123456789Otomatis jadi 628123456789
628123456789Format internasional tanpa +
120363xxxx@g.usID grup WhatsApp

POST/messages/text

FieldTipeWajibKeterangan
tostringNomor tujuan
messagestringMaks 4096 karakter. Mendukung *tebal* _miring_ ~coret~
device_idintDevice pengirim. Kosong = device terhubung pertama
device_external_idstringPilih device pengirim lewat external_id Anda (alternatif device_id)
typing_timeint (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

FieldTipeWajibKeterangan
tostring
image_urlurlURL publik JPG/PNG
captionstringMaks 1024 karakter
device_id, typing_timeSama seperti teks
{ "to": "08123456789", "image_url": "https://cdn.toko.com/promo.jpg", "caption": "Promo minggu ini" }

POST/messages/document

FieldTipeWajibKeterangan
tostring
document_urlurlURL publik file
filenamestringNama file yang tampil di WhatsApp
mimetypestringDefault application/pdf
captionstring
{
  "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

  1. POST /devices dengan external_id milik Anda (mis. id pelanggan). Aman dipanggil berulang: kalau sudah ada, device yang sama dikembalikan.
  2. Tampilkan QR dengan salah satu cara: buka link scan (connect_link: true), embed link itu sebagai iframe, atau ambil gambar QR sendiri dari GET /devices/{id}/qr tiap 3 detik.
  3. Begitu discan, webhook device.status dengan status: "connected" dikirim ke webhook_url, dan link scan mengarahkan ke return_url.
  4. Kirim pesan dengan device_external_id sehingga Anda tidak perlu menyimpan id device kami.

POST/devices

FieldTipeWajibKeterangan
namestringYaNama device, maks 60 karakter
external_idstringID di sistem Anda, unik per akun. Huruf, angka, . _ : -, maks 100
metadataobjectData bebas milik Anda, maks 4 KB
webhook_urlurlPenerima event device.status & message. Secret dikembalikan di respons
connect_linkboolSekalian buat link scan
return_urlurlTujuan setelah scan berhasil. Ditambah status, device_id, external_id
link_expires_inintMasa 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

EndpointFungsi
GET/devicesDaftar device. Filter ?external_id= dan ?status=
GET/devices/{id}Detail satu device
PATCH/devices/{id}Ubah name, external_id, metadata
POST/devices/{id}/connectMulai ulang session (QR baru)
POST/devices/{id}/logoutKeluarkan 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/testKirim event test ke webhook
DELETE/devices/{id}Logout WhatsApp & hapus device
statusArti
connectedSiap kirim
connectingSedang menyambung, coba lagi beberapa detik
qr_readyMenunggu scan QR
disconnectedTerputus; 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.

HeaderIsi
X-Webhook-Eventmessage, device.status, message.transcript, payment.proof, atau test
X-Webhook-DeliveryUUID unik per event. Simpan untuk mencegah proses ganda saat retry.
X-Webhook-Signaturesha256= + 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}/messages mengembalikan field transcript.
  • 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:

CekHasil 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 depanMencurigakan
Gambar dan nomor referensi belum pernah dipakai di bukti lainMencurigakan
Status transaksi berhasilMencurigakan
AI melihat tanda gambar diedit, atau data tidak terbacaPerlu 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" }
EndpointFungsi
GET/payments/expectedDaftar tagihan. Filter ?status=pending|matched|cancelled, ?reference=
DELETE/payments/expected/{id}Batalkan tagihan
GET/payment-proofsDaftar 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

HTTPArtiRetry?
401API key tidak ada / tidak validTidak
402Paket tidak aktif atau device melebihi limit paketTidak, perpanjang paket
403Email akun belum diverifikasiTidak
404Device tidak ditemukan / tidak ada device terhubungTidak
409Device belum terhubungYa, setelah device connected
422Validasi gagal atau nomor tidak validTidak
429Rate limit terlampaui, atau kuota pesan bulan ini habis (lihat message)Rate limit: ya, dengan jeda. Kuota: tidak, upgrade paket
502 / 503Gateway WhatsApp sedang tidak tersediaYa, 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.