https://github.com/arktnld/wago-api
WhatsApp REST API — native protocol, multi-session, production-ready
https://github.com/arktnld/wago-api
chatbot docker golang messaging rest-api whatsapp whatsapp-api whatsmeow
Last synced: 2 months ago
JSON representation
WhatsApp REST API — native protocol, multi-session, production-ready
- Host: GitHub
- URL: https://github.com/arktnld/wago-api
- Owner: arktnld
- License: mit
- Created: 2026-05-02T18:33:33.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-02T19:59:52.000Z (2 months ago)
- Last Synced: 2026-05-02T20:28:57.020Z (2 months ago)
- Topics: chatbot, docker, golang, messaging, rest-api, whatsapp, whatsapp-api, whatsmeow
- Language: Go
- Homepage: https://github.com/arktnld/wago-api
- Size: 75.2 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# wago-api
[](https://github.com/arktnld/wago-api/actions)
[](https://github.com/arktnld/wago-api/releases)
[](https://go.dev)
[](LICENSE)
[](https://hub.docker.com/r/arktnld/wago-api)
[](https://goreportcard.com/report/github.com/arktnld/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
```bash
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:
```bash
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)](https://editor.swagger.io/?url=https://raw.githubusercontent.com/arktnld/wago-api/main/openapi.json)**
Also available at `http://localhost:3000/api-docs` when the server is running.
## Docker
```yaml
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:
```bash
docker compose up --build
```
Session data is stored in the `./sessions` volume and survives container restarts.
## Configuration
| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | `3000` | Server port |
| `API_KEY` | | API key sent via `X-Api-Key` header. Leave empty to disable auth |
| `BASE_WEBHOOK_URL` | | URL to receive events (e.g. `https://myserver.com/webhook`) |
| `ENABLE_WEBHOOK` | `true` | Send events via HTTP POST |
| `ENABLE_WEBSOCKET` | `false` | Send events via WebSocket |
| `AUTO_START_SESSIONS` | `true` | Reconnect saved sessions on startup |
| `SET_MESSAGES_AS_SEEN` | `false` | Automatically mark messages as read |
| `LOG_LEVEL` | `info` | `trace`, `debug`, `info`, `warn`, `error` |
| `RATE_LIMIT_MAX` | `1000` | Max requests per IP per window |
| `RATE_LIMIT_WINDOW_MS` | `1000` | Rate limit window in ms |
| `ENABLE_SWAGGER_ENDPOINT` | `true` | Serve `/api-docs` and `/openapi.json` |
## 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:
```json
{
"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**:
```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:
```yaml
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:
```bash
cp -r ./sessions ./sessions-backup-$(date +%Y%m%d)
```
## Build from Source
Requires Go 1.25+ and a C compiler (for SQLite).
```bash
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](https://github.com/tulir/whatsmeow) by tulir. API design inspired by [wwebjs-api](https://github.com/avoylenko/wwebjs-api).
## License
[MIT](LICENSE)