For AI agents: markdown of this page — /docs-content-en/chats/messages/blocks.md documentation index — /llms.txt

Message blocks

A constructor message consists of blocks: text, a heading, an image and other elements that Bitrix24 assembles into one message. These calls add, replace and delete the blocks of such a message. The v2 messenger methods: im.v2.Chat.Message.Block.Element.append, im.v2.Chat.Message.Block.Element.update and im.v2.Chat.Message.Block.Element.delete.

Add a block

POST /v1/chats/messages/:messageId/blocks

Adds a block to the end of the message.

Parameters

Parameter Type Required Default Description
messageId (path) number yes — ID of the constructor message, a positive integer
element (body) object yes — A block in the Bitrix24 constructor format: type and the fields of that type, for example { "type": "text", "text": "Build passed" }

Other body fields and query parameters are rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/chats/messages/1001/blocks" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "element": { "type": "text", "text": "Build passed" } }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/chats/messages/1001/blocks" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "element": { "type": "text", "text": "Build passed" } }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/messages/1001/blocks', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ element: { type: 'text', text: 'Build passed' } }),
})

const { data } = await res.json()
console.log('Block added:', data.result)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/messages/1001/blocks', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ element: { type: 'text', text: 'Build passed' } }),
})

const { data } = await res.json()
console.log('Block added:', data.result)

Replace a block

PATCH /v1/chats/messages/:messageId/blocks/:blockId

Replaces the block entirely. The block ID is kept.

Parameters

Parameter Type Required Default Description
messageId (path) number yes — ID of the constructor message, a positive integer
blockId (path) string yes — Block ID — block.elements[].id of the message
element (body) object yes — The new block in the constructor format

Other body fields and query parameters are rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/chats/messages/1001/blocks/650a1b2c3d4e5" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "element": { "type": "text", "text": "Build failed" } }'

curl — OAuth application

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/chats/messages/1001/blocks/650a1b2c3d4e5" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "element": { "type": "text", "text": "Build failed" } }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/messages/1001/blocks/650a1b2c3d4e5', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ element: { type: 'text', text: 'Build failed' } }),
})

const { data } = await res.json()
console.log('Block replaced:', data.result)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/messages/1001/blocks/650a1b2c3d4e5', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ element: { type: 'text', text: 'Build failed' } }),
})

const { data } = await res.json()
console.log('Block replaced:', data.result)

Delete a block

DELETE /v1/chats/messages/:messageId/blocks/:blockId

Parameters

Parameter Type Required Default Description
messageId (path) number yes — ID of the constructor message, a positive integer
blockId (path) string yes — Block ID

No body is needed. Query parameters and body fields are rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

Terminal 
curl -X DELETE "https://vibecode.bitrix24.com/v1/chats/messages/1001/blocks/650a1b2c3d4e5" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -X DELETE "https://vibecode.bitrix24.com/v1/chats/messages/1001/blocks/650a1b2c3d4e5" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/messages/1001/blocks/650a1b2c3d4e5', {
  method: 'DELETE',
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data } = await res.json()
console.log('Block deleted:', data.result)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/messages/1001/blocks/650a1b2c3d4e5', {
  method: 'DELETE',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()
console.log('Block deleted:', data.result)

Response fields

Field Type Description
success boolean Always true on success
data.result boolean true — the block was added, replaced or deleted

Response example

JSON 
{
  "success": true,
  "data": { "result": true }
}

Error response example

422 — the message has no blocks:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "BLOCK_NOT_FOUND",
    "b24Code": "BLOCK_NOT_FOUND"
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS messageId is not a positive integer; element is missing or not an object; an extra body field or a query parameter. Checked before any call to Bitrix24
404 ENTITY_NOT_FOUND Bitrix24 returned "not found"; the portal code is in error.b24Code
422 BITRIX_ERROR Bitrix24 returned an error; the portal code is in error.b24Code. BLOCK_NOT_FOUND — the message has no blocks; ELEMENT_NOT_FOUND — there is no block with this ID; WRONG_ELEMENT_TYPE, EMPTY_TEXT_FIELD — the block is malformed; BLOCK_LENGTH_EXCEEDED — the message blocks exceed the limit; MESSAGE_ACCESS_DENIED — the message cannot be edited
403 SCOPE_DENIED The API key does not have the im scope
403 WRITE_BLOCKED_READONLY_KEY The key is read-only — see access rights
401 TOKEN_MISSING The API key has no Bitrix24 tokens configured

The full list of common API errors — Errors.

Known specifics

Constructor messages only. Blocks exist only on a message sent with blocks. A plain message has none, and Bitrix24 returns BLOCK_NOT_FOUND — a plain message cannot be turned into a constructor message.

The response does not include the new block's ID. Adding a block returns { "result": true }. Read block IDs from block.elements[].id of the message — for example, with messages around a message.

Bitrix24 checks the block shape. The platform only checks that element is an object and passes it as is. Block types and their fields are defined by the Bitrix24 constructor.

Whoever can edit the message can edit its blocks. Usually that is the author; Bitrix24 refuses everyone else with MESSAGE_ACCESS_DENIED.

See also