📘 Panduan API — WA Gateway

API untuk mengirim pesan WhatsApp dan memantau statusnya. Semua endpoint mengembalikan JSON.

★ Titip ke antrian (disarankan) Status koneksi & health Tampilkan QR Kirim teks Kirim file Kirim gambar Daftar & kirim ke grup Status terkirim/diterima/dibaca Statistik

★ Cara disarankan: titip pesan ke antrian (outbox)

Titip 1 pesan

# tagihan + PDF
curl -X POST http://localhost:3600/api/enqueue \
  -H "X-API-Key: KEY" \
  -F "to=08123456789" \
  -F "text=Tagihan SPP Juli 2026 an. Medina" \
  -F "client_ref=IU-SD-072026-00039" \
  -F "file=@tagihan-medina.pdf"

{ "message_id": 1201, "client_ref": "IU-SD-072026-00039", "status": "queued" }
# kirim ulang dengan client_ref sama → { ..., "status":"queued", "dedup": true }  (tidak dikirim dobel)

Nomor pengirim tidak Anda tentukan — gateway memilih otomatis nomor yang healthy & di bawah kuota, bergiliran, dengan jeda acak. Nomor tujuan yang ternyata tidak punya WhatsApp otomatis berstatus invalid (tidak dikirim).

Cek status (polling)

curl -X POST http://localhost:3600/api/status \
  -H "X-API-Key: KEY" -H "Content-Type: application/json" \
  -d '{ "refs": ["IU-SD-072026-00039","IU-SD-072026-00040"] }'

{ "messages": [
  { "client_ref":"IU-SD-072026-00039", "status":"delivered", "sender":"628123456789",
    "sent_at":"...", "delivered_at":"...", "read_at":null },
  { "client_ref":"IU-SD-072026-00040", "status":"queued", "sender":"" }
]}

Status: queued → processing → sent → delivered → read, atau failed / undelivered / invalid. Sukses = delivered (sampai HP).

Ringkasan antrian

curl -H "X-API-Key: KEY" http://localhost:3600/api/queue/summary
# → { "queued":12, "processing":1, "sent":2, "delivered":683, "read":40, "undelivered":3, "failed":1, "invalid":5 }

1. Status nomor: connected / disconnected / health

Daftar semua nomor milik Anda beserta status koneksi dan kesehatannya.

curl -H "X-API-Key: KEY" http://localhost:3600/api/senders

[
  {
    "number": "628123456789",
    "label": "Bendahara 1",
    "status": "connected",       // connected | disconnected | connecting | banned | logged_out
    "health": "healthy",         // healthy | degraded | quarantined | banned | unknown
    "daily_count": 42,
    "max_per_day": 150,
    "delivered": 40,             // total pesan sampai ke penerima
    "undelivered": 2,            // total gagal sampai (indikasi bermasalah)
    "last_error": ""
  }
]

2. Tambah nomor & tampilkan QR Code

Mulai pairing (dibatasi kuota nomor Anda), lalu tampilkan QR untuk di-scan di HP (WhatsApp → Perangkat Tertaut).

# 1) mulai
curl -X POST -H "X-API-Key: KEY" http://localhost:3600/api/pair
# → { "pair_id": "abc123", "status": "pending" }

# 2) tampilkan gambar QR (PNG) — pasang di <img>
http://localhost:3600/api/pair/abc123/qr.png?apikey=KEY

# 3) cek status sampai "connected"
curl -H "X-API-Key: KEY" http://localhost:3600/api/pair/abc123
# → { "status": "connected", "number": "628123456789", "has_qr": false }

<!-- contoh di HTML -->
<img src="http://localhost:3600/api/pair/abc123/qr.png?apikey=KEY">

3. Kirim pesan teks

from = nomor pengirim (salah satu nomor client Anda) — disarankan diisi agar aplikasi Anda yang mengatur nomor mana yang dipakai. Jika dikosongkan, gateway auto-pilih nomor tersehat. to menerima 08…, 62…, atau +62….

curl -X POST http://localhost:3600/api/send \
  -H "X-API-Key: KEY" -H "Content-Type: application/json" \
  -d '{
    "from": "628123456789",
    "to": "08123456789",
    "text": "Halo, ini pesan uji coba"
  }'

{ "message_id": 101, "wa_id": "3EB0...", "sender": "628123456789", "status": "sent" }

4. Kirim file (PDF/dokumen)

Tiga cara: unggah langsung (multipart), base64, atau URL.

a. Multipart (unggah file)

curl -X POST http://localhost:3600/api/send/file \
  -H "X-API-Key: KEY" \
  -F "to=08123456789" \
  -F "caption=Tagihan SPP Juli 2026" \
  -F "file=@tagihan.pdf"

b. Base64 (JSON)

{
  "to": "08123456789",
  "file_name": "tagihan.pdf",
  "mime": "application/pdf",
  "caption": "Tagihan SPP",
  "data": "JVBERi0xLjcK..."   // isi file dalam base64
}

c. Dari URL (JSON)

{
  "to": "08123456789",
  "file_name": "tagihan.pdf",
  "caption": "Tagihan SPP",
  "url": "https://situs-anda.com/tagihan.pdf"
}

5. Kirim gambar

# multipart
curl -X POST http://localhost:3600/api/send/file \
  -H "X-API-Key: KEY" \
  -F "to=08123456789" -F "as_image=true" \
  -F "caption=Brosur PPDB" -F "file=@brosur.jpg"

# atau JSON
{ "to":"0812...", "as_image": true, "caption":"Brosur", "url":"https://.../brosur.jpg" }

5b. Daftar grup & kirim ke grup

Mengembalikan grup yang diikuti sebuah nomor (nomor harus connected). jid adalah kode grup yang dipakai sebagai to untuk mengirim ke grup.

curl -H "X-API-Key: KEY" http://localhost:3600/api/senders/628123456789/groups

[
  { "jid": "120363012345678901@g.us", "name": "Wali Murid Kelas 1", "members": 34 }
]

Kirim pesan/file ke grup: pakai jid grup sebagai to.

curl -X POST http://localhost:3600/api/send \
  -H "X-API-Key: KEY" -H "Content-Type: application/json" \
  -d '{ "from":"628123456789", "to":"120363012345678901@g.us", "text":"Pengumuman untuk grup" }'

6. Status pesan: terkirim / diterima / dibaca

Riwayat pesan (25 per halaman). Filter: status, sender, q (cari), limit, offset.

curl -H "X-API-Key: KEY" \
  "http://localhost:3600/api/messages?status=delivered&limit=25&offset=0"

{
  "total": 120,
  "messages": [
    {
      "id": 101, "sender": "628123456789", "recipient": "628999",
      "type": "document", "body": "tagihan.pdf — Tagihan SPP",
      "status": "read",
      "sent_at": "2026-07-01 10:14:09",
      "delivered_at": "2026-07-01 10:14:12",   // ✅ diterima HP penerima
      "read_at": "2026-07-01 10:20:01"          // ✅ dibaca
    }
  ]
}

7. Statistik & info akun

curl -H "X-API-Key: KEY" http://localhost:3600/api/stats
# → { "total":120, "today":42, "sent":5, "delivered":100, "read":10, "undelivered":3, "failed":2 }

curl -H "X-API-Key: KEY" http://localhost:3600/api/me
# → { "id":2, "name":"SD Cahaya Ilmu", "max_numbers":5, "number_count":3, "is_active":true }

Kelola nomor

Butuh nomor lebih banyak dari kuota? Hubungi super admin untuk menaikkan batas.