# PaalChat Documentation

Connect your customers' WhatsApp Business numbers and message their customers from one API.

PaalChat connects PaalTech products - Multi-SKUUL, SKUUL, Basic SKUUL, PaalPOS and
the ones to come - to the WhatsApp Business Platform. It runs Meta's Embedded
Signup for your customers, keeps their Meta credentials, sends and receives
WhatsApp messages, and tells your product what happened through signed callbacks.

Your product never holds a Meta token and never calls Meta. It calls PaalChat and
receives callbacks. Use the guides when you need context, then switch to the
[API Reference](/docs/api) for exact request and response details.

The API lives at `https://whatsapp.paaltech.org/api/v1`.

## Jump right in

- [Quickstart](/docs/quickstart) - Make your first authenticated request and send a template message.
- [Connect WhatsApp](/docs/connect-whatsapp) - Send your customer to the hosted Meta signup and know when they are connected.
- [Send messages](/docs/sending-messages) - Templates, free-form text, the 24-hour window and safe references.
- [Receive messages](/docs/receiving-messages) - Build an inbox from message.received callbacks and reply in time.
- [Callbacks](/docs/callbacks) - Verify signatures, acknowledge fast and handle retries.
- [API Reference](/docs/api) - Every endpoint, parameter, response and error.

## How it fits together

```text
 Your product (e.g. Multi-SKUUL)          PaalChat                                Meta
 ─────────────────────────────           ────────                               ──────
 POST /businesses          ───────────▶  business "presec"
 POST .../whatsapp/connect ───────────▶  one-time link ─────────────▶ school admin opens it,
                                          hosted signup page ◀──────▶ Embedded Signup (Meta login)
                                          verifies with Meta, stores
                                          the encrypted token
 ◀── callback whatsapp.connection (connected)
 POST .../messages         ───────────▶  queued ──────────────────▶ Cloud API /messages
 ◀── callback message.status (sent, delivered, read / failed)  ◀── Meta webhook
                                          customer replies ◀──────── Meta webhook
 ◀── callback message.received
```

Three parties, three kinds of identifiers:

| Who | Identified by | Example |
|---|---|---|
| Your product | its API token | `7\|ptw_4gV...` |
| Your customer (a school, a shop) | **your** `external_id` | `presec` (Multi-SKUUL: the tenant ID) |
| Meta objects | Meta's numeric IDs | WABA `102290129340398`, phone number `106540352242922` |

PaalChat never needs to know your database. It only stores the `external_id` you give it.

## Requests and responses

- JSON in and out: send `Content-Type: application/json` and `Accept: application/json`.
- Successful responses wrap the resource in `data`; lists add `links` and `meta` for paging.
- Every error has the same shape: `{"error": {"code": "...", "message": "..."}}`. See [Errors and status codes](/docs/errors).
- Timestamps are ISO 8601 in UTC. Meta IDs are strings.

## Downloads

- [Postman collection](/docs/paalchat.postman_collection.json) - every endpoint, with variables for the base URL, token and business.
- [OpenAPI 3.1 spec](/openapi.yaml) - for client generators.
- [AI version](/docs/ai) - every page as Markdown, plus `llms.txt`.

## Next steps

1. [Get a token and make your first call](/docs/quickstart).
2. [Understand abilities](/docs/authentication) and ask only for what you need.
3. [Go through the go-live checklist](/docs/go-live-checklist) before production.