andri
/
whatsapp-hybrid-gateway
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
whatsapp-hybrid-gateway/DOCUMENTATION.md

17 KiB
Raw Permalink Blame History

WhatsApp Gateway API Documentation

Overview

WhatsApp Gateway API adalah REST API lengkap untuk mengirim berbagai jenis pesan WhatsApp menggunakan library Baileys. API ini menyediakan endpoints untuk mengirim text, gambar, dokumen, audio, video, dan sticker melalui WhatsApp.

API Information

  • Base URL: http://your-server:5000
  • Version: 2.0.0
  • Protocol: HTTP/HTTPS
  • Format: JSON
  • Authentication: Optional (API Key)

Table of Contents

  1. Authentication
  2. Base Endpoints
  3. Message Endpoints
  4. File Upload Guidelines
  5. Error Handling
  6. Rate Limiting
  7. Examples
  8. Response Codes

Authentication

API authentication bersifat opsional dan dikonfigurasi melalui environment variables.

API Key (Optional)

Jika enabled, sertakan API key di header request:

X-API-Key: your-api-key-here

Atau menggunakan Authorization header:

Authorization: Bearer your-api-key-here

Base Endpoints

1. Health Check / API Information

Endpoint: GET /

Description: Mendapatkan informasi lengkap tentang API, status bot, dan fitur yang tersedia.

Request:

GET / HTTP/1.1
Host: localhost:5000

Response:

{
  "service": "WhatsApp Gateway Production",
  "status": "running",
  "bot_connected": true,
  "version": "2.0.0",
  "environment": "production",
  "features": {
    "text_messages": "✅ Working",
    "image_messages": "✅ Working",
    "document_messages": "✅ Working",
    "audio_messages": "✅ Available",
    "video_messages": "✅ Available",
    "sticker_messages": "✅ Available",
    "webhooks": "❌ Disabled",
    "analytics": "✅ Enabled",
    "rate_limiting": "✅ Enabled",
    "api_auth": "❌ Disabled"
  },
  "supported_formats": {
    "images": ["jpg", "jpeg", "png", "gif", "webp"],
    "documents": ["pdf", "doc", "docx", "xls", "xlsx", "ppt", "pptx", "txt", "zip", "rar", "7z"],
    "audio": ["mp3", "wav", "ogg", "m4a", "aac", "flac"],
    "video": ["mp4", "avi", "mov", "mkv", "webm", "3gp", "flv"],
    "stickers": ["webp"]
  },
  "file_size_limits": {
    "images": "16MB",
    "documents": "32MB",
    "audio": "16MB",
    "video": "64MB",
    "stickers": "1MB"
  },
  "endpoints": [
    "POST /api/send-message - Send text message",
    "POST /api/send-image - Send image with caption",
    "POST /api/send-document - Send document with caption",
    "POST /api/send-audio - Send audio file",
    "POST /api/send-video - Send video with caption",
    "POST /api/send-sticker - Send WebP sticker",
    "GET /api/status - Bot status",
    "GET /api/health - Health check"
  ],
  "limits": {
    "max_requests": 100,
    "time_window": "3600s"
  },
  "uptime": 1234.56,
  "memory": {
    "used": 85,
    "total": 128
  }
}

2. Bot Status

Endpoint: GET /api/status

Description: Mendapatkan status detail bot WhatsApp dan sistem.

Request:

GET /api/status HTTP/1.1
Host: localhost:5000

Response:

{
  "bot_connected": true,
  "connection_attempts": 0,
  "max_attempts": 5,
  "thread_alive": true,
  "upload_folder": "./uploads",
  "session_folder": "./session",
  "environment": "production",
  "features": {
    "webhooks": false,
    "analytics": true,
    "rate_limiting": true,
    "api_authentication": false
  },
  "supported_formats": {
    "images": ["jpg", "jpeg", "png", "gif", "webp"],
    "documents": ["pdf", "doc", "docx", "xls", "xlsx", "ppt", "pptx", "txt", "zip", "rar", "7z"],
    "audio": ["mp3", "wav", "ogg", "m4a", "aac", "flac"],
    "video": ["mp4", "avi", "mov", "mkv", "webm", "3gp", "flv"],
    "stickers": ["webp"]
  },
  "system": {
    "uptime": 1234.56,
    "memory_usage_mb": 85,
    "node_version": "v20.11.0",
    "platform": "linux"
  },
  "message": "Bot status retrieved"
}

3. Health Check

Endpoint: GET /api/health

Description: Simple health check untuk monitoring.

Request:

GET /api/health HTTP/1.1
Host: localhost:5000

Response (Bot Connected):

{
  "status": "ok",
  "timestamp": "2025-09-23T13:45:30.123Z",
  "uptime": 1234.56,
  "environment": "production",
  "services": {
    "whatsapp_bot": "connected",
    "api_server": "running"
  }
}

Response (Bot Disconnected):

{
  "status": "ok",
  "timestamp": "2025-09-23T13:45:30.123Z",
  "uptime": 1234.56,
  "environment": "production",
  "services": {
    "whatsapp_bot": "disconnected",
    "api_server": "running"
  }
}

4. QR Code

Endpoint: GET /api/qr

Description: Mendapatkan QR code untuk koneksi WhatsApp (jika tersedia).

Request:

GET /api/qr HTTP/1.1
Host: localhost:5000

Response (QR Available):

{
  "status": "success",
  "qr": "2@8QJwrEjN8hKDGkjgh...",
  "message": "QR code available for scanning"
}

Response (Already Connected):

{
  "status": "success",
  "message": "Bot already connected, no QR needed"
}

Message Endpoints

1. Send Text Message

Endpoint: POST /api/send-message

Description: Mengirim pesan text ke nomor WhatsApp.

Request:

POST /api/send-message HTTP/1.1
Host: localhost:5000
Content-Type: application/json

{
  "phone": "6281234567890",
  "message": "Hello from WhatsApp Gateway API!"
}

Response (Success):

{
  "status": "success",
  "message": "Text message sent successfully",
  "data": {
    "phone": "6281234567890",
    "message": "Hello from WhatsApp Gateway API!",
    "type": "text",
    "timestamp": "2025-09-23 13:45:30"
  }
}

2. Send Image

Endpoint: POST /api/send-image

Description: Mengirim gambar dengan caption opsional.

Request:

POST /api/send-image HTTP/1.1
Host: localhost:5000
Content-Type: multipart/form-data

--boundary
Content-Disposition: form-data; name="phone"

6281234567890
--boundary
Content-Disposition: form-data; name="caption"

Beautiful sunset photo!
--boundary
Content-Disposition: form-data; name="file"; filename="sunset.jpg"
Content-Type: image/jpeg

[binary image data]
--boundary--

cURL Example:

curl -X POST http://localhost:5000/api/send-image \
  -F "phone=6281234567890" \
  -F "caption=Beautiful sunset photo!" \
  -F "file=@sunset.jpg"

Response (Success):

{
  "status": "success",
  "message": "Image sent successfully",
  "data": {
    "phone": "6281234567890",
    "filename": "sunset.jpg",
    "caption": "Beautiful sunset photo!",
    "type": "image",
    "file_size_kb": 245.67,
    "timestamp": "2025-09-23 13:45:30"
  }
}

3. Send Document

Endpoint: POST /api/send-document

Description: Mengirim dokumen dengan caption opsional.

Request (Form Data):

  • phone (required): Nomor WhatsApp tujuan
  • file (required): File dokumen
  • caption (optional): Caption untuk dokumen

cURL Example:

curl -X POST http://localhost:5000/api/send-document \
  -F "phone=6281234567890" \
  -F "caption=Important document" \
  -F "file=@report.pdf"

Response (Success):

{
  "status": "success",
  "message": "Document sent successfully",
  "data": {
    "phone": "6281234567890",
    "filename": "report.pdf",
    "caption": "Important document",
    "type": "document",
    "file_size_kb": 1024.50,
    "timestamp": "2025-09-23 13:45:30"
  }
}

4. Send Audio

Endpoint: POST /api/send-audio

Description: Mengirim file audio sebagai voice note.

Request (Form Data):

  • phone (required): Nomor WhatsApp tujuan
  • file (required): File audio

cURL Example:

curl -X POST http://localhost:5000/api/send-audio \
  -F "phone=6281234567890" \
  -F "file=@voice_message.mp3"

Response (Success):

{
  "status": "success",
  "message": "Audio sent successfully",
  "data": {
    "phone": "6281234567890",
    "filename": "voice_message.mp3",
    "type": "audio",
    "file_size_kb": 512.25,
    "timestamp": "2025-09-23 13:45:30"
  }
}

5. Send Video

Endpoint: POST /api/send-video

Description: Mengirim video dengan caption opsional.

Request (Form Data):

  • phone (required): Nomor WhatsApp tujuan
  • file (required): File video
  • caption (optional): Caption untuk video

cURL Example:

curl -X POST http://localhost:5000/api/send-video \
  -F "phone=6281234567890" \
  -F "caption=Amazing video!" \
  -F "file=@demo.mp4"

Response (Success):

{
  "status": "success",
  "message": "Video sent successfully",
  "data": {
    "phone": "6281234567890",
    "filename": "demo.mp4",
    "caption": "Amazing video!",
    "type": "video",
    "file_size_kb": 2048.75,
    "timestamp": "2025-09-23 13:45:30"
  }
}

6. Send Sticker

Endpoint: POST /api/send-sticker

Description: Mengirim sticker dalam format WebP.

Request (Form Data):

  • phone (required): Nomor WhatsApp tujuan
  • file (required): File sticker (WebP)

cURL Example:

curl -X POST http://localhost:5000/api/send-sticker \
  -F "phone=6281234567890" \
  -F "file=@funny_sticker.webp"

Response (Success):

{
  "status": "success",
  "message": "Sticker sent successfully",
  "data": {
    "phone": "6281234567890",
    "filename": "funny_sticker.webp",
    "type": "sticker",
    "file_size_kb": 23.45,
    "timestamp": "2025-09-23 13:45:30"
  }
}

File Upload Guidelines

Supported File Types

Media Type Extensions Max Size Caption Support
Images jpg, jpeg, png, gif, webp 16MB ✅ Yes
Documents pdf, doc, docx, xls, xlsx, ppt, pptx, txt, zip, rar, 7z 32MB ✅ Yes
Audio mp3, wav, ogg, m4a, aac, flac 16MB ❌ No
Video mp4, avi, mov, mkv, webm, 3gp, flv 64MB ✅ Yes
Stickers webp 1MB ❌ No

Phone Number Format

API mendukung berbagai format nomor telepon:

  • 6281234567890 (format internasional Indonesia)
  • +6281234567890 (dengan tanda plus)
  • 081234567890 (format lokal, otomatis dikonversi)

Semua format akan dikonversi ke format WhatsApp: 6281234567890@s.whatsapp.net

Error Handling

Semua error menggunakan format JSON yang konsisten:

Error Response Format

{
  "status": "error",
  "message": "Error description here",
  "timestamp": "2025-09-23T13:45:30.123Z"
}

Common Errors

400 - Bad Request

{
  "status": "error",
  "message": "Phone number required",
  "timestamp": "2025-09-23T13:45:30.123Z"
}

{
  "status": "error",
  "message": "Invalid file type. Allowed: [\"jpg\",\"jpeg\",\"png\",\"gif\",\"webp\"]",
  "timestamp": "2025-09-23T13:45:30.123Z"
}

401 - Unauthorized (jika API key enabled)

{
  "status": "error",
  "message": "Unauthorized: Invalid or missing API key",
  "timestamp": "2025-09-23T13:45:30.123Z"
}

404 - Not Found

{
  "status": "error",
  "message": "Endpoint not found",
  "timestamp": "2025-09-23T13:45:30.123Z"
}

429 - Rate Limit Exceeded

{
  "status": "error",
  "message": "Too many requests. Please try again later.",
  "timestamp": "2025-09-23T13:45:30.123Z",
  "limit": 100,
  "window": 3600
}

500 - Internal Server Error

{
  "status": "error",
  "message": "Failed to send message: connection timeout",
  "timestamp": "2025-09-23T13:45:30.123Z"
}

503 - Service Unavailable

{
  "status": "error",
  "message": "Bot not connected",
  "timestamp": "2025-09-23T13:45:30.123Z"
}

Rate Limiting

Rate limiting dapat dikonfigurasi melalui environment variables:

  • Default Limit: 100 requests per hour
  • Time Window: 3600 seconds (1 hour)
  • Headers: Response tidak include rate limit headers
  • Scope: Per IP address

Ketika limit tercapai, API akan mengembalikan HTTP 429 dengan pesan error.

Examples

JavaScript (Node.js)

const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

const API_BASE = 'http://localhost:5000';

// Send text message
async function sendText(phone, message) {
  try {
    const response = await axios.post(`${API_BASE}/api/send-message`, {
      phone: phone,
      message: message
    });
    console.log('Success:', response.data);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

// Send image
async function sendImage(phone, imagePath, caption) {
  try {
    const form = new FormData();
    form.append('phone', phone);
    form.append('caption', caption);
    form.append('file', fs.createReadStream(imagePath));

    const response = await axios.post(`${API_BASE}/api/send-image`, form, {
      headers: form.getHeaders()
    });
    console.log('Success:', response.data);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

// Usage
sendText('6281234567890', 'Hello from Node.js!');
sendImage('6281234567890', './image.jpg', 'Sample image');

Python

import requests

API_BASE = 'http://localhost:5000'

# Send text message
def send_text(phone, message):
    response = requests.post(f'{API_BASE}/api/send-message', json={
        'phone': phone,
        'message': message
    })
    return response.json()

# Send image
def send_image(phone, image_path, caption=None):
    with open(image_path, 'rb') as f:
        files = {'file': f}
        data = {'phone': phone}
        if caption:
            data['caption'] = caption
            
        response = requests.post(f'{API_BASE}/api/send-image', 
                               files=files, data=data)
    return response.json()

# Usage
result = send_text('6281234567890', 'Hello from Python!')
print(result)

result = send_image('6281234567890', './image.jpg', 'Sample image')
print(result)

PHP

<?php

$apiBase = 'http://localhost:5000';

// Send text message
function sendText($phone, $message) {
    global $apiBase;
    
    $data = json_encode([
        'phone' => $phone,
        'message' => $message
    ]);

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, "$apiBase/api/send-message");
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
    curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($response, true);
}

// Send image
function sendImage($phone, $imagePath, $caption = null) {
    global $apiBase;
    
    $postData = [
        'phone' => $phone,
        'file' => new CURLFile($imagePath)
    ];
    
    if ($caption) {
        $postData['caption'] = $caption;
    }

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, "$apiBase/api/send-image");
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($response, true);
}

// Usage
$result = sendText('6281234567890', 'Hello from PHP!');
print_r($result);
?>

cURL Commands

# Send text message
curl -X POST http://localhost:5000/api/send-message \
  -H "Content-Type: application/json" \
  -d '{"phone":"6281234567890","message":"Hello from cURL!"}'

# Send image
curl -X POST http://localhost:5000/api/send-image \
  -F "phone=6281234567890" \
  -F "caption=Sample image" \
  -F "file=@image.jpg"

# Send document
curl -X POST http://localhost:5000/api/send-document \
  -F "phone=6281234567890" \
  -F "caption=Important document" \
  -F "file=@document.pdf"

# Check status
curl http://localhost:5000/api/status

# Health check
curl http://localhost:5000/api/health

Response Codes

Code Description Meaning
200 OK Request successful
400 Bad Request Invalid request parameters
401 Unauthorized Invalid or missing API key
404 Not Found Endpoint not found
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server error occurred
503 Service Unavailable Bot not connected

Troubleshooting

Common Issues

  1. Bot Not Connected

    • Check /api/status endpoint
    • Look for QR code in server logs
    • Scan QR code with WhatsApp

  2. File Upload Fails

    • Check file size limits
    • Verify file extension is supported
    • Ensure proper Content-Type header

  3. Rate Limit Hit

    • Wait for time window to reset
    • Reduce request frequency
    • Contact admin to adjust limits

  4. Authentication Error

    • Check if API key is required
    • Verify API key in headers
    • Ensure correct header format

Support

For technical support or questions:

  • Check server logs: sudo journalctl -u wa -f
  • Verify bot connection: curl http://localhost:5000/api/status
  • Test basic connectivity: curl http://localhost:5000/api/health

API Version: 2.0.0
Last Updated: September 23, 2025
Status: Production Ready