For AI agents: markdown of this page — /docs-content-en/entities/tasks/chat.md documentation index — /llms.txt

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 Required Description
limit number Messages per page, 1..200, default 50. For a read-only key, at most 50: a larger value is reduced to 50
lastId number Cursor: return messages older than this id. For the next page, pass the smallest id from the current page

Example

Terminal 
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 smallest one on 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 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.
  2. 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.
  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, and hasNextPage is inferred from whether the page is full.
  6. Comments vs chat. GET /v1/tasks/:taskId/comments returns only user 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 capped at 200, and at 50 for a read-only key)
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.

See also