WA Gateway API

1. Mulai cepat

1. Buka Admin Panel, login dengan password admin.
2. Klik + Device Baru → beri nama (mis. cs-bot). Simpan device key yang tampil.
3. Pairing — dua cara:
   • QR scan: buka Kelola → tab Koneksi / QR → scan QR dari WhatsApp (Perangkat Tertaut → Tautkan perangkat). QR refresh otomatis tiap 4 detik.
   • Pairing code: masukkan nomor (628xxx) → dapat kode 8 digit → WhatsApp → Perangkat Tertaut → Tautkan dengan nomor telepon.
4. Setelah status connected, device siap dipakai lewat REST API.

Kirim pesan pertama

curl -X POST https://151.245.136.93:8443/api/v1/send \
  -H "X-Device-Key: wag_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"to":"628123456789","type":"text","message":"Halo dari WA Gateway"}'

2. Autentikasi

Semua endpoint /api/v1/* butuh device key. Tiga cara:

X-Device-Key: wag_xxxxxxxxxxxxxxxx      ← disarankan
Authorization: Bearer wag_xxxxxxxxxxxxxxxx
?device_key=wag_xxxxxxxxxxxxxxxx        ← untuk testing cepat

• Key tidak valid → 401
• Device belum connected → 409 (pesannya menyebut status device-nya)
• Key bisa di-rotate dari admin panel → key lama langsung mati

3. Device & pairing (bisa lewat API)

Supaya aplikasimu bisa onboarding nomor sendiri tanpa buka panel.

{
  "success": true,
  "status": "qr",                 // connected | qr | pairing | connecting | reconnecting | disconnected | stopped | logged_out | error
  "connected": false,
  "qr": "data:image/png;base64,iVBOR…",   // tinggal 
  "qr_raw": "2@abc123…",                   // string QR mentah kalau mau generate sendiri
  "qr_expires_in_ms": 12400,
  "pairing_code": null,
  "phone": null
}

curl -X POST .../api/v1/device/pairing-code -H "X-Device-Key: wag_xxx" \
  -d '{"phone":"628123456789"}'
{"success":true,"pairing_code":"V7H7NRKZ","phone":"628123456789"}

4. Kirim pesan — satu endpoint

Semua tipe pesan lewat endpoint ini. Field type menentukan jenisnya — default text.

Parameter

Contoh per tipe

# TEXT (default)
{"to":"628123456789","message":"Halo 👋"}

# IMAGE
{"to":"628123456789","type":"image","url":"https://contoh.com/foto.jpg","message":"caption"}

# VIDEO
{"to":"628123456789","type":"video","url":"https://contoh.com/video.mp4","message":"caption"}

# AUDIO (message → caption tidak dipakai; ptt:true = voice note)
{"to":"628123456789","type":"audio","url":"https://contoh.com/a.mp3","ptt":false}

# DOCUMENT
{"to":"628123456789","type":"document","url":"https://contoh.com/invoice.pdf",
 "filename":"invoice.pdf","mimetype":"application/pdf","message":"Invoice"}

# STICKER
{"to":"628123456789","type":"sticker","url":"https://contoh.com/stiker.webp"}

# LOCATION
{"to":"628123456789","type":"location","latitude":-6.2088,"longitude":106.8456,
 "name":"Kantor","address":"Jl. Contoh No. 1"}

# CONTACT
{"to":"628123456789","type":"contact","contacts":[{"name":"Budi","phone":"628111222333"}]}

# REACTION (emoji "" = hapus reaksi)
{"to":"628123456789","type":"reaction","message_id":"3EB0XXXX","emoji":"👍"}

Upload file sendiri (multipart)

curl -X POST https://151.245.136.93:8443/api/v1/send \
  -H "X-Device-Key: wag_xxxxxxxx" \
  -F "to=628123456789" \
  -F "type=image" \
  -F "message=caption dari HP" \
  -F "file=@/path/foto.jpg"

Kalau type tidak dikirim, tipenya ditebak dari MIME file (image/* → image, video/* → video, audio/* → audio, lainnya → document). Maks. ukuran: 64 MB.

5. Bulk / broadcast

{
  "delay_ms": 1500,
  "messages": [
    {"to":"628111111111","message":"Promo hari ini"},
    {"to":"628222222222","message":"Promo hari ini"},
    {"to":"[email protected]","message":"Promo di grup","is_group":true}
  ]
}

Response berisi ringkasan success/failed + detail per nomor. Jeda default 1,5 detik (anti-spam). Maks 500 nomor per request.

6. Grup

7. Riwayat pesan

{
  "success": true, "total": 128,
  "messages": [{
    "id": 128, "device_id": "cs-bot-1a2b3c", "direction": "in",
    "chat_id": "[email protected]", "chat_name": "Budi",
    "is_group": false, "type": "conversation", "body": "Halo min",
    "media_url": null, "wa_msg_id": "3EB0…", "status": "received",
    "created_at": 1792238000000, "created_at_iso": "2026-10-17T11:53:20.000Z"
  }]
}

GET /api/v1/messages/:id untuk satu pesan. Media masuk otomatis diunduh dan tersedia di media_url.

POST /api/v1/message/delete — hapus pesan untuk semua orang: {"to":"628xxx","message_id":"3EB0…","from_me":true}

8. Webhook (pesan masuk)

Set URL per device di admin panel (tab Webhook). Gateway POST JSON tiap ada pesan masuk / keluar (pilih event-nya).

POST https://app-anda.com/webhook
Content-Type: application/json
X-Webhook-Event: message
X-Device-Id: cs-bot-1a2b3c

{
  "event": "message",
  "device_id": "cs-bot-1a2b3c",
  "device_name": "cs-bot",
  "sent_at": "2026-10-17T11:53:20.000Z",
  "data": {
    "message_id": 128, "direction": "in",
    "chat_id": "[email protected]", "chat_name": "Budi",
    "sender_id": "[email protected]", "sender_name": "Budi",
    "is_group": false, "type": "conversation", "body": "Halo min",
    "media_path": null, "wa_msg_id": "3EB0…", "status": "received"
  }
}

Event: message (masuk), message.sent (keluar), test. Response 2xx = sukses; kegagalan tercatat di tab Webhook Log.

Test cepat: POST /api/v1/webhook/test body {"url":"https://app-anda.com/webhook"}

9. Admin Panel & API-nya

Panel: /admin/. Fitur: statistik, kelola device (QR, pairing code, start/stop/restart/logout/reset, rotate key, hapus), kirim uji (pilih tipe), log pesan, log webhook.

10. Operasional

Aplikasi jalan sebagai service systemd (wa-gateway.service) di /www/wwwroot/wa-gateway, port 8787 (internal), dan diakses publik lewat nginx 8443 (HTTPS).

sudo systemctl status wa-gateway
sudo systemctl restart wa-gateway
tail -f /www/wwwroot/wa-gateway/logs/server.out

Troubleshooting

Backup: sessions/ (kredensial WhatsApp) dan data/wa-gateway.db (device, key, riwayat). Spesifikasi mesin: /openapi.json.