# List messages

Source: https://docs.vlayers.ai/reference/messages/list-messages

`GET /v1/messages` · scope `messages:read`

Returns messages across your workspace, oldest first, filtered by conversation, channel or direction. Use it to backfill history or to poll for new messages with `after`; for real-time delivery, prefer webhooks or the event stream.

Requires an API key with the `messages:read` scope.

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `conversationId` | query | string | no | Only messages in this conversation. Example: `"0192f5b0-7c3e-7a51-9b2d-4e8f1a6c3d21"` |
| `channel` | query | string | no | Only messages on this channel. Example: `"sms"` |
| `direction` | query | "inbound" \| "outbound" | no | `inbound` (people writing to you) or `outbound` (what you sent). Example: `"inbound"` |
| `after` | query | string | no | A page's `nextCursor`: return what came after it. Use it to poll for new messages. Example: `"eyJjIjoiMjAyNi0xMC0yMFQxNTowNDowNVoifQ"` |
| `before` | query | string | no | A page's `prevCursor`: return what came before it. Pass `end` for the newest page. Example: `"end"` |
| `limit` | query | integer | no | How many items to return, 1–100. Default 50. Example: `20` |

## Request

cURL:

```bash
curl "https://api.vlayers.ai/v1/messages?direction=inbound&limit=20" \
  -H "Authorization: Bearer $VOICELAYER_API_KEY"
```

TypeScript:

```ts
import { createVoiceLayerClient, listMessages } from '@voicelayer/api';

const client = createVoiceLayerClient({ apiKey: process.env.VOICELAYER_API_KEY!, throwOnError: true });

const { data } = await listMessages({
  client,
  query: {
    direction: 'inbound',
    limit: 20
  }
});
console.log(data.messages);
```

Python:

```python
import os
import voicelayer

config = voicelayer.Configuration(access_token=os.environ["VOICELAYER_API_KEY"])
with voicelayer.ApiClient(config) as client:
    api = voicelayer.MessagesApi(client)
    result = api.list_messages(
        direction="inbound",
        limit=20,
    )
    print(result.messages)
```

## Response `200`

```json
{
  "messages": [
    {
      "id": "0192f5b0-8d1f-7b62-8c3e-5f9a2b7d4e32",
      "conversationId": "0192f5b0-7c3e-7a51-9b2d-4e8f1a6c3d21",
      "channel": "sms",
      "direction": "inbound",
      "status": "received",
      "text": "Do you have a table for two tonight?",
      "media": [],
      "from": "+15550123",
      "to": "+14155550100",
      "bindingId": null,
      "metadata": {},
      "error": null,
      "createdAt": "2026-10-20T15:04:05.000Z"
    }
  ],
  "nextCursor": "eyJjIjoiMjAyNi0xMC0yMFQxNTowNDowNVoifQ",
  "hasMore": false,
  "prevCursor": null
}
```