# 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 resolves the chat from the task ID itself, so you never need to know the chat id. A typical scenario is pulling the final messages of a closed task.

Bitrix24 API: `im.v2.Chat.Message.tail` (on older Bitrix24 accounts — `im.dialog.messages.get`)
Scope: `task`, `im`

## Query parameters

| Parameter | Type | Req. | Description |
|----------|-----|:-----:|---------|
| `limit` | number | | Messages per page, 1..200, default 50 |
| `lastId` | number | | Cursor: return messages older than this `id`. For the next page pass the minimal `id` of the current one |

## Example

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

Response:

```json
{
  "success": true,
  "data": {
    "messages": [
      {
        "id": 9123,
        "authorId": 20294,
        "text": "Release 24.500.0 is ready",
        "createdAt": "2026-06-10T14:51:00+02:00",
        "isSystem": false
      }
    ],
    "hasNextPage": true
  }
}
```

## Message fields

| Field | Description |
|------|---------|
| `id` | Message ID — use the minimal one from the page as `lastId` for the next page |
| `authorId` | Author (`0` for system messages) |
| `text` | Message text. May contain Bitrix24 BB-codes |
| `createdAt` | Creation date, ISO 8601 |
| `isSystem` | System message ("task created", "deadline changed", …) — filter on this flag when you only need human replies |

## What to know before you start

1. **The `im` B24 scope is required.** The endpoint reads the chat through Bitrix24 `im.*` methods — the key's webhook/OAuth grant must include the `im` scope in addition to `task`, otherwise the Bitrix24 account returns `insufficient_scope`.
2. **Access follows chat membership.** Bitrix24 returns messages only when the key's B24 user is a member of the task chat (creator, assignee, watcher) or a Bitrix24 account administrator.
3. **Messages come newest-first.** The first element is the most recent message. Cursor pagination via `lastId` goes back through history.
4. **404 when there is no chat yet.** Bitrix24 creates the task chat lazily — a task with no chat messages may have no chat at all (`TASK_CHAT_NOT_FOUND`).
5. **Older Bitrix24 accounts.** On Bitrix24 accounts without the modern `im.v2` surface the API transparently switches to the legacy method: the page is capped at 50 messages there and `hasNextPage` is derived from page fullness.
6. **Comments vs chat.** [`GET /v1/tasks/:taskId/comments`](../task-comments.md) returns only human comments; this endpoint returns the raw chat feed in full, including system messages.

## Errors

| HTTP | Code | Cause |
|------|-----|---------|
| 400 | `INVALID_PARAMS` | Non-numeric `taskId`, non-numeric/non-positive `limit` or `lastId` (`limit` above 200 is not an error — it is silently capped to 200) |
| 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) |

## See also

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