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 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

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 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 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