# Messages

> Read Instagram and Facebook message history, and send text replies to both.

Canonical: <https://www.tryadeli.com/docs/api/messages>

Instagram direct messages and Facebook Page messages, normalized into one
shape. Adeli refreshes history from the provider before returning it, so a read
is live rather than a cache.

> **Warning: Meta providers only**
>
> TikTok messaging is not supported, and YouTube has no messaging API at all —
> its direct messages were retired in 2019. WhatsApp sends approved templates rather than
> free text through the API — see [WhatsApp](https://www.tryadeli.com/docs/api/messages#whatsapp) below.

> **Note: Both providers reply inside a 24-hour window**
>
> Meta only permits a reply within 24 hours of the person's last message, on
> Instagram and on Facebook alike. When Meta refuses a send because the window
> has closed, Adeli returns `409 window_closed`; you cannot open one by sending
> first.

## Endpoints

- `GET /api/v1/messages` — [List messages](https://www.tryadeli.com/docs/api/messages/list-messages.md)
- `POST /api/v1/messages` — [Send message](https://www.tryadeli.com/docs/api/messages/send-message.md)

## WhatsApp

Each profile can hold one WhatsApp number that the business connected itself,
through Embedded Signup on the dashboard's **Accounts** page. It appears in
`GET /api/v1/accounts` with `platform: "whatsapp"`, the phone number ID as
`providerId`, and the display number as `displayIdentifier`, and its history is
included in `GET /api/v1/messages`. WhatsApp history is what Adeli has received
by webhook and sent, so a read makes no provider call.

Through the API, WhatsApp sends one of the business's **approved templates** —
the only message WhatsApp allows when starting a conversation or more than 24
hours after the customer last wrote.

**WhatsApp body**

| Name                      | Type         | Required | Description                                                                                                           |
| ------------------------- | ------------ | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `platform`                | `"whatsapp"` | Yes      |                                                                                                                       |
| `accountId`               | `uuid`       | Yes      | The WhatsApp account in your organization.                                                                            |
| `profileId`               | `uuid`       |          | Optional, because accountId names its profile. If you pass both, they must agree.                                     |
| `recipient`               | `string`     | Yes      | An E.164 phone number, such as `+15551234567`.                                                                        |
| `template.name`           | `string`     | Yes      | An approved template on the business's WhatsApp Business Account: lowercase letters, digits, and underscores.         |
| `template.language`       | `string`     | Yes      | The template's language, such as `en_US`.                                                                             |
| `template.bodyParameters` | `string[]`   |          | Values for the body's `{{1}}`, `{{2}}`, … placeholders, in order. Up to 20; omit for a template without placeholders. |

```json
{
  "platform": "whatsapp",
  "accountId": "00000000-0000-0000-0000-000000000000",
  "recipient": "+15551234567",
  "template": { "name": "order_update", "language": "en_US", "bodyParameters": ["Jane", "A-42"] }
}
```

Success returns `201` with `type: "template"`. A number whose setup has not
finished returns `422 setup_incomplete`; one whose access the business revoked
returns `422 reconnect_required`. An unknown or unapproved template fails at
Meta and surfaces as `502 provider_error`.

WhatsApp numbers cannot be connected through `POST /api/v1/profiles/{profileId}/connect`
yet — that returns `422 provider_not_supported`.