API Documentation & Integration Guide

1. Overview & Key Capabilities

WhatsGateway provides a developer-friendly HTTP interface layered on top of the open-source Baileys library and PHP 8.2 backend. Unlike commercial cloud brokers that charge $0.05 to $0.15+ per message conversation, WhatsGateway is completely self-hosted with zero licensing or subscription fees.

2. System Architecture Flow

The platform decouples HTTP message ingestion from the WebSocket connection to guarantee sub-millisecond response times and eliminate network timeouts:

3. Base URLs & Environments

All API endpoints are relative to your deployment's base URL. Replace the host below with your own private domain or local server address:

4. Authentication & Single API Key

Every API request requires an active API Key generated from your dashboard under API Keys. We support two standard header formats interchangeably:

5. Rate Limits & Burst Policies

Rate limits can be customized per API key directly in your dashboard (default: 60 requests per minute). If a client exceeds the threshold, the gateway responds with HTTP 429:

{
  "ok": false,
  "error": "Rate limit exceeded.",
  "request_id": "req_6718a209b...",
  "rate": {
    "allowed": false,
    "limit": 60,
    "current": 61,
    "remaining": 0,
    "reset_in_seconds": 45
  },
  "meta_error": {
    "message": "Rate limit hit.",
    "type": "OAuthException",
    "code": 80007
  }
}

Send Message (Clean REST Format)

Dispatches a text message, document, image, audio, or video file to any international WhatsApp recipient.

{
  "to": "919876543210",
  "message": "Hello from WhatsGateway! 🚀\nYour order *#84920* is confirmed.",
  "humanize": true
}

{
  "ok": true,
  "status": "queued",
  "message_id": 142,
  "request_id": "req_6718a9ef38...",
  "recipient": "919876543210",
  "type": "text",
  "has_media": false,
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "919876543210",
      "wa_id": "919876543210"
    }
  ],
  "messages": [
    {
      "id": "wamid.b29f430ca0489...",
      "message_status": "accepted"
    }
  ]
}

Meta WhatsApp Cloud API (Drop-In Compatibility)

If your existing codebase was built for the official Meta WhatsApp Cloud API (Graph API v17+), you can point your HTTP client directly at WhatsGateway without altering your request payload structure.

8. Media & Binary File Uploads

WhatsGateway supports three methods for sending attachments up to 20MB:

curl -X POST "https://whatsapp-api-xepo.onrender.com/api/send.php" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY_HERE" \
  -d '{
    "to": "919876543210",
    "type": "image",
    "media_url": "https://images.unsplash.com/photo-1579202673506-ca3ce28943ef?w=800",
    "caption": "Photo dispatch verified! 📸"
  }'

curl -X POST "https://whatsapp-api-xepo.onrender.com/api/send.php" \
  -H "X-API-Key: YOUR_API_KEY_HERE" \
  -F "to=919876543210" \
  -F "file=@/path/to/invoice-84920.pdf" \
  -F "caption=Attached is your monthly billing statement."

curl -X POST "https://whatsapp-api-xepo.onrender.com/api/send.php" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY_HERE" \
  -d '{
    "to": "919876543210",
    "media_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
    "filename": "pixel.png",
    "caption": "Rendered via Base64"
  }'

9. Voice Notes & Push-to-Talk (PTT)

By default, audio files are delivered as standard media players. To render audio as an authentic WhatsApp voice message with waveform playback, pass "ptt": true:

curl -X POST "https://whatsapp-api-xepo.onrender.com/api/send.php" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY_HERE" \
  -d '{
    "to": "919876543210",
    "type": "audio",
    "media_url": "https://example.com/audio/voice-memo.ogg",
    "ptt": true
  }'

Gateway & Worker Health Check

Monitor uptime and connectivity for automated uptime pings (UptimeRobot, Datadog, Prometheus):

curl -X GET "https://whatsapp-api-xepo.onrender.com/api/health.php"

{
  "ok": true,
  "status": "healthy",
  "timestamp": "2026-10-23T15:10:00+05:30",
  "service": "whatsgateway",
  "worker": {
    "ok": true,
    "status_code": 200,
    "service": "baileys-worker"
  }
}

11. Anti-Ban Architecture & Humanize Delays

WhatsApp monitors sudden high-frequency bursts of unsolicited traffic. WhatsGateway embeds multiple safeguards to keep your linked numbers healthy:

12. Webhooks & Real-Time Delivery Notifications

Configure your HTTPS webhook endpoint in the Dashboard under Webhooks. Whenever a message transitions states or your phone link updates, WhatsGateway executes an asynchronous HTTP POST callback:

const crypto = require('crypto');

function verifyWebhook(rawBody, signatureHeader, secret) {
    const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
    return crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected));
}

import hmac, hashlib

def verify_webhook(raw_body_bytes, signature_header, secret_key):
    expected = "sha256=" + hmac.new(secret_key.encode(), raw_body_bytes, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature_header, expected)

{
  "event": "message.delivered",
  "message_id": 142,
  "to": "919876543210",
  "status": "delivered",
  "timestamp": "2026-10-23T15:12:00Z"
}

{
  "event": "message.read",
  "message_id": 142,
  "to": "919876543210",
  "status": "read",
  "timestamp": "2026-10-23T15:12:05Z"
}

13. Google Contacts Integration & Limited Use

WhatsGateway supports one-click address book synchronization powered by Google People API OAuth 2.0 PKCE:

14. Multi-Language Quickstart Code

Production-grade implementations in popular programming languages:

curl -X POST "https://whatsapp-api-xepo.onrender.com/api/send.php" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wa_live_YOUR_API_KEY_HERE" \
  -d '{
    "to": "919876543210",
    "message": "Hello from WhatsGateway! 🚀\nYour order *#84920* has been shipped.",
    "humanize": true
  }'

// Native fetch available in Node.js 18+ and modern browsers
const response = await fetch("https://whatsapp-api-xepo.onrender.com/api/send.php", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "wa_live_YOUR_API_KEY_HERE"
  },
  body: JSON.stringify({
    to: "919876543210",
    message: "Order #84920 confirmed via Node.js! ⚡",
    humanize: true
  })
});

const result = await response.json();
console.log("Gateway Response:", result);

import requests

url = "https://whatsapp-api-xepo.onrender.com/api/send.php"
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "wa_live_YOUR_API_KEY_HERE"
}
payload = {
    "to": "919876543210",
    "message": "Hello from Python! 🐍\nYour verification code is *7492*.",
    "humanize": True
}

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

<?php
$payload = [
    'to' => '919876543210',
    'message' => 'Hello from PHP Client! 🐘',
    'humanize' => true
];

$ch = curl_init("https://whatsapp-api-xepo.onrender.com/api/send.php");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-API-Key: wa_live_YOUR_API_KEY_HERE'
    ],
    CURLOPT_POSTFIELDS => json_encode($payload)
]);

$response = curl_exec($ch);
curl_close($ch);
echo $response;

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	payload, _ := json.Marshal(map[string]interface{}{
		"to":       "919876543210",
		"message":  "Instant transactional alert via Go! 🐹",
		"humanize": true,
	})

	req, _ := http.NewRequest("POST", "https://whatsapp-api-xepo.onrender.com/api/send.php", bytes.NewBuffer(payload))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("X-API-Key", "wa_live_YOUR_API_KEY_HERE")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

15. Interactive Terminal CLI Tool

Send messages directly from your developer terminal without writing code using our included interactive Python CLI tool:

16. HTTP Status Codes & Error Dictionary

All HTTP error responses return a standardized JSON envelope with both generic and Meta-compatible error structures: