Dokumentasi Client API WA Gateway

3. Endpoint API

Kirim pesan teks ke nomor WhatsApp tujuan.

curl -X POST http://localhost:3000/api/send \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "628123456789",
    "text": "Halo, ini pesan dari WA Gateway",
    "antiBan": true
  }'

Kirim gambar, video, dokumen, atau audio.

curl -X POST http://localhost:3000/api/send-media \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "628123456789",
    "type": "image",
    "url": "https://example.com/image.jpg",
    "caption": "Halo dari WA Gateway",
    "antiBan": true
  }'

Kirim pesan ke banyak nomor secara berurutan.

curl -X POST http://localhost:3000/api/broadcast \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "toNumbers": ["628123456789", "628987654321"],
    "text": "Broadcast informasi promo",
    "delayMs": 2500
  }'

Ambil daftar aturan auto-reply yang sudah dibuat pada sesi saat ini.

curl -X GET "http://localhost:3000/api/auto-replies" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Tambah auto-reply baru berdasarkan keyword.

curl -X POST http://localhost:3000/api/auto-replies \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "halo",
    "reply_text": "Halo, selamat datang!"
  }'

Hapus satu aturan auto-reply berdasarkan ID.

curl -X DELETE "http://localhost:3000/api/auto-replies/12" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

4. Contoh request body

{
  "to": "628123456789",
  "text": "Hai, ini contoh kirim pesan",
  "antiBan": true,
  "autoDelete": true,
  "autoDeleteDelay": 30
}

{
  "to": "628123456789",
  "type": "image",
  "url": "https://example.com/promo.jpg",
  "caption": "Promo hari ini",
  "antiBan": true
}

5. Contoh client dengan JavaScript / Fetch

const token = 'YOUR_API_TOKEN';

const res = await fetch('http://localhost:3000/api/send', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    to: '628123456789',
    text: 'Halo dari Node.js client'
  })
});

const data = await res.json();
console.log(data);

6. Contoh client dengan Python

import requests

token = 'YOUR_API_TOKEN'
url = 'http://localhost:3000/api/send'

payload = {
    'to': '628123456789',
    'text': 'Halo dari Python client'
}

headers = {
    'Authorization': 'Bearer {token}',
    'Content-Type': 'application/json'
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

7. Webhook (Callback Update Real-Time)

Webhook memungkinkan server WA Gateway mengirim notifikasi otomatis ke endpoint Anda saat ada event penting, tanpa perlu polling terus-menerus. Ini sangat cocok untuk menerima pesan masuk, status koneksi perangkat, dan status pengiriman pesan.

Contoh konfigurasi

{
  "enabled": true,
  "url": "https://example.com/wa-webhook",
  "secret": "my-secret-key",
  "events": "incoming,connected,disconnected,message_status",
  "chain_urls": [
    "https://backup.example.com/wa-webhook"
  ]
}

Header yang dikirim ke webhook endpoint

Content-Type: application/json
User-Agent: WA-Gateway-Webhook/1.0
X-WA-Gateway-Event: incoming
X-WA-Gateway-Signature: sha256=af621e2f4fcb9b70d8f6d6c3d5641d48d... 

Header X-WA-Gateway-Signature adalah HMAC SHA256 dari raw JSON body, menggunakan secret yang Anda masukkan saat pengaturan webhook. Ini berguna untuk verifikasi integritas payload.

Contoh payload untuk event incoming

{
  "event": "incoming",
  "session_id": "d8f8d0c2-4ec9-4f1a-a91c-3c36c12a6f0b",
  "timestamp": 1727528887000,
  "data": {
    "session_id": "d8f8d0c2-4ec9-4f1a-a91c-3c36c12a6f0b",
    "from": "628123456789@s.whatsapp.net",
    "from_me": false,
    "message_id": "3EB0A24D1A2A",
    "message_type": "conversation",
    "message": {
      "conversation": "Halo, saya ingin bertanya"
    },
    "text": "Halo, saya ingin bertanya",
    "timestamp": 1727528887
  }
}

Contoh payload untuk event connected

{
  "event": "connected",
  "session_id": "d8f8d0c2-4ec9-4f1a-a91c-3c36c12a6f0b",
  "timestamp": 1727528887000,
  "data": {
    "session_id": "d8f8d0c2-4ec9-4f1a-a91c-3c36c12a6f0b",
    "status": "connected"
  }
}

Contoh payload untuk event message_status

{
  "event": "message_status",
  "session_id": "d8f8d0c2-4ec9-4f1a-a91c-3c36c12a6f0b",
  "timestamp": 1727528887000,
  "data": {
    "session_id": "d8f8d0c2-4ec9-4f1a-a91c-3c36c12a6f0b",
    "message_id": "ABC123",
    "jid": "628123456789@s.whatsapp.net",
    "status": "sent",
    "timestamp": 1727528887
  }
}

Webhook chaining (penerusan lanjutan)

Jika Anda mengisi chain_urls, WA Gateway akan mengirim payload ke URL utama terlebih dahulu, lalu ke URL tambahan secara berurutan. Artinya satu event bisa diteruskan ke beberapa endpoint sekaligus tanpa harus melakukan polling manual.

Primary: https://example.com/wa-webhook
Backup 1: https://backup.example.com/wa-webhook
Backup 2: https://audit.example.com/wa-webhook

Contoh endpoint webhook di Node.js

const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.json());

app.post('/wa-webhook', (req, res) => {
  const signature = req.headers['x-wa-gateway-signature'];
  const body = JSON.stringify(req.body);
  const expected = 'sha256=' + crypto
    .createHmac('sha256', 'my-secret-key')
    .update(body)
    .digest('hex');

  if (signature !== expected) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  console.log('Event:', req.body.event);
  console.log('Data:', req.body.data);

  res.status(200).json({ ok: true });
});

app.listen(3001, () => console.log('Webhook ready on port 3001'));