Set a set of additional content blocks in the activity crm.activity.layout.blocks.set

Choose a tool for developing with an AI agent:

use Alaio Vibecode to build an app for Bitrix24 from a task description without knowing any programming language. The agent writes the code and deploys the app to a server, with no manual hosting setup
use the MCP server to develop a REST API integration in your own project. The agent refers to the official REST documentation

Scope: crm

Who can execute the method: any user with permission to modify the CRM entity to which the activity is linked

The method crm.activity.layout.blocks.set installs a set of additional content blocks in an activity.

The method only works in the context of the application: when called via a webhook, it returns the ERROR_WRONG_CONTEXT error. The application modifies only the set of blocks that it installed itself. Calling the method again replaces this set entirely.

The method works only with activities. To install a set of blocks in a comment or another timeline entry, use crm.timeline.layout.blocks.set.

A set of blocks cannot be installed in a configurable activity or in an activity of a deprecated type — the timeline does not render such an activity as a configurable entry. In these cases, the method returns the UNSUITABLE_ACTIVITY_TYPE_ERROR error. The suitability of an activity cannot be determined in advance from REST data, the only way to check is a trial call.

If the activity is linked to several CRM entities at once, the set of blocks remains a single one and is displayed in the timeline of every linked entity. The links are managed by the crm.activity.binding.* methods.

The order in which the methods are called and the general rules for working with block sets are described in the section overview.

Method Parameters

Required parameters are marked with *

Name `type`	Description
entityTypeId* `integer`	Identifier of the CRM object type to which the activity is linked, for example `2` for a deal
entityId* `integer`	Identifier of the CRM object to which the activity is linked, for example the deal identifier
activityId* `integer`	Identifier of the activity. It is returned by the crm.activity.add and crm.activity.list methods
layout* `RestAppLayoutDto`	Object describing the set of additional content blocks (detailed description)

Parameter layout

Name `type`	Description
blocks* `object`	Associative array of content blocks. The key is the block identifier, the value is the block description

Limitations on blocks:

the blocks field is required, otherwise the method returns the FIELD_IS_REQUIRED error
a set can contain no more than 20 blocks, otherwise the method returns the TOO_MANY_ITEMS error
a block key can contain only Latin letters, digits, hyphens, and underscores, otherwise the method returns the KEY_CONTAIN_WRONG_SYMBOLS error
a block type must be on the list of allowed types, otherwise the method returns the ENUM_FIELD error

Each block is described by the type and properties fields. The composition of properties depends on the block type:

type	What It Displays	Required `properties` Fields
`text`	A line of formatted text	`value`
`largeText`	Long text collapsed into a preview	`value`
`link`	A link with an action on click	`text`, `action`
`deadline`	The activity deadline, which can be changed right in the block	No required fields
`withTitle`	A title — value pair, where the value is a nested block of the `text`, `link`, or `deadline` type	`title`, `block`
`lineOfBlocks`	Several blocks of the `text`, `link`, or `deadline` type in a single line	`blocks`

The full list of fields for each type, including the optional ones, is provided in the description of the ContentBlockDto structure.

Display Features

If different applications have added their own sets of additional content blocks to an activity, the sets are displayed in the order they were added.

In the HTML markup, data attributes show which application added the set of additional content blocks:

data-app-name — application name
data-rest-client-id — application identifier

Code Examples

Install a set of four additional content blocks in the activity with id = 8, linked to the deal with id = 4:

text
long multiline text
link
block with a title

How to Use Examples in Documentation

cURL (OAuth)

JS (TS)

JS (UMD)

Python

PHP

BX24.js

PHP CRest

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"entityTypeId":2,"entityId":4,"activityId":8,"layout":{"blocks":{"block_1":{"type":"text","properties":{"value":"Hello!\nWe are starting.","multiline":true,"bold":true,"color":"base_90"}},"block_2":{"type":"largeText","properties":{"value":"Hello!\nWe are starting.\nWe are continuing.\nWe are still working on this.\nWe are continuing.\nWe are close to the result.\nGoodbye."}},"block_3":{"type":"link","properties":{"text":"Open deal","bold":true,"action":{"type":"redirect","uri":"/crm/deal/details/123/"}}},"block_4":{"type":"withTitle","properties":{"title":"Title","block":{"type":"text","properties":{"value":"Some value"}}}}}},"auth":"**put_access_token_here**"}' \
        https://**put_your_bitrix24_address**/rest/crm.activity.layout.blocks.set

// This snippet is an ES module: top-level await requires type="module" or a bundler.
        // $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
        import { Text } from '@bitrix24/b24jssdk'
        import type { B24Frame } from '@bitrix24/b24jssdk'
        
        declare const $b24: B24Frame
        
        // Shape of the payload returned in result (match the "response handling" section of the page)
        type SetLayoutBlocksResult = {
          success: boolean
        }
        
        try {
          const response = await $b24.actions.v2.call.make<SetLayoutBlocksResult>({
            method: 'crm.activity.layout.blocks.set',
            params: {
              entityTypeId: 2, // Deal
              entityId: 4,     // Deal ID
              activityId: 8,   // Activity ID linked to the deal
              layout: {
                blocks: {
                  block_1: {
                    type: 'text',
                    properties: {
                      value: 'Hello!\nWe are starting.',
                      multiline: true,
                      bold: true,
                      color: 'base_90',
                    },
                  },
                  block_2: {
                    type: 'largeText',
                    properties: {
                      value: 'Hello!\nWe are starting.\nWe are continuing.\nWe are still working on this.\nWe are continuing.\nWe are close to the result.\nGoodbye.',
                    },
                  },
                  block_3: {
                    type: 'link',
                    properties: {
                      text: 'Open deal',
                      bold: true,
                      action: {
                        type: 'redirect',
                        uri: '/crm/deal/details/123/',
                      },
                    },
                  },
                  block_4: {
                    type: 'withTitle',
                    properties: {
                      title: 'Header',
                      block: {
                        type: 'text',
                        properties: {
                          value: 'Some value',
                        },
                      },
                    },
                  },
                },
              },
            },
            requestId: Text.getUuidRfc4122()
          })
        
          // The payload is available only on a successful response
          if (!response.isSuccess) {
            console.error(response.getErrorMessages().join('; '))
          } else {
            const result = response.getData()!.result
            console.info('Layout blocks set successfully:', result.success)
          }
        } catch (error) {
          // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
          console.error(error)
        }

<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
        <script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
        <script>
          async function setActivityLayoutBlocks() {
            try {
              // Initialize the SDK inside a Bitrix24 frame
              const $b24 = await B24Js.initializeB24Frame()
        
              const response = await $b24.actions.v2.call.make({
                method: 'crm.activity.layout.blocks.set',
                params: {
                  entityTypeId: 2, // Deal
                  entityId: 4,     // Deal ID
                  activityId: 8,   // Activity ID linked to the deal
                  layout: {
                    blocks: {
                      block_1: {
                        type: 'text',
                        properties: {
                          value: 'Hello!\nWe are starting.',
                          multiline: true,
                          bold: true,
                          color: 'base_90',
                        },
                      },
                      block_2: {
                        type: 'largeText',
                        properties: {
                          value: 'Hello!\nWe are starting.\nWe are continuing.\nWe are still working on this.\nWe are continuing.\nWe are close to the result.\nGoodbye.',
                        },
                      },
                      block_3: {
                        type: 'link',
                        properties: {
                          text: 'Open deal',
                          bold: true,
                          action: {
                            type: 'redirect',
                            uri: '/crm/deal/details/123/',
                          },
                        },
                      },
                      block_4: {
                        type: 'withTitle',
                        properties: {
                          title: 'Header',
                          block: {
                            type: 'text',
                            properties: {
                              value: 'Some value',
                            },
                          },
                        },
                      },
                    },
                  },
                },
                requestId: B24Js.Text.getUuidRfc4122()
              })
        
              // The payload is available only on a successful response
              if (!response.isSuccess) {
                console.error(response.getErrorMessages().join('; '))
                return
              }
        
              const result = response.getData().result
              console.info('Layout blocks set successfully:', result.success)
            } catch (error) {
              // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
              console.error(error)
            }
          }
        
          document.addEventListener('DOMContentLoaded', setActivityLayoutBlocks)
        </script>


        from b24pysdk.errors import BitrixAPIError, BitrixSDKException
        
        try:
            bitrix_response = client.crm.activity.layout.blocks.set(
                entity_type_id=2,
                entity_id=4,
                activity_id=8,
                layout={
                    "blocks": {
                        "block_1": {
                            "type": "text",
                            "properties": {
                                "value": "Hello!\nWe are starting.",
                                "multiline": True,
                                "bold": True,
                                "color": "base_90",
                            },
                        },
                        "block_2": {
                            "type": "largeText",
                            "properties": {
                                "value": "Hello!\nWe are starting.\nWe are continuing.\nWe are still working on this.\nWe are continuing.\nWe are close to the result.\nGoodbye.",
                            },
                        },
                        "block_3": {
                            "type": "link",
                            "properties": {
                                "text": "Open deal",
                                "bold": True,
                                "action": {
                                    "type": "redirect",
                                    "uri": "/crm/deal/details/123/",
                                },
                            },
                        },
                        "block_4": {
                            "type": "withTitle",
                            "properties": {
                                "title": "Title",
                                "block": {
                                    "type": "text",
                                    "properties": {
                                        "value": "Some value",
                                    },
                                },
                            },
                        },
                    },
                },
            ).response
            result = bitrix_response.result
            print(result)
        except BitrixAPIError as error:
            print(
                "Bitrix API error",
                f"error: {error.error}",
                f"error_description: {error.error_description}",
                sep="\n",
            )
        except BitrixSDKException as error:
            print(f"Bitrix SDK error: {error.message}")
        except Exception as error:
            print(f"Unexpected error: {error}")

try {
            $response = $b24Service
                ->core
                ->call(
                    'crm.activity.layout.blocks.set',
                    [
                        'entityTypeId' => 2, // Deal
                        'entityId'     => 4, // Deal ID
                        'activityId'   => 8, // ID of the deal linked to this deal
                        'layout'       => [
                            'blocks' => [
                                'block_1' => [
                                    'type'       => "text",
                                    'properties' => [
                                        'value'     => "Hello!\nWe are starting.",
                                        'multiline' => true,
                                        'bold'      => true,
                                        'color'     => "base_90",
                                    ],
                                ],
                                'block_2' => [
                                    'type'       => "largeText",
                                    'properties' => [
                                        'value' => "Hello!\nWe are starting.\nWe are continuing.\nWe are still working on this.\nWe are continuing.\nWe are close to the result.\nGoodbye.",
                                    ],
                                ],
                                'block_3' => [
                                    'type'       => "link",
                                    'properties' => [
                                        'text'     => "Open deal",
                                        'bold'     => true,
                                        'action'   => [
                                            'type' => "redirect",
                                            'uri'  => "/crm/deal/details/123/",
                                        ],
                                    ],
                                ],
                                'block_4' => [
                                    'type'       => "withTitle",
                                    'properties' => [
                                        'title'  => "Title",
                                        'block'  => [
                                            'type'       => "text",
                                            'properties' => [
                                                'value' => "Some value",
                                            ],
                                        ],
                                    ],
                                ],
                            ],
                        ],
                    ]
                );
        
            $result = $response
                ->getResponseData()
                ->getResult();
        
            echo 'Success: ' . print_r($result, true);
        
        } catch (Throwable $e) {
            error_log($e->getMessage());
            echo 'Error setting activity layout blocks: ' . $e->getMessage();
        }

const layout = {
            blocks: {
                'block_1': {
                    type: "text",
                    properties: {
                        value: "Hello!\nWe are starting.",
                        multiline: true,
                        bold: true,
                        color: "base_90"
                    }
                },
                'block_2': {
                    type: "largeText",
                    properties: {
                        value: "Hello!\nWe are starting.\nWe are continuing.\nWe are still working on this.\nWe are continuing.\nWe are close to the result.\nGoodbye."
                    }
                },
                'block_3': {
                    type: "link",
                    properties: {
                        text: "Open deal",
                        bold: true,
                        action: {
                            type: "redirect",
                            uri: "/crm/deal/details/123/"
                        }
                    }
                },
                'block_4': {
                    type: "withTitle",
                    properties: {
                        title: "Title",
                        block: {
                            type: "text",
                            properties: {
                                value: "Some value"
                            }
                        }
                    }
                }
            }
        };
        BX24.callMethod(
            'crm.activity.layout.blocks.set',
            {
                entityTypeId: 2, // Deal
                entityId: 4,     // Deal ID
                activityId: 8,   // ID of the activity linked to this deal
                layout: layout,  // Object describing the set of additional content blocks
            },
            (result) => {
                if (result.error()) {
                    console.error(result.error());
                } else {
                    console.info(result.data());
                }
            },
        );

require_once('crest.php');
        $result = CRest::call(
            'crm.activity.layout.blocks.set',
            [
                'entityTypeId' => 2,
                'entityId' => 4,
                'activityId' => 8,
                'layout' => [
                    'blocks' => [
                        'block_1' => [
                            'type' => "text",
                            'properties' => [
                                'value' => "Hello!\nWe are starting.",
                                'multiline' => true,
                                'bold' => true,
                                'color' => "base_90"
                            ]
                        ],
                        'block_2' => [
                            'type' => "largeText",
                            'properties' => [
                                'value' => "Hello!\nWe are starting.\nWe are continuing.\nWe are still working on this.\nWe are continuing.\nWe are close to the result.\nGoodbye."
                            ]
                        ],
                        'block_3' => [
                            'type' => "link",
                            'properties' => [
                                'text' => "Open deal",
                                'bold' => true,
                                'action' => [
                                    'type' => "redirect",
                                    'uri' => "/crm/deal/details/123/"
                                ]
                            ]
                        ],
                        'block_4' => [
                            'type' => "withTitle",
                            'properties' => [
                                'title' => "Title",
                                'block' => [
                                    'type' => "text",
                                    'properties' => [
                                        'value' => "Some value"
                                    ]
                                ]
                            ]
                        ]
                    ]
                ]
            ]
        );
        echo '';
        print_r($result);
        echo '';

// client and ctx are already created — see the Go SDK section
        res, err := client.Core().Call(ctx, "crm.activity.layout.blocks.set", b24.Params{
        	"entityTypeId": 2,
        	"entityId":     4,
        	"activityId":   8,
        	"layout": b24.Params{
        		"blocks": b24.Params{
        			"block_1": b24.Params{
        				"type": "text",
        				"properties": b24.Params{
        					"value":     "Hello!\nWe are starting.",
        					"multiline": true,
        					"bold":      true,
        					"color":     "base_90",
        				},
        			},
        			"block_2": b24.Params{
        				"type": "largeText",
        				"properties": b24.Params{
        					"value": "Hello!\nWe are starting.\nWe are continuing.\nWe are still working on this.\nWe are continuing.\nWe are close to the result.\nGoodbye.",
        				},
        			},
        			"block_3": b24.Params{
        				"type": "link",
        				"properties": b24.Params{
        					"text": "Open deal",
        					"bold": true,
        					"action": b24.Params{
        						"type": "redirect",
        						"uri":  "/crm/deal/details/123/",
        					},
        				},
        			},
        			"block_4": b24.Params{
        				"type": "withTitle",
        				"properties": b24.Params{
        					"title": "Title",
        					"block": b24.Params{
        						"type": "text",
        						"properties": b24.Params{
        							"value": "Some value",
        						},
        					},
        				},
        			},
        		},
        	},
        })
        if err != nil {
        	return fmt.Errorf("crm.activity.layout.blocks.set: %w", err)
        }
        
        // The response arrives as json.RawMessage — unmarshal it
        // into a struct matching the response shape shown below on this page.
        fmt.Printf("%s\n", res.Result)

Response Handling

HTTP status: 200

{
            "result": {
                "success": true
            },
            "time": {
                "start": 1753341040.475739,
                "finish": 1753341040.582705,
                "duration": 0.10696601867675781,
                "processing": 0.04708504676818848,
                "date_start": "2025-07-24T17:57:20+00:00",
                "date_finish": "2025-07-24T17:57:20+00:00",
                "operating": 0
            }
        }

Returned Data

Name `type`	Description
result `object`	Root element of the response (detailed description). If the set of blocks could not be installed, the method returns an `error` object instead of `result` — see the "Error Handling" section
time `time`	Information about the request execution time

Object result

Name `type`	Description
success `boolean`	Result of installing the set of additional content blocks. The field is returned when the method completes successfully and has the value `true`

The method does not return the installed set of blocks itself in the response. To read the stored set, call crm.activity.layout.blocks.get.

After the call from the example above, the activity looks like this:

Example

Error Handling

HTTP status: 400

{
            "error": "ERROR_WRONG_CONTEXT",
            "error_description": "The method call is only possible in the context of a REST application"
        }

Name `type`	Description
error `string`	String error code. It consists of digits, Latin letters, and underscores. It may arrive empty — in that case only `error_description` shows the reason
error_description `string`	Error message for the developer. Do not show it to the end user without processing

Possible Error Codes

Code	Description
`ERROR_WRONG_CONTEXT`	The method can only be called in the context of a REST application. The method was called via a webhook
`OWNER_NOT_FOUND`	The element to which the activity is linked was not found. An unknown `entityTypeId` was passed, or the activity is not linked to the element with the specified `entityId`
`NOT_FOUND`	The activity with the specified `activityId` was not found
`ACCESS_DENIED`	The user has no permission to modify the CRM entity to which the activity is linked
`UNSUITABLE_ACTIVITY_TYPE_ERROR`	The activity type is not suitable for adding a set of additional content blocks
`FIELD_IS_REQUIRED`	A required field of the structure was not passed: `blocks` in `RestAppLayoutDto`, or a `properties` field of a block, for example `value` for a block of the `text` type
`FIELD_IS_REDUNDANT`	The structure object contains a field that is not in its description
`TOO_MANY_ITEMS`	More than 20 blocks were passed in `blocks`
`KEY_CONTAIN_WRONG_SYMBOLS`	A block key in `blocks` contains invalid characters
`WRONG_FIELD_VALUE`	The field value does not match the expected type, for example a block was passed as something other than an object
`ENUM_FIELD`	The `type` field of a block contains a value that is not on the list of allowed types

The error text specifies which field and which structure object caused it.

Statuses and System Error Codes

HTTP Status: 4xx, 5xx

The errors described below are returned by the REST API itself, not by the logic of a specific method. They can arrive in response to any method.

Status	Code Error Message	Description
`500`	`INTERNAL_SERVER_ERROR` Internal server error	An internal server error has occurred. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support
`500`	`ERROR_UNEXPECTED_ANSWER` Server returned an unexpected response	The server returned an unexpected response. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support
`503`	`QUERY_LIMIT_EXCEEDED` Too many requests	The request intensity limit has been exceeded
`429`	`OPERATION_TIME_LIMIT` Method is blocked due to operation time limit	The method is blocked because the request resource intensity limit has been exceeded. The block is lifted automatically once the accumulated execution time of the method no longer exceeds the limit
`401`	`NO_AUTH_FOUND` Wrong authorization data	The request contains no authorization data: neither an access token nor a webhook code was passed
`401`	`INVALID_REQUEST` Https required	Methods are called over the HTTPS protocol only
`401`	`OVERLOAD_LIMIT` REST API is blocked due to overload	The REST API is blocked due to overload. This is a manual individual block. To have it lifted, contact Bitrix24 technical support
`401`	`ACCESS_DENIED` REST is available only on commercial plans	REST API access is not active for this account. In Bitrix24 Cloud, check the current plan or trial status: Vibe+ plans include REST API access, while Essentials plans do not. A webhook receives a different error message — `REST is available only by subscription`
`401`	`INVALID_CREDENTIALS` Invalid request credentials	No active webhook with the specified user identifier and secret code was found
`404`	`ERROR_METHOD_NOT_FOUND` Method not found!	No method with this name was found. The name is misspelled, the method does not exist in the REST API, or it is unavailable without the required scope
`401`	`insufficient_scope` The request requires higher privileges than provided by the webhook token	The request requires broader permissions than the token has: for a webhook these are the permissions granted to it, for an application it is the scope. For an application, the error message ends with `provided by the access token`
`401`	`expired_token` The access token provided has expired	The access token has expired
`401`	`user_access_error` The user does not have access to the application	The application is installed, but the Bitrix24 administrator has granted access to it only to specific users
`403`	`PORTAL_DELETED` Portal was deleted	The public part of the site is closed. To open it on an on-premise installation, disable the "Temporary closure of the public part of the site" option. Path to the setting: Desktop > Settings > Product Settings > Module Settings > Main Module > Temporary closure of the public part of the site

Continue Learning

Was the article helpful?

Overview of Methods

Retrieve a Set of Additional Content Blocks

Set a set of additional content blocks in the activity crm.activity.layout.blocks.set

Method ParametersMethod Parameters

Parameter layoutParameter layout

Display FeaturesDisplay Features

Code ExamplesCode Examples

Response HandlingResponse Handling

Returned DataReturned Data

Object resultObject result

Error HandlingError Handling

Possible Error CodesPossible Error Codes

Statuses and System Error CodesStatuses and System Error Codes

Continue LearningContinue Learning