ServerWA — Dokumentasi Integrasi API

Ringkasan

ServerWA adalah gateway WhatsApp berbasis Node.js (Baileys) dengan REST API dan Socket.IO. Setiap aplikasi CRM (mis. SalesForge) mengidentifikasi device dengan token unik; folder sesi disimpan per nomor WhatsApp di server/auth/628….

Protokol: HTTPS + JSON (Content-Type: application/json)
Autentikasi API: header X-API-Key atau Authorization: Bearer
Realtime: Socket.IO (QR, koneksi, pesan masuk)
Webhook: POST ke URL yang Anda set di config.webhookUrl saat connect

Autentikasi

Semua endpoint di bawah /api/whatsapp/* dan /metrics membutuhkan API key (kecuali health publik).

Header	Contoh
`X-API-Key`	`X-API-Key: <API_SECRET>`
`Authorization`	`Authorization: Bearer <API_SECRET>`

Nilai API_SECRET diatur di file .env serverwa (REQUIRE_API_SECRET=true di production).

Jangan commit API_SECRET ke repositori. Di SalesForge gunakan WA_GATEWAY_API_SECRET di .env (sama dengan API_SECRET).

Socket.IO

const socket = io('https://gateway.example.com', {
  auth: { apiKey: 'API_SECRET_ANDA' },
  transports: ['websocket', 'polling']
});

Base URL

URL gateway saat halaman ini dibuka:

—

Contoh request:

curl -H "X-API-Key: API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"token":"DEVICE_TOKEN"}' \
  BASE_URL/api/whatsapp/session

Socket.IO — Event

Hubungkan ke origin yang sama dengan server (lihat ORIGIN di .env). Wajib kirim auth.apiKey.

Event (server → client)	Payload	Keterangan
`qrcode`	`{ token, data, message, retryCount }`	`data` = data URL gambar QR
`connection-open`	`{ token, user, phone }`	Sesi WA terhubung
`connection-close`	`{ token, message, reason? }`	Sesi putus / logout / timeout QR
`message-upsert`	Objek pesan masuk	Mirror payload webhook (realtime)
`user-data-cleaned`	`{ token }`	Auth folder dihapus

Alur scan QR: panggil POST /api/whatsapp/connect → dengarkan qrcode → setelah scan, connection-open.

Webhook keluar (ke CRM)

Server mengirim POST JSON ke config.webhookUrl saat:

Pesan masuk (teks/media)
Update status pesan terkirim (sent, delivered, read, …)
Logout / sesi ditutup
Sinkron kontak (opsional, event history)

Contoh payload pesan masuk

{
  "token": "device_token_abc",
  "message_id": "3EB0…",
  "fromMe": false,
  "from": "[email protected]",
  "message": { "conversation": "Halo" },
  "pushName": "Budi",
  "remoteJid": "[email protected]",
  "messageType": "conversation",
  "text": "Halo",
  "timestamp": 1710000000000
}

Media dapat menyertakan imageBase64, videoBase64, dll. (base64 + mimetype).

Webhook internal (path suffix)

Server dapat memanggil {webhookUrl}/check-message atau /check-call untuk setting read/reject call.

Format nomor

Personal: 628123456789 atau [email protected] (otomatis diformat)
Grup: 120363…@g.us
Connect: wajib config.phone = nomor WA device (contoh 6289876543210) untuk folder auth

Folder auth (server)

Path: server/auth/<nomor>/ — contoh server/auth/6281234567890/creds.json

File .session.json menyimpan mapping token CRM ↔ nomor. Auto-reconnect saat startup membaca folder nomor ini.

Integrasi SalesForge

Library PHP: App\Libraries\Whatsapp — header API otomatis dari WA_GATEWAY_API_SECRET.

Fitur CRM	Endpoint ServerWA
Scan QR device	`POST /api/whatsapp/connect` + Socket.IO
Broadcast / cron	`POST /api/whatsapp/send-text`, `send-media`
Grup WA (broadcast)	`group-all-data`, `group-metadata`
Admin server	`GET /health/live` (tanpa key)

Health & Metrics

GETPublic /health/live

Liveness probe — server hidup.

GETPublic /health/ready

Readiness — siap terima traffic (503 jika belum ready).

GETPublic /health

Ringkasan status + memori + sesi (tanpa data sensitif penuh).

GETAuth /health/detail

Detail operasional + metrics (butuh API key).

GETAuth /metrics

Snapshot metrik request + sesi.

Sesi & QR

POSTAuth /api/whatsapp/connect

Membuat/melanjutkan koneksi WA. Rate limit: connect (default 15/menit).

Body:

{
  "token": "device_token_unik",
  "config": {
    "browserName": "SalesForge CRM",
    "webhookUrl": "https://crm.example.com/api/webhook",
    "phone": "6281234567890"
  }
}

Response sukses: qrcode (data URL), atau pendingQr: true (QR via Socket), atau user jika sudah login.

POST /api/whatsapp/create-instance

Legacy — hapus auth lalu connect baru. Response: { status, qrcode, message }.

Config & Session

POST /api/whatsapp/update-config

Body: { "token", "config": { "webhookUrl": "…" } }

GET /api/whatsapp/config/:token

Mengembalikan webhookUrl yang tersimpan.

POST /api/whatsapp/session

Body: { "token" } — cek sesi aktif. Response: { status, data: user } atau gagal.

GET /api/whatsapp/chats/:token

Status koneksi ringkas untuk token.

Hapus sesi

POST /api/whatsapp/delete-instance

Logout + hapus auth folder. Body: { "token" }

POST /api/whatsapp/delete-auth

Hapus folder auth (manual cleanup). Body: { "token" }

Kirim pesan — Teks

POST /api/whatsapp/send-text

Body: { "token", "number", "text" }

Response: { "status": true, "data": { …message key } } — butuh client ready (503 jika belum connect).

Kirim pesan — Media

POST /api/whatsapp/send-media

Body:

{
  "token": "…",
  "number": "628…",
  "type": "image",
  "url": "https://…/file.jpg",
  "caption": "Opsional"
}

type: image, video, audio, document, …

Kirim pesan — Poll

POST /api/whatsapp/send-poll

Body: { "token", "number", "question", "options": ["A","B"], "selectableCount": 1 }

Button, Template, List, Story

POST/api/whatsapp/send-button

buttons (array), message, footer, type, image

POST/api/whatsapp/send-template

Body: { "token", "number", "buttons", "text", "footer", "image" }

POST/api/whatsapp/send-list

list (array), title, buttonText, …

POST/api/whatsapp/send-story

numbers, type, content, caption, …

Grup WhatsApp

POST/api/whatsapp/group-all-data

Body: { "token" } — daftar semua grup (objek keyed by JID).

Response: { "status": true, "data": { "120363…@g.us": { "subject": "…", … } } }

POST/api/whatsapp/group-metadata

Body: { "token", "number": "120363…@g.us" } — metadata + participants.

Cek nomor & profil

POST/api/whatsapp/check-number

Body: { "token", "number" } — Response: { "status": true, "data": { "exists": true|false } }

POST/api/whatsapp/profile-picture

Body: { "token", "number", "highrest": false }

Pengaturan device

POST/api/whatsapp/update-device-setting

Body: { "token", "setting": "read"|"reject", "value": 0|1 }

read — auto read status@broadcast
reject — tolak panggilan masuk
antispam — hapus link non-admin di grup (via webhook check)

Status & monitoring

GET/api/whatsapp/status

Status ringkas: uptime, jumlah sesi aktif.

GET/api/whatsapp/sessions

Daftar sesi (token disamarkan) untuk monitoring.

Kode HTTP & error umum

HTTP	Arti
400	Parameter kurang / `config.phone` wajib
401	API key salah atau tidak dikirim
429	Rate limit (connect/send)
503	Client WA belum ready / kapasitas penuh / memori
500	Error internal / gagal init koneksi

Dev only

POST /test-link-preview — hanya jika NODE_ENV !== 'production'.

Rate limit (default .env)

API global: RATE_LIMIT_API_MAX / 15 menit
Connect: RATE_LIMIT_CONNECT_MAX / menit
Send: RATE_LIMIT_SEND_MAX / menit

Dokumentasi ini di-generate untuk ServerWA Gateway. Buka /docs setelah server berjalan.