Konsep Autentikasi: JWT vs Session API Token Authentication Concepts: JWT vs Session API Token

WA Gateway memisahkan autentikasi menjadi dua jenis token untuk keamanan dan pemisahan wewenang: WA Gateway separates authentication into two distinct token types for maximum security and responsibility separation:

Kirimkan kredensial pengguna Anda untuk mendapatkan JWT Bearer Token yang digunakan untuk mengelola sesi dan akun. Send user credentials to receive a JWT Bearer Token required for session lifecycle management and account operations.

curl -X POST "http://localhost:3000/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "yourpassword"
  }'

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "username": "admin",
    "role": "admin",
    "max_sessions": 5,
    "status": "active",
    "expires_at": null
  }
}

Gunakan JWT dari Langkah 1 untuk membuat slot sesi WhatsApp baru. Sistem akan mengembalikan sessionId dan apiToken statis. Sistem secara otomatis memeriksa kuota max_sessions akun Anda. Use the JWT token from Step 1 to create a WhatsApp session slot. The system returns a unique sessionId and a static apiToken. The system automatically enforces your account's max_sessions quota limit.

curl -X POST "http://localhost:3000/api/user/sessions" \
  -H "Authorization: Bearer <YOUR_JWT_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support WhatsApp"
  }'

{
  "success": true,
  "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "apiToken": "4f9d8e7c6b5a43210fedcba9876543210fedcba9876543210fedcba987654321",
  "message": "Session created. Please link your WhatsApp device via QR code or phone pairing code."
}

Anda dapat menautkan nomor WhatsApp Anda dengan dua metode: memindai QR Code di layar atau meminta Pairing Code 8-digit langsung ke HP Anda. You can link your WhatsApp device via two methods: scanning a QR Code on screen or requesting an 8-digit Pairing Code directly to your phone.

Metode A: Scan QR Code

curl -X POST "http://localhost:3000/api/user/sessions/<SESSION_ID>/connect" \
  -H "Authorization: Bearer <YOUR_JWT_TOKEN>"

curl -X GET "http://localhost:3000/api/user/sessions/<SESSION_ID>/qr" \
  -H "Authorization: Bearer <YOUR_JWT_TOKEN>"

Metode B: 8-Digit Pairing Code

curl -X POST "http://localhost:3000/api/user/sessions/<SESSION_ID>/pair" \
  -H "Authorization: Bearer <YOUR_JWT_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "6281234567890"
  }'

{
  "status": "pairing",
  "pairing_code": "AB12-CD34"
}

Setelah status sesi berubah menjadi connected, gunakan Session API Token untuk mengirim pesan teks ke penerima WhatsApp. Once the session state is connected, use the Session API Token in the Authorization header to send a message.

curl -X POST "http://localhost:3000/api/send" \
  -H "Authorization: Bearer <YOUR_SESSION_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "628123456789",
    "text": "Halo! Pesan ini dikirim melalui WA Gateway REST API."
  }'

{
  "success": true,
  "message": "Message sent",
  "messageId": "3EB04A1B2C3D4E5F6"
}

Contoh Pengiriman Media (Gambar / Dokumen)

curl -X POST "http://localhost:3000/api/send-media" \
  -H "Authorization: Bearer <YOUR_SESSION_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "628123456789",
    "type": "image",
    "url": "https://images.unsplash.com/photo-1579202673506-ca3ce28943ef",
    "caption": "Bukti Pengiriman Invoice #INV-2026-001"
  }'

Atur URL server Anda untuk menerima notifikasi pesan masuk, pembaruan status koneksi, dan tanda terima pesan secara real-time. Anda juga dapat menyertakan beberapa target via chain_urls. Configure your backend URL to receive real-time HTTP POST notifications for incoming messages, connection state transitions, and delivery receipts. You can also specify multiple backup targets using chain_urls.

curl -X PATCH "http://localhost:3000/api/user/sessions/<SESSION_ID>/webhook" \
  -H "Authorization: Bearer <YOUR_JWT_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "url": "https://api.yourdomain.com/webhooks/whatsapp",
    "secret": "mySecretWebhookSignatureKey123",
    "chain_urls": [
      "https://backup.yourdomain.com/webhooks/whatsapp"
    ]
  }'

{
  "event": "incoming",
  "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": {
    "id": "3EB04A1B2C3D4E5F6",
    "from": "628123456789@s.whatsapp.net",
    "fromMe": false,
    "text": "Halo admin, saya ingin menanyakan status pesanan saya.",
    "timestamp": 1788960613,
    "type": "text"
  }
}

Penanganan Error & Best Practice Error Handling & Best Practices

Seluruh error mengembalikan struktur JSON konsisten dengan status HTTP yang tepat: All errors return a consistent JSON structure accompanied by standard HTTP status codes:

{
  "error": "Account suspended: Please contact the administrator.",
  "details": "Additional context if available"
}

Status Error Umum:

• 400 Bad Request: Field mandatory tidak diisi atau nomor tidak terdaftar di WhatsApp.
• 401 Unauthorized: Header Authorization: Bearer <token> hilang atau token kedaluwarsa.
• 403 Forbidden: Kuota sesi habis (max_sessions), akun disuspensi admin, atau akun telah kedaluwarsa.
• 404 Not Found: Sesi atau resource tidak ditemukan.
• 409 Conflict: Sesi sudah terkoneksi saat mencoba mengambil QR code.

Tips Pencegahan Pemblokiran (Anti-Ban) Anti-Ban Best Practices

• Gunakan Jeda Pengiriman (Delay): Jangan mengirim pesan beruntun tanpa jeda. Pada fitur broadcast, gunakan minimal delayMs: 3000. Apply Delivery Delays: Never blast messages without pause. In the broadcast API, use at least delayMs: 3000.
• Pertahankan Anti-Ban Default (antiBan: true): Biarkan gateway menyimulasikan status mengetik (composing) secara alami sebelum transmisi pesan. Keep Anti-Ban Enabled (antiBan: true): Allow the gateway to simulate natural typing indicators (composing) before dispatching.
• Validasi Nomor Tujuan: Gunakan POST /api/validate-number untuk menyaring nomor mati sebelum melakukan pengiriman massal. Validate Recipient Numbers: Use POST /api/validate-number to filter out inactive numbers before bulk dispatches.
• Gunakan Auto-Delete Sisi Server: Aktifkan auto_delete_enabled untuk mencegah penumpukan media dan database chat di memori internal HP server Anda. Enable Server-Side Auto-Delete: Turn on auto_delete_enabled to prevent media storage bloat on the server phone.