# WhatsApp Provider API

Send and read WhatsApp messages over HTTP with an API key. This is an unofficial linked-device API (not Meta Cloud API). Keep volume low.

Base URL: `http://localhost:3000`

## Setup

1. Open `/login.html` and create an account (new accounts get 10 free credits).
2. On the dashboard, click **Link WhatsApp** and scan the QR from your phone: WhatsApp → **Linked devices** → **Link a device**.
3. Click **Create key** and copy the key. It is shown only once.
4. Buy more credits if you need them. **1 credit = 1 outbound API send.** Reading messages is free.

## Authentication

Send the key on every request:

```http
x-api-key: wk_live_...
```

`Authorization: Bearer wk_live_...` also works.

If you have more than one linked WhatsApp, pick one with `from` (JSON body or query) or header `x-account-id`. If omitted, the first connected account is used.

## Send a message

`POST /v1/messages` — deducts **1 credit** after WhatsApp accepts the send.

```http
POST /v1/messages
x-api-key: wk_live_...
Content-Type: application/json

{
  "to": "918056515399",
  "message": "Hello from the API"
}
```

```bash
curl -X POST http://localhost:3000/v1/messages ^
  -H "x-api-key: wk_live_YOUR_KEY" ^
  -H "Content-Type: application/json" ^
  -d "{\"to\":\"918056515399\",\"message\":\"Hello from the API\"}"
```

Use the full number with country code. No `+` needed.

### Optional fields

| Field | Description |
| --- | --- |
| `to` or `phone` | Recipient number (required) |
| `message` or `text` | Message body |
| `from` | Linked WhatsApp `accountId` |

### Send a file

```bash
curl -X POST http://localhost:3000/v1/messages ^
  -H "x-api-key: wk_live_YOUR_KEY" ^
  -F "to=918056515399" ^
  -F "message=See attached" ^
  -F "file=@C:\path\to\photo.jpg"
```

Max file size is 16 MB.

### Response

```json
{
  "ok": true,
  "credits": 9,
  "message": {
    "id": "3EB0...",
    "chatId": "918056515399@s.whatsapp.net",
    "phone": "918056515399",
    "fromMe": true,
    "text": "Hello from the API",
    "timestamp": 1786817503
  }
}
```

### Errors

| Status | Meaning |
| --- | --- |
| `401` | Missing or invalid API key |
| `400` | Missing `to` or message/file |
| `402` | Not enough credits |
| `409` | No connected WhatsApp. Link a device first |

## Get chats

`GET /v1/chats` — lists conversations for the selected account. Free.

```bash
curl http://localhost:3000/v1/chats -H "x-api-key: wk_live_YOUR_KEY"
```

```json
{
  "accountId": "298281c1c0b468f2765f448856e65cac",
  "chats": [
    {
      "id": "918056515399@s.whatsapp.net",
      "phone": "918056515399",
      "name": "Naveen S",
      "lastMessage": "Done",
      "lastTimestamp": 1786817228,
      "unreadCount": 0
    }
  ]
}
```

## Get messages

`GET /v1/messages` — reads stored history. Free.

### Latest messages in one chat

```bash
curl "http://localhost:3000/v1/messages?to=918056515399&limit=50" ^
  -H "x-api-key: wk_live_YOUR_KEY"
```

### Latest messages across chats

```bash
curl "http://localhost:3000/v1/messages?limit=50" ^
  -H "x-api-key: wk_live_YOUR_KEY"
```

### Older messages (scroll back)

```bash
curl "http://localhost:3000/v1/messages?to=918056515399&order=asc&limit=40" ^
  -H "x-api-key: wk_live_YOUR_KEY"

curl "http://localhost:3000/v1/messages?to=918056515399&order=asc&before=1786817228&beforeId=3EB0..." ^
  -H "x-api-key: wk_live_YOUR_KEY"
```

### Query parameters

| Param | Description |
| --- | --- |
| `to` or `phone` | Chat number. Omit to get recent messages from all chats |
| `limit` | Max messages (default 50, max 200) |
| `order` | `asc` for oldest-first in a chat |
| `before` | Unix timestamp to page older messages |
| `beforeId` | Message id tie-break with `before` |
| `from` | Linked WhatsApp `accountId` |

### Response

```json
{
  "accountId": "298281c1c0b468f2765f448856e65cac",
  "messages": [
    {
      "id": "3EB0...",
      "chatId": "918056515399@s.whatsapp.net",
      "phone": "918056515399",
      "fromMe": false,
      "text": "Done",
      "type": "text",
      "timestamp": 1786817228,
      "status": "delivered"
    }
  ]
}
```

## Incoming webhook

Set `WEBHOOK_URL` in `.env`. Each new **inbound** message is POSTed as JSON:

```json
{
  "accountId": "298281c1c0b468f2765f448856e65cac",
  "id": "3EB0...",
  "phone": "918056515399",
  "text": "Hi",
  "fromMe": false
}
```

## Credits

| Pack | Messages | Price |
| --- | --- | --- |
| Starter | 100 | ₹10 |
| Growth | 500 | ₹45 |
| Pro | 1000 | ₹90 |
| Business | 5000 | ₹400 |

Buy packs from the dashboard. Signup includes 10 free credits.