> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wsapi.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Overview of the WSAPI HTTP REST API

The WSAPI provides a RESTful HTTP API for sending WhatsApp messages, managing contacts, groups, chats, and more. All requests are authenticated and use JSON payloads.

## Base URL

```
https://api.wsapi.chat
```

All API requests use HTTPS encryption.

## Authentication

Every request requires two headers:

| Header          | Description                             |
| --------------- | --------------------------------------- |
| `X-Api-Key`     | Your account API key                    |
| `X-Instance-Id` | The target WhatsApp instance identifier |

```bash theme={null}
curl -X GET https://api.wsapi.chat/chats \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Instance-Id: YOUR_INSTANCE_ID"
```

<Warning>
  Keep your API key secret. Rotate it immediately if you suspect exposure.
</Warning>

## Request format

* **Method**: Use the appropriate HTTP method (`GET`, `POST`, `PUT`, `DELETE`)
* **Headers**: Include authentication headers and `Content-Type: application/json`
* **Body**: JSON-formatted request body for `POST` and `PUT` requests

### Example: Send a text message

```bash theme={null}
curl -X POST https://api.wsapi.chat/messages/text \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Instance-Id: YOUR_INSTANCE_ID" \
  -d '{
    "to": "1234567890@s.whatsapp.net",
    "message": "Hello from WSAPI!"
  }'
```

## Response codes

| Code  | Meaning                                                   |
| ----- | --------------------------------------------------------- |
| `200` | Success — response body contains the result               |
| `201` | Created — resource was created successfully               |
| `202` | Accepted — request accepted for asynchronous processing   |
| `204` | No Content — request succeeded with no response body      |
| `400` | Bad Request — invalid parameters or payload               |
| `401` | Unauthorized — invalid or missing API key                 |
| `403` | Forbidden — insufficient permissions                      |
| `404` | Not Found — resource doesn't exist                        |
| `409` | Device Not Paired — instance is not connected to WhatsApp |
| `429` | Rate Limited — too many requests                          |
| `500` | Server Error — something went wrong on our end            |

## Phone number format

WhatsApp uses the JID (Jabber ID) format for phone numbers:

* **Individual chats**: `{countryCode}{number}@s.whatsapp.net` (e.g., `1234567890@s.whatsapp.net`)
* **Group chats**: `{groupId}@g.us`

<Note>
  Do not include the `+` prefix in phone numbers. Use the raw digits with country code.
</Note>

## Resources

The API is organized into the following resource groups:

<CardGroup cols={2}>
  <Card title="Messages" icon="message">
    Send text, media, documents, stickers, locations, contacts, and reactions
  </Card>

  <Card title="Chats" icon="comments">
    List, archive, pin, mute, and manage chat settings
  </Card>

  <Card title="Contacts" icon="address-book">
    List, create, update contacts and retrieve profile pictures
  </Card>

  <Card title="Groups" icon="users">
    Create groups, manage participants, update settings and invite links
  </Card>

  <Card title="Session" icon="plug">
    Get QR codes, pairing codes, connection status, and logout
  </Card>

  <Card title="Instance" icon="server">
    Manage instance settings, restart, and update configuration
  </Card>

  <Card title="Account" icon="user">
    Get and update your WhatsApp profile name, picture, status, and presence
  </Card>

  <Card title="Media" icon="image">
    Download and manage media files
  </Card>

  <Card title="Newsletters" icon="newspaper">
    Newsletter and channel management
  </Card>

  <Card title="Status" icon="circle-dot">
    Status and stories posting
  </Card>

  <Card title="Calls" icon="phone">
    Call management
  </Card>

  <Card title="Communities" icon="building">
    Community and sub-group management
  </Card>
</CardGroup>

## Tools

* **OpenAPI Spec** — available for download and import into API clients
* **Interactive Playground** — test endpoints directly from the API Reference pages

Browse the full endpoint list in the sidebar, or use the interactive playground to make test requests.