# Task chat

`GET /v1/tasks/:taskId/chat/messages`

Reads the task's chat feed — newest messages first. Every task in Bitrix24 has a group chat, and the endpoint itself resolves the chat from the task ID, so you do not need to know the chat ID. A typical scenario is exporting the final messages of a closed task.

The generic `filter` parameter is not applied by this endpoint. By default, the API preserves the previous HTTP 200 response and data, adds `Warning: 299 - "filter is not supported on this endpoint and was ignored"`, and records unsupported-filter use in the server log.

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|---------|
| `taskId` (path) | number | yes | Task ID. List: [`GET /v1/tasks`](/docs/entities/tasks/list) |
| `limit` (query) | number | no | Messages per page, 1..200, default 50. For a read-only key, at most 50: a larger value is reduced to 50 |
| `lastId` (query) | number | no | Cursor: return messages older than this `id`. For the next page, pass the smallest `id` from the current one |

## Examples

### curl — personal key

```bash
curl 'https://vibecode.bitrix24.com/v1/tasks/289/chat/messages?limit=50' \
  -H 'X-Api-Key: YOUR_API_KEY'
```

### curl — OAuth application

```bash
curl 'https://vibecode.bitrix24.com/v1/tasks/289/chat/messages?limit=50' \
  -H 'X-Api-Key: YOUR_APP_KEY' \
  -H 'Authorization: Bearer USER_SESSION_TOKEN'
```

### JavaScript — personal key

```javascript
const response = await fetch('https://vibecode.bitrix24.com/v1/tasks/289/chat/messages?limit=50', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})
const result = await response.json()
console.log(result.data.messages)
```

### JavaScript — OAuth application

```javascript
const response = await fetch('https://vibecode.bitrix24.com/v1/tasks/289/chat/messages?limit=50', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const result = await response.json()
console.log(result.data.messages)
```

## Response fields

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | `true` on success |
| `data.messages` | array | Messages on the page, newest to oldest |
| `data.messages[].id` | number | Message ID — use the smallest one on the page as `lastId` for the next page |
| `data.messages[].authorId` | number | Author (`0` for system messages) |
| `data.messages[].text` | string | Message text. May contain Bitrix24 BB-code |
| `data.messages[].createdAt` | string | Creation date, ISO 8601 |
| `data.messages[].isSystem` | boolean | System message ("task created", "deadline changed", …) — filter on this flag when you only need human replies |
| `data.hasNextPage` | boolean | Whether there is a next page. When `true`, pass the smallest `id` of the current page as `lastId` |

## Response example

```json
{
  "success": true,
  "data": {
    "messages": [
      {
        "id": 43247,
        "authorId": 0,
        "text": "[USER=1]John Smith[/USER] started the task.",
        "createdAt": "2026-10-19T18:20:03+00:00",
        "isSystem": true
      },
      {
        "id": 43241,
        "authorId": 0,
        "text": "[USER=1]John Smith[/USER] created [URL=/company/personal/user/1/tasks/task/view/289/]this task[/URL].",
        "createdAt": "2026-10-19T18:20:00+00:00",
        "isSystem": true
      }
    ],
    "hasNextPage": false
  }
}
```

## Error response example

404 — the task has no chat, or the task does not exist:

```json
{
  "success": false,
  "error": {
    "code": "TASK_CHAT_NOT_FOUND",
    "message": "Task 289 has no chat yet (B24 allocates the chat lazily) or the task does not exist."
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 200 | `Warning: 299` | The filter is ignored by default; previous data is preserved and the warning is sent in the `Warning` header. |
| 400 (strict mode only) | `UNSUPPORTED_FILTER` | The server mode is disabled by default; until it is enabled, the endpoint preserves HTTP 200 and the previous data. |
| 400 | `INVALID_PARAMS` | `taskId` is not a positive integer: `taskId must be a positive integer` |
| 400 | `INVALID_PARAMS` | `limit` is not a positive integer: `limit must be a positive integer (1..200)`. A `limit` above 200 is not an error — it is capped at 200, and at 50 for a read-only key |
| 400 | `INVALID_PARAMS` | `lastId` is not a positive integer: `lastId must be a positive integer (message id cursor)` |
| 401 | `MISSING_API_KEY` | `X-Api-Key` is missing |
| 401 | `INVALID_API_KEY` | The key is not found |
| 401 | `TOKEN_MISSING` | The key has no valid Bitrix24 token |
| 403 | `SCOPE_DENIED` | The key lacks the `task` scope |
| 404 | `TASK_CHAT_NOT_FOUND` | The task has no chat (or the task does not exist) |
| 422 | `BITRIX_ERROR` | Bitrix24 error: `insufficient_scope` (no `im`), `ACCESS_ERROR` (not a chat member) |

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

## Known specifics

- **The `im` scope is required on the Bitrix24 side.** The endpoint reads the chat through Bitrix24 `im.*` methods — the key's webhook or OAuth grant must include the `im` scope in addition to `task`; otherwise Bitrix24 returns `insufficient_scope`.
- **Access follows chat membership.** Bitrix24 returns messages only when the user the key acts on behalf of is a member of the task chat (creator, assignee, observer) or a Bitrix24 account administrator. A read-only key reads the feed in a different way that does not make the user a member of the chat, so its page holds at most 50 messages whatever the `limit`. For such a key, `hasNextPage` means the page is full: if the last page holds exactly as many messages as fit on it, you get `true`, and the next request returns an empty page with `false`. Page through with the `lastId` cursor until `hasNextPage: false`. Up to 200 messages per page are returned to a key with write access — see [access rights](/docs/access-rights).
- **Messages come newest-first.** The first element is the most recent message. Cursor pagination via `lastId` goes back through history.
- **404 when there is no chat yet.** Bitrix24 does not create the task chat right away — a task without a single message may have no chat (`TASK_CHAT_NOT_FOUND`).
- **Older Bitrix24 accounts.** On Bitrix24 accounts without the modern `im.v2` surface, the API transparently switches to the legacy method: the page there is capped at 50 messages, and `hasNextPage` is inferred from whether the page is full.
- **Comments vs chat.** [`GET /v1/tasks/:taskId/comments`](../task-comments.md) returns only user comments. This endpoint returns the raw chat feed in full, including system messages.

## See also

- [Tasks](/docs/entities/tasks)
- [Task comments](/docs/entities/task-comments)
- [Scrum](/docs/scrum)