wago-api

wago-api

WhatsApp REST API — native protocol, multi-session, production-ready.

• 129 REST endpoints — messaging, groups, communities, channels, privacy, business
• Multi-session — run hundreds of WhatsApp accounts in a single instance
• Lightweight Docker image — single Go binary, zero runtime dependencies
• Production-ready — auto-reconnect, webhook retry, rate limiting, SSRF protection, request tracing

Quick Start

git clone https://github.com/arktnld/wago-api && cd wago-api
docker compose up

Open http://localhost:3000/session/start/main to create a session, then scan the QR code at http://localhost:3000/session/qr/main/image with WhatsApp > Linked Devices > Link a Device.

Send your first message:

curl -X POST http://localhost:3000/client/sendMessage/main \
  -H 'Content-Type: application/json' \
  -d '{"chatId":"5511999999999@s.whatsapp.net","text":"Hello from wago-api!"}'

Features

• Messaging — text, image, video, audio, documents, polls, reactions, reply, forward, edit, delete
• Groups — create, manage participants, invite links, permissions, membership approval
• Communities — create, link/unlink sub-groups, manage join approval
• Channels — create, follow, send messages, reactions, fetch history
• Contacts — profile pictures, presence (online/offline/typing), block/unblock, QR links
• Privacy — 10 granular settings (last seen, profile, groups, read receipts, etc), disappearing messages
• Business — verified profiles, wa.me links, bot listing
• Calls — reject incoming calls programmatically
• Labels — create, edit, assign to chats and messages
• Multi-session — run hundreds of accounts in one instance
• Webhooks — real-time events via HTTP POST with automatic retry
• WebSocket — real-time event stream

API Documentation

Open Interactive Documentation (Swagger)

Also available at http://localhost:3000/api-docs when the server is running.

Docker

services:
  api:
    image: arktnld/wago-api:latest
    ports:
      - "3000:3000"
    volumes:
      - ./sessions:/app/sessions
    environment:
      - API_KEY=your-secret-key
      - BASE_WEBHOOK_URL=https://your-server.com/webhook
    restart: unless-stopped

Or build locally:

docker compose up --build

Session data is stored in the ./sessions volume and survives container restarts.

Configuration

Webhooks

When a WhatsApp event happens (message received, status change, etc), wago-api sends a POST request to your webhook URL:

POST {BASE_WEBHOOK_URL}/{sessionId}/{event}

Example payload:

{
  "sessionId": "main",
  "event": "message",
  "data": {
    "id": "3EB0F85AB813A2BB26F73D",
    "chat": "5511999999999@s.whatsapp.net",
    "sender": "5511999999999@s.whatsapp.net",
    "pushName": "John",
    "body": "Hello!",
    "type": "text",
    "timestamp": 1777744034,
    "isGroup": false,
    "isFromMe": false
  }
}

Failed deliveries are retried 3 times with exponential backoff (1s, 2s, 4s).

Security

• API Key — header-only authentication (no query params to avoid log leaks)
• SSRF Protection — blocks requests to private IPs and cloud metadata endpoints
• Rate Limiting — per-IP with automatic cleanup
• Request Tracing — X-Request-Id header on every response

HTTPS

wago-api runs HTTP by default. For production, use a reverse proxy:

Caddy (automatic TLS):

wago.example.com {
    reverse_proxy localhost:3000
}

Nginx:

server {
    listen 443 ssl;
    server_name wago.example.com;
    ssl_certificate /etc/ssl/cert.pem;
    ssl_certificate_key /etc/ssl/key.pem;
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
    location /ws/ {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Logs & Backup

Log rotation with Docker:

services:
  api:
    image: arktnld/wago-api:latest
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

Session backup: session data is stored in SQLite files at ./sessions/. Back up this directory regularly:

cp -r ./sessions ./sessions-backup-$(date +%Y%m%d)

Build from Source

Requires Go 1.25+ and a C compiler (for SQLite).

git clone https://github.com/arktnld/wago-api
cd wago-api
CGO_ENABLED=1 go build -ldflags="-s -w" -o wago-api .
./wago-api

Credits

Built on whatsmeow by tulir. API design inspired by wwebjs-api.

License

MIT