Structure of Configurable Activity
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
LayoutDto is the top-level object that describes the appearance of a timeline entry. The application builds the whole entry from it: the icon, the heading with tags, the content area, and the bottom part with buttons and a menu.
The object is passed in the layout parameter of the crm.activity.configurable.add and crm.activity.configurable.update methods. The crm.activity.configurable.get method returns the same structure in the layout field of the response.
On update, the structure is replaced as a whole, the fields are not merged. Pass layout in full even if only one block has changed.
The structure is hierarchical: each LayoutDto field is a standalone object with its own set of fields, described on a separate page. Such objects are called DTO, Data Transfer Object.
LayoutDto describes the entire entry and works only for activities created by the application itself. To add your own blocks to someone else's timeline entry, use a different object — RestAppLayoutDto.
Scope:
crmWho can execute the method: a user with edit access to the CRM object the activity is linked to. Without such access the method returns the
ACCESS_DENIEDerror
The methods that accept LayoutDto work only within the context of an application. Calling them via an inbound webhook returns the ERROR_WRONG_CONTEXT error.
Parameters of the LayoutDto Object
Required parameters are marked with *
|
Field |
Description |
|
icon* |
Icon to the left of the entry |
|
header* |
Title of the record |
|
body* |
Main content area of the entry |
|
footer |
Bottom part of the entry with action block |
How to Build the Structure
- Fill in the required
icon,header, andbodyfields, and if the entry has actions — the optionalfooterwith buttons and menu items. - Assemble the entry content from content blocks — they live in
body.blocks. - Describe the reaction to clicks —
ActionDto. This object is accepted by the heading, tags, logo, links, buttons, and menu items. - Pass the finished structure in the
layoutparameter of the crm.activity.configurable.add method.
Texts the user sees accept the textWithTranslation type — they can be passed in several languages at once.
The scope field of blocks, buttons, and menu items hides the element in the browser or in the mobile app. It is not related to the application scope.
Structure Restrictions
|
Restriction |
Error Code |
|
No more than two tags in the heading |
|
|
No more than two buttons in the bottom part |
|
|
No more than 20 content blocks in the main area |
|
|
No more than ten menu items and no more than ten menu sections |
|
|
Keys of the |
|
|
A required field of the object is not passed |
|
|
A field not present in the object description is passed |
|
|
The field value is not in the list of allowed values, for example an unknown tag type |
|
|
A multi-language value contains a language code not installed in Bitrix24 |
|
The full list of errors is on the crm.activity.configurable.add and crm.activity.configurable.update pages.
Object Example
An entry about an incoming call: an icon, a heading with a tag, the customer and the assignee in the content area, a button that opens the app, and two menu items.
{
"icon": {
"code": "call-completed"
},
"header": {
"title": "Incoming call",
"tags": {
"status2": {
"type": "warning",
"title": "not transcribed"
}
}
},
"body": {
"logo": {
"code": "call-incoming",
"action": {
"type": "redirect",
"uri": "/crm/deal/details/123/"
}
},
"blocks": {
"client": {
"type": "withTitle",
"properties": {
"title": "Client",
"inline": true,
"block": {
"type": "text",
"properties": {
"value": "Müller GmbH"
}
}
}
},
"responsible": {
"type": "lineOfBlocks",
"properties": {
"blocks": {
"name": {
"type": "link",
"properties": {
"text": "Klaus Weber",
"bold": true,
"action": {
"type": "redirect",
"uri": "/crm/lead/details/789/"
}
}
},
"phone": {
"type": "text",
"properties": {
"value": "+49 999 888 7777"
}
}
}
}
}
}
},
"footer": {
"buttons": {
"aboutClient": {
"title": "About client",
"action": {
"type": "openRestApp",
"actionParams": {
"clientId": 456
}
},
"type": "primary"
}
},
"menu": {
"showPostponeItem": false,
"items": {
"confirm": {
"title": "Confirm request",
"action": {
"type": "restEvent",
"id": "confirm",
"animationType": "loader"
}
},
"decline": {
"title": "Reject request",
"action": {
"type": "restEvent",
"id": "decline",
"animationType": "loader"
}
}
}
}
}
}