# List messages

> Instagram, Facebook, and WhatsApp message history, oldest first.

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

`GET https://app.tryadeli.com/api/v1/messages`

Authorization: `Bearer <API key>` — see [Authentication](https://www.tryadeli.com/docs/authentication)

Returns a flat array across the profile's Instagram, Facebook, and WhatsApp
conversations, oldest first by `occurredAt`. Uses the
[aggregate response contract](https://www.tryadeli.com/docs/concepts#partial-responses).

**Query parameters**

| Name        | Type                                      | Required | Description                                                                                                                                                                                          |
| ----------- | ----------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `platform`  | `"instagram" \| "facebook" \| "whatsapp"` |          | Return one provider's messages only. `facebook` covers every connected Facebook Page's Messenger conversations. Anything else, including `tiktok` and `youtube`, returns `422 unsupported_platform`. |
| `accountId` | `uuid`                                    |          | Narrow to one connected account.                                                                                                                                                                     |
| `profileId` | `uuid`                                    |          | Required unless you pass accountId, which names its profile. If you pass both, they must agree.                                                                                                      |

**Message fields**

| Name         | Type                                    | Required | Description                                                                                               |
| ------------ | --------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `id`         | `string`                                |          | Adeli's identifier for this message.                                                                      |
| `providerId` | `string \| null`                        |          | The provider's message id.                                                                                |
| `direction`  | `"inbound" \| "outbound"`               |          | Relative to the connected account.                                                                        |
| `type`       | `"text" \| "template" \| "unsupported"` |          | `unsupported` covers media and other payloads Adeli does not normalize.                                   |
| `sender`     | `string \| null`                        |          | Set on inbound messages — the provider-scoped participant id (an IGSID on Instagram, a PSID on Facebook). |
| `recipient`  | `string \| null`                        |          | Set on outbound messages.                                                                                 |
| `status`     | `string`                                |          | Provider delivery state, such as `received` or `sent`.                                                    |
| `occurredAt` | `ISO 8601`                              |          | When the provider recorded the message. Sort on this.                                                     |

If a provider sync fails, Adeli still returns the messages it has already
persisted and reports the failure in `errors`, which makes the response `207`.

**Errors** — `401 unauthorized`, `400 invalid_request`,
`422 unsupported_platform`, `404 profile_not_found`, `404 account_not_found`,
`502 provider_error`.

## Request examples

**cURL**

```bash
curl --fail-with-body "https://app.tryadeli.com/api/v1/messages?platform=instagram&accountId=00000000-0000-0000-0000-000000000000" \
  -H "Authorization: Bearer $ADELI_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch("https://app.tryadeli.com/api/v1/messages?platform=instagram&accountId=00000000-0000-0000-0000-000000000000", {
  headers: {
    Authorization: `Bearer ${process.env.ADELI_API_KEY}`,
  },
});
console.log(await response.json());
```

**Python**

```python
import os

import requests

response = requests.get(
    "https://app.tryadeli.com/api/v1/messages",
    headers={"Authorization": f"Bearer {os.environ['ADELI_API_KEY']}"},
    params={
        "platform": "instagram",
        "accountId": "00000000-0000-0000-0000-000000000000",
    },
)
print(response.json())
```

## Responses

### 200

```json
{
  "status": "complete",
  "messages": [
    {
      "id": "instagram_message_aWdfbWlk",
      "providerId": "aWdfbWlk",
      "platform": "instagram",
      "accountId": "00000000-0000-0000-0000-000000000000",
      "profileId": "00000000-0000-4000-8000-000000000001",
      "direction": "inbound",
      "type": "text",
      "recipient": null,
      "sender": "17841400000000001",
      "body": "Do you ship to Canada?",
      "status": "received",
      "occurredAt": "2026-04-01T12:00:00.000Z",
      "createdAt": "2026-04-01T12:00:01.000Z"
    }
  ],
  "errors": []
}
```

### 422

```json
{
  "error": {
    "code": "unsupported_platform",
    "message": "Unsupported platform"
  }
}
```