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

# WhatsApp

> Send and receive WhatsApp Business messages through the SmartlyQ API.

SmartlyQ connects to the **WhatsApp Business Cloud API** (Meta), so you can send session and template messages, receive inbound messages and delivery receipts via webhooks, and manage templates and the business profile.

## Connect a number

There are two ways to connect a WhatsApp number.

**In the app (recommended).** In **Settings → WhatsApp**, click **Connect with WhatsApp** and complete Meta's Embedded Signup popup - sign in, pick your WhatsApp Business Account and phone number, and you're done. SmartlyQ exchanges the returned code for a system-user token, subscribes to the number's webhooks, and stores the connection. No tokens to copy.

**Over the API (headless).** For server-to-server onboarding, supply your WhatsApp Business Account id, the phone number id, and a Meta system-user access token:

```bash theme={null}
curl -X POST https://api.smartlyq.com/v1/social/connect/whatsapp \
  -H "Authorization: Bearer sqk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "waba_id": "1234567890", "phone_number_id": "9876543210", "access_token": "EAAG..." }'
```

Either way, the token is verified against the number and stored encrypted; the connected number appears in `GET /v1/social/accounts` (platform `whatsapp`). Its `id` is the `account_id` you pass to every WhatsApp call below.

## Send a message

`POST /v1/whatsapp/messages`. There are three message kinds, and **which you can send depends on the 24-hour window**:

* **`text`** and **`media`** are *session* messages - deliverable only within 24 hours of the customer's last message to you.
* **`template`** (an approved HSM) is the only kind deliverable *outside* that window.

```json Text (session) theme={null}
{ "account_id": 42, "to": "+14155551234", "type": "text", "text": "Thanks for reaching out!" }
```

```json Template (any time) theme={null}
{
  "account_id": 42, "to": "+14155551234", "type": "template",
  "template": { "name": "order_update", "language": "en_US",
    "components": [{ "type": "body", "parameters": [{ "type": "text", "text": "#A1234" }] }] }
}
```

```json Media (session) theme={null}
{ "account_id": 42, "to": "+14155551234", "type": "media",
  "media": { "kind": "image", "link": "https://cdn.example.com/receipt.png", "caption": "Your receipt" } }
```

A `502` means WhatsApp rejected it - most commonly sending a session message outside the 24-hour window (send a template instead).

## Receive messages

Inbound messages and delivery receipts arrive on **your webhooks**, not by polling (the Cloud API has no message-history endpoint). Subscribe to:

| Event               | Fires when                                               |
| ------------------- | -------------------------------------------------------- |
| `message.received`  | A customer sends you a message (lands in your inbox too) |
| `message.delivered` | Your outbound message reached the recipient              |
| `message.read`      | The recipient opened your message                        |
| `message.failed`    | Your outbound message failed, with the platform error    |

See the [Webhooks guide](/guides/webhooks). Inbound messages also populate the in-app Inbox automatically.

## Templates

* `GET /v1/whatsapp/templates?account_id=42` - list templates and their approval status.
* `POST /v1/whatsapp/templates` - submit a new template (`name`, `category` = `MARKETING`/`UTILITY`/`AUTHENTICATION`, `language`, `components`) for Meta approval.

## Business profile

* `GET /v1/whatsapp/business-profile?account_id=42` - read about/address/email/websites/vertical.
* `PATCH /v1/whatsapp/business-profile` - update any of those fields.

## Phone numbers

`GET /v1/whatsapp/phone-numbers?account_id=42` lists the numbers on the connection's WhatsApp Business Account with their display number, verified name, and quality rating.

## Limits & restrictions

WhatsApp messaging is governed by both Meta's platform rules and your SmartlyQ plan. Knowing these avoids surprises:

**Meta (platform) rules — enforced by WhatsApp:**

* **24-hour customer service window** — free-form `text` and `media` messages are only deliverable within 24 hours of the customer's last message to you. Outside it, you must use an approved `template`. A `502` on a session message almost always means the window has closed.
* **Messaging tiers** — a new number can start \~250 unique customers per 24 hours, rising to 1K → 10K → 100K → unlimited as your volume and quality grow. Meta raises the tier automatically.
* **Quality rating** — each number carries a green / yellow / red rating. Too many blocks or reports lowers it and can throttle or restrict the number, so keep messaging relevant and opt-in.
* **Template categories** — templates are `MARKETING`, `UTILITY`, or `AUTHENTICATION`, and each must be approved by Meta before it can be sent. Marketing templates are subject to per-user frequency caps.
* **Throughput** — Meta accepts roughly 80 messages/second per number by default. SmartlyQ paces sends under this automatically so a burst can't trip the throttle.

**SmartlyQ (plan) limits:**

* **Monthly message cap** — each plan includes a monthly WhatsApp send allowance. When it's reached, `POST /whatsapp/messages` returns `429 LIMIT_REACHED` until the next month or a plan upgrade. This is separate from Meta's tiers.
* **Connected numbers** count toward your plan's connected-account limit, like any other channel.