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

Batch comment operations

POST /v1/tasks/:taskId/comments/batch

Bulk create, update, or delete comments on a single task. Up to 50 items per call. Each item is processed independently — a failure in one item does not cancel the rest.

Parameters

Parameter Type Required Description
ParametertaskId (path) Typenumber Requiredyes DescriptionTask ID

Request fields (body)

Field Type Required Description
Fieldaction Typestring Required★ DescriptionOperation type: create, update or delete
Fielditems Typearray Requiredfor create / update DescriptionList of items (up to 50). For create: [{ message: string }]. For update: [{ id: number, message: string }]
Fieldids Typenumber[] Requiredfor delete DescriptionComment identifiers to delete (up to 50)

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/tasks/289/comments/batch" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "create",
    "items": [
      { "message": "Step 1: prepared the draft." },
      { "message": "Step 2: sent it for review." }
    ]
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/tasks/289/comments/batch" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "create",
    "items": [
      { "message": "Step 1: prepared the draft." },
      { "message": "Step 2: sent it for review." }
    ]
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/tasks/289/comments/batch', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    action: 'create',
    items: [
      { message: 'Step 1: prepared the draft.' },
      { message: 'Step 2: sent it for review.' },
    ],
  }),
})

const { success, data } = await res.json()
data.forEach((item) => {
  if (item.success) console.log(`#${item.index} → id=${item.id}`)
  else console.log(`#${item.index} → error: ${item.error}`)
})

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/tasks/289/comments/batch', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    action: 'create',
    items: [
      { message: 'Step 1: prepared the draft.' },
      { message: 'Step 2: sent it for review.' },
    ],
  }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true — even if every item failed, the top level still reports success. Check each item's status in data[i]
Fielddata Typearray DescriptionArray of results in the same order as the request items / ids
Fielddata[].index Typenumber DescriptionItem index (0-based)
Fielddata[].success Typeboolean DescriptionResult of the specific operation
Fielddata[].id Typenumber | null DescriptionComment ID on create / update. Occasionally null with success: true — the comment was created but its ID wasn't recovered (see POST /v1/tasks/:taskId/comments "Known specifics"). If Bitrix24 didn't create the comment at all (task doesn't exist/isn't accessible) that's a different case — success: false + error: TASK_NOT_FOUND, no ID is returned
Fielddata[].error Typestring DescriptionError code for a failed item (GONE, READONLY_FIELD, BATCH_ITEM_VALIDATION, BITRIX_ERROR, INVALID_PARAMS, TASK_NOT_FOUND)
Fielddata[].message Typestring DescriptionError text for a failed item

Response example

action: create on the new card — both records went into the task chat:

JSON 
{
  "success": true,
  "data": [
    { "index": 0, "success": true, "id": 36571 },
    { "index": 1, "success": true, "id": 36573 }
  ]
}

action: update on the new card — every update attempt turns into GONE (method unavailable):

JSON 
{
  "success": true,
  "data": [
    {
      "index": 0,
      "success": false,
      "error": "GONE",
      "message": "Bitrix24 disabled update/delete for task comments in the new task card. To remove a comment, delete the source task or ask a portal admin to remove the message via the chat UI."
    }
  ]
}

Error response example

400 — invalid action value:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_BATCH_ACTION",
    "message": "Action must be one of: create, update, delete"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptiontaskId is not a positive integer
HTTP400 CodeINVALID_BATCH_ACTION Descriptionaction is not create, update or delete
HTTP400 CodeBATCH_ITEM_VALIDATION Descriptionitems (or ids for delete) is empty or not an array
HTTP400 CodeBATCH_LIMIT_EXCEEDED DescriptionMore than 50 items passed in a single request
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the task scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens

Errors for individual items are returned inside data[i].error:

Code Description
CodeGONE DescriptionOnly for update / delete on the new card — the operation is unavailable on the Bitrix24 side
CodeREADONLY_FIELD DescriptionAn update item contains a read-only field (ID, taskId, authorId, createdAt, or an alias); that item is not sent to Bitrix24
CodeBATCH_ITEM_VALIDATION DescriptionThe item failed validation (for example, no id or message, wrong type)
CodeINVALID_PARAMS Descriptionmessage is missing or exceeds the length limit
CodeBITRIX_ERROR DescriptionBitrix24 returned an error for the specific item (text in message)
CodeTASK_NOT_FOUND DescriptionOnly for create — task taskId doesn't exist or isn't accessible to the key, so the comment is not created

Full list of common API errors — Errors.

Known specifics

The top-level success is always true if the request passed validation. Failed items inside the batch do not turn the whole response into an error — this is intentional so the client can handle a partial result. Before using the result, always check data[i].success for each item.

READONLY_FIELD arrives separately for each item. The batch keeps HTTP 200 and top-level success: true: the forbidden item gets success: false, is not sent to Bitrix24, and valid sibling items are still processed. Lowercase id remains the comment selector; for example, an additional ID in the same item is treated as a forbidden data field.

GONE arrives separately for each item. On the new card, update / delete of each item returns GONE, but the overall response stays 200 success — the whole batch is not rejected. In mixed scenarios, some items on the old card go through, others on the new card return GONE.

create distinguishes "not created" from "created, id unknown". If the task doesn't exist/isn't accessible, the item fails with TASK_NOT_FOUND (success: false, no id). If the comment was genuinely created (it went to the task's chat) but the system couldn't confirm its id via a search over recent messages, the item stays success: true with id: null — retrying will create a duplicate, not recover the original id.

See also