## Read messages

`GET /v1/chats/:dialogId/messages`

Returns dialog messages with cursor-based pagination. The `me` alias as `dialogId` addresses the current user's personal dialog — see more in the [Chats overview](/docs/chats).

## Parameters

| Parameter | Type | Req. | Default | Description |
|----------|-----|:-----:|-----------|---------|
| `dialogId` (path) | string | yes | — | Dialog ID: numeric user ID for personal messages, `chatXXX` for group chats. The special `me` alias — the current user's personal dialog |
| `limit` (query) | number | no | 50 | Number of messages per page |
| `lastId` (query) | number | no | — | Cursor to load older messages: return messages with an ID lower than the given one |
| `firstId` (query) | number | no | — | Cursor to load newer messages: return messages with an ID higher than the given one |

## Examples

### curl — personal key

```bash
curl "https://vibecode.bitrix24.com/v1/chats/chat42/messages?limit=20" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl "https://vibecode.bitrix24.com/v1/chats/chat42/messages?limit=20" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — personal key

```javascript
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/chats/chat42/messages?limit=20',
  {
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
    },
  }
)

const { success, data } = await res.json()
console.log('Messages:', data.messages)
console.log('Participants:', data.users)
```

### JavaScript — OAuth application

```javascript
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/chats/chat42/messages?limit=20',
  {
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)

const { success, data } = await res.json()
```

## Response fields

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data.chatId` | number | Chat ID |
| `data.messages` | array | Array of messages |
| `data.messages[].id` | number | Message ID |
| `data.messages[].chatId` | number | ID of the chat the message belongs to |
| `data.messages[].authorId` | number | Message author ID. `0` — system message |
| `data.messages[].date` | string | Sent date (ISO 8601) |
| `data.messages[].text` | string | Message text |
| `data.messages[].unread` | boolean | Not read by the current user |
| `data.messages[].uuid` | string\|null | Unique message identifier (set by the sender) |
| `data.messages[].replaces` | array | List of replaced message IDs |
| `data.messages[].params` | array\|object | Additional message parameters (formatting, system markers) |
| `data.messages[].disappearingDate` | string\|null | Message auto-deletion date (ISO 8601) or `null` |
| `data.users` | array | Dialog participants with profiles |
| `data.users[].id` | number | User ID |
| `data.users[].name` | string | Display name |
| `data.users[].active` | boolean | Whether the user is active in the Bitrix24 account |
| `data.files` | array | Files attached to messages |

## Response example

```json
{
  "success": true,
  "data": {
    "chatId": 42,
    "messages": [
      {
        "id": 1001,
        "chatId": 42,
        "authorId": 5,
        "date": "2026-06-05T10:00:00+00:00",
        "text": "Good afternoon! How are you?",
        "unread": false,
        "uuid": null,
        "replaces": [],
        "params": [],
        "disappearingDate": null
      },
      {
        "id": 1002,
        "chatId": 42,
        "authorId": 7,
        "date": "2026-06-05T10:01:00+00:00",
        "text": "All good, thanks.",
        "unread": true,
        "uuid": null,
        "replaces": [],
        "params": [],
        "disappearingDate": null
      }
    ],
    "users": [
      {
        "id": 5,
        "active": true,
        "name": "John Brown",
        "firstName": "John",
        "lastName": "Brown",
        "workPosition": "Manager",
        "color": "#3bc8f5",
        "gender": "M",
        "bot": false,
        "type": "user"
      }
    ],
    "files": []
  }
}
```

## Error response example

422 — dialog not found or no access:

```json
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Access denied"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 422 | `BITRIX_ERROR` | Bitrix24 returned an error — dialog not found or no access (text in the `message` field) |
| 404 | `ENTITY_NOT_FOUND` | Bitrix24 returned a NOT_FOUND error |
| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unavailable or returned a server error |
| 502 | `ME_ALIAS_RESOLUTION_FAILED` | Failed to resolve the user when using the `me` alias |
| 403 | `SCOPE_DENIED` | The key is missing the `im` scope |
| 401 | `TOKEN_MISSING` | No `X-Api-Key` was passed or tokens are not configured |

Full list of common API errors — [Errors](/docs/errors).

## Known specifics

**Cursor-based pagination.** The endpoint uses cursor pagination, not page-number offset. To load older messages, pass `lastId` equal to the smallest `id` from the last response. To load newer ones, pass `firstId` equal to the largest `id`.

**Message order.** Messages are returned in descending order — from newest to oldest.

## See also

- [Messages](/docs/chats/messages)
- [Send a message](/docs/chats/messages/send)
- [Chat discovery](/docs/chats/discovery/get)