# WA Gateway

> Self-hosted WhatsApp HTTP gateway built on Baileys 7. Multi-session, multi-tenant, with webhook delivery, anti-ban patterns, and per-device rate limiting. Customers obtain an API key from the web dashboard once, then use REST endpoints to send text/media messages and receive incoming events via webhook.

## Base URL

The base URL of this gateway is the origin you reached this file from. All API
endpoints below are relative to that origin's `/api` prefix when behind the
reverse proxy (e.g. `https://wa.example.com/api/messages/send-text`).

## Documentation

- [Full reference](/llms-full.txt): All endpoints, examples, webhook contract, error shapes
- [OpenAPI spec](/api/openapi.json): Machine-readable OpenAPI 3.1 spec
- [Interactive explorer](/api/docs): Swagger UI

## Getting an API key

Sign-up and login are **dashboard-only flows** — not part of this API. To get
your API key:

1. Visit the web dashboard at the same origin (e.g. `https://wa.example.com`)
2. Register an account → login
3. Open **Settings** to copy your API key

Then use the key in the `X-API-Key` header on every API call below.

## Authentication

```
X-API-Key: <your-64-char-hex-key>
```

Verify your key works: `GET /api/auth/me`. Rotate it with `POST /api/auth/rotate-key`.

## Core flow

1. `POST /api/devices {name}` — create a device record
2. `POST /api/devices/{id}/connect` — start WA session
3. Subscribe to `GET /api/devices/{id}/events` (SSE) — receive `qr` event
4. Scan the QR with WhatsApp on your phone (Linked Devices)
5. Wait for `status: CONNECTED` event
6. `POST /api/messages/send-text` — send your first message

## Quick examples

### Send text

```
POST /api/messages/send-text
Content-Type: application/json
X-API-Key: <key>

{"deviceId": "...", "to": "628111222333", "text": "Halo!"}
```

### Send image

```
POST /api/messages/send-media
Content-Type: application/json
X-API-Key: <key>

{"deviceId": "...", "to": "628111222333", "kind": "image",
 "url": "https://example.com/img.jpg", "caption": "Halo!"}
```

### Register webhook

```
POST /api/webhooks
Content-Type: application/json
X-API-Key: <key>

{"url": "https://your-app.com/wa", "events": ["message.received", "device.status"]}
```

Each delivery includes `X-Webhook-Signature` (HMAC-SHA256 of body with your secret).

## Rate limits

- 30 messages per minute per device (default)
- Response headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
- Exceeded returns HTTP 429