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

Task comments

Comments are a nested task resource. Each comment has an author, text, and creation time. The base path is /v1/tasks/:taskId/comments. All operations require an existing task (:taskId) on the Bitrix24 account.

Bitrix24 API: tasks.task.chat.message.*, task.commentitem.* Scope: task

Create comment

POST /v1/tasks/:taskId/comments

Adds a comment to a task. On the new task card the message is posted to the chat; on the old one it lands in the comments block inside the card itself.

Parameters

Parameter Type Required Description
taskId (path) number yes Task ID

Request fields (body)

Field Type Required Description
message string ★ Comment text, up to 65,535 characters. Supports BB-code ([USER=ID]Name[/USER], [B]...[/B], [QUOTE]...[/QUOTE])

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/tasks/289/comments" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Added a draft of the report — please take a look."
  }'

curl — OAuth app

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/tasks/289/comments" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Added a draft of the report — please take a look."
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/tasks/289/comments', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    message: 'Added a draft of the report — please take a look.',
  }),
})

const { success, data } = await res.json()
console.log('New comment ID:', data.id)

JavaScript — OAuth app

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/tasks/289/comments', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    message: 'Added a draft of the report — please take a look.',
  }),
})

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

Response fields

Field Type Description
success boolean Always true on success
data.id number | null New comment identifier. On the new card the chat-message id is returned; in a rare case it may be null — see "Known specifics"

Response example

HTTP 201 Created:

JSON 
{
  "success": true,
  "data": {
    "id": 36559
  }
}

Error response example

400 — empty or missing message:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "`message` is required and must be a string"
  }
}

404 — the task doesn't exist or isn't accessible:

JSON 
{
  "success": false,
  "error": {
    "code": "TASK_NOT_FOUND",
    "message": "Bitrix24 did not create the comment (returned false). Task 99999999 may not exist or may not be accessible."
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS taskId is not a positive integer
400 INVALID_PARAMS The message field is missing or is not a string
400 INVALID_PARAMS message exceeds the length limit
403 SCOPE_DENIED The API key does not have the task scope
401 TOKEN_MISSING The API key has no configured tokens
404 TASK_NOT_FOUND Task taskId doesn't exist or isn't accessible to the key — Bitrix24 didn't create the comment

Full list of common API errors — Errors.

Known specifics

data.id is occasionally null on success (success: true). On the new task card the comment goes to chat (tasks.task.chat.message.send), and the id is recovered by a separate search over recent chat messages. If recovering the id fails (the message wasn't found in the search window), the comment was already created, but the response returns id: null — this is not an error, and retrying the request will create a duplicate. If Bitrix24 didn't create the comment at all (the task doesn't exist or isn't accessible), that's a different case — the API returns 404 TASK_NOT_FOUND instead of 201 with id: null.

See also