# List messages

> Page through the messages you sent and received, newest first, filtered by direction and status.

`GET https://api-connect.nxiom.com/api/v1/messaging/messages`

## Authorization

Requires `whatsapp.full_access`, because the list includes messages your customers sent you. WhatsApp must be turned on for your organization.

## Query parameters

| Field | Type | Description |
| --- | --- | --- |
| `page` | integer · optional | Page number, from `1` to `10000`. Default `1`. |
| `limit` | integer · optional | 1–100. Default `50`. |
| `channel` | string · optional | `whatsapp`. Only messages of this channel. |
| `direction` | string · optional | `outbound` or `inbound`. `outbound` for messages you sent, `inbound` for messages your customers sent you. |
| `status` | string · optional | Only messages with this status, such as `delivered`, `failed`, or `received`. See [the message object](/docs/api/messaging/retrieve#the-message-object). |

## Request

### cURL

```shell
curl "https://api-connect.nxiom.com/api/v1/messaging/messages?direction=inbound&page=1&limit=50" \
  -H "Authorization: Bearer $NEXIOM_API_KEY"
```

### Node.js

```typescript
const apiKey = process.env.NEXIOM_API_KEY;
if (!apiKey) throw new Error('Set NEXIOM_API_KEY');

const response = await fetch(
  'https://api-connect.nxiom.com/api/v1/messaging/messages?direction=inbound&page=1&limit=50',
  {
    method: 'GET',
    headers: {
      Authorization: `Bearer ${apiKey}`,
    },
  },
);

const result = await response.json();
if (!response.ok) {
  throw new Error(result.message ?? `HTTP ${response.status}`);
}
console.log(result);
```

### PHP

```php
<?php

$apiKey = getenv('NEXIOM_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set NEXIOM_API_KEY');
}

$request = curl_init("https://api-connect.nxiom.com/api/v1/messaging/messages?direction=inbound&page=1&limit=50");
curl_setopt_array($request, [
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $apiKey",
    ],
]);

$raw = curl_exec($request);
$status = curl_getinfo($request, CURLINFO_HTTP_CODE);
$error = curl_error($request);
curl_close($request);

if ($raw === false) {
    throw new RuntimeException($error);
}
$result = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
if ($status >= 400) {
    throw new RuntimeException($result["message"] ?? "HTTP $status");
}
print_r($result);
```

## Response

HTTP `200`. Results are under `data`, newest first, with page-based [pagination](/docs/api/pagination).

| Field | Type | Description |
| --- | --- | --- |
| `items` | array | Messages on this page. |
| `total` | number | Messages matching the filters. |
| `page` | number | The page returned. |
| `limit` | number | The page size. |

Each item has `id`, `channel`, `direction`, `status`, `sender`, `recipient`, `failure_code`, `is_billable`, `cost`, `cost_currency`, and the timestamps `created_at`, `accepted_at`, `sent_at`, `delivered_at`, `read_at`, and `failed_at`, as in [the message object](/docs/api/messaging/retrieve#the-message-object). [Retrieve a message](/docs/api/messaging/retrieve) for its type, template, content, including each card of a carousel, and conversation. Messages are kept for 30 days.

### 200 OK

Example response. Identifiers are illustrative.

```json
{
  "message": "Messages fetched",
  "data": {
    "items": [
      {
        "id": "msg_example",
        "channel": "whatsapp",
        "direction": "inbound",
        "status": "received",
        "sender": "+213555123456",
        "recipient": "+213555000111",
        "failure_code": null,
        "is_billable": false,
        "cost": "0.0000",
        "cost_currency": "DZD",
        "created_at": "2026-10-14T10:02:05.000Z",
        "accepted_at": null,
        "sent_at": "2026-10-14T10:02:03.000Z",
        "delivered_at": null,
        "read_at": null,
        "failed_at": null
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 50
  }
}
```

### 400 Bad Request

The request is invalid. Correct it before retrying; `details` lists the failing fields.

```json
{
  "error": "invalid_argument",
  "message": "Request doesn't match the schema",
  "correlationId": "req_example",
  "details": {
    "context": "body",
    "issues": []
  }
}
```

### 401 Unauthorized

The API key is missing, malformed, revoked, or expired.

```json
{
  "error": "unauthorized",
  "message": "Invalid API key",
  "correlationId": "req_example"
}
```

### 403 Forbidden

The API key lacks whatsapp.full_access, or WhatsApp is not turned on for your organization (code: FEATURE_NOT_AVAILABLE).

```json
{
  "error": "not_allowed",
  "message": "Missing required API key permissions: whatsapp.full_access",
  "correlationId": "req_example"
}
```

---

Source: https://connect.nxiom.com/docs/api/messaging/list