Additional Integration Features for CRM_XXX_DETAIL_ACTIVITY, CRM_DYNAMIC_XXX_DETAIL_ACTIVITY

If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the MCP server so that the assistant can utilize the official REST documentation.

Scope: crm

Who can work with the integration: a user with access permission to modify the CRM entity

With additional parameters, you can set the Bitrix24 interface for your menu item in the timeline.

To add the integration, use the method placement.bind. The basic integration capabilities are described in the article Button Above the Timeline of the CRM Entity.

Download an example application using the integration.

OPTIONS Parameter

Name `type`	Description
useBuiltInInterface `boolean`	Use the standard Bitrix24 interface. Default is `N`. If `Y`, the interface is built according to the described structure LayoutDto. The process of working with the interface is described below
newUserNotificationTitle `string`	Notification title for new users
newUserNotificationText `string`	Notification text for new users. Clicking "More" will open a slider with the context `newUserNotification=Y` and a width of `800px`

Registration Example

BX24.callMethod(
          'placement.bind',
          {
            'PLACEMENT': 'CRM_DEAL_DETAIL_ACTIVITY',
            'HANDLER': 'https://your-handler-uri.com',
            'TITLE': 'My Integration',
            'OPTIONS': {
              'useBuiltInInterface': 'Y',
              'newUserNotificationTitle': 'Welcome to the new application',
              'newUserNotificationText': 'E-invoice will help you manage invoices'
            }
          }
        );

Working with the Integration Interface

Interaction occurs through the method BX24.placement.call. The application workflow when using the standard Bitrix24 interface useBuiltInInterface = Y:

Loading the iframe.

The application is loaded in a hidden iframe. The placementOptions include:
- entityTypeId
- entityId
- useBuiltInInterface: Y
Rendering the interface.

Once the application is loaded, it should call setLayout to render the initial state of the integration point.
```
BX24.placement.call('setLayout', LayoutDto, callback);
        
```
Responding to actions.

If the application displays interactive elements in the interface, such as links, it can register a handler bindLayoutEventCallback to handle interactions with those elements.
```
BX24.placement.call('bindLayoutEventCallback', null, callback);
        
```

Managing element states.

You can change the appearance and visibility of a specific interface element through setLayoutItemState.

BX24.placement.call('setLayoutItemState', { id: '...', visible: true/false, properties: {...} }, callback);

Managing buttons.

You can change the appearance of the buttons at the bottom of the interface through setPrimaryButtonState and setSecondaryButtonState.

BX24.placement.call('setPrimaryButtonState', {...}, callback);
        BX24.placement.call('setSecondaryButtonState', {...}, callback);

Completing the process.

When the user's interaction with the integration is complete or if the user clicks "cancel," you need to call finish. The timeline will switch to the default tab.
```
BX24.placement.call('finish');
        
```
Locking the interface.

During long operations, such as saving, the interface can be locked by calling lock. To unlock, call unlock.
```
BX24.placement.call('lock');   // lock
        BX24.placement.call('unlock'); // unlock
        
```
Tracking changes to the entity.

To track changes to the entity fields, for example, to redraw the interface based on the field value, you can register a handler bindEntityUpdateCallback. The callback will be invoked immediately after the fields are saved in the editor.
```
BX24.placement.call('bindEntityUpdateCallback', null, callback);
        
```

Interface Appearance LayoutDto

Name `type`	Description
blocks `ContentBlockDto[]`	Associative array of objects describing content blocks. The keys of the array are the block identifiers. Minimum 1 element
primaryButton `ButtonDto`	Primary button. Usually completes data processing, saves it
secondaryButton `ButtonDto`	Secondary button. Usually cancels the data processing

Clicking on active buttons triggers callbacks:

primaryButton — callback BX24.placement.call('bindPrimaryButtonClickCallback', null, callback),
secondaryButton — callback BX24.placement.call('bindSecondaryButtonClickCallback', null, callback).

ContentBlockDto

Content blocks in the main area can be combined and flexibly assembled into various interfaces.

General structure of a block:

{
          "type": "string",
          "visible": true,
          "properties": {}
        }

type — type of the block, string,
visible — controls the visibility of the block, boolean field. Changing visibility allows for dynamic interfaces. Default = true.
properties — set of properties for a specific block.

Types of Content Blocks

Type	Name
`text`	Text
`link`	Link
`withTitle`	Block with Title
`lineOfBlocks`	Multiple Content Blocks in One Line
`dropdownMenu`	Dropdown Menu
`input`	Text Input Field
`textarea`	Multiline Text Input Field
`select`	Input Field with List Selection
`list`	Unordered List
`section`	Section

Text

A block displaying formatted text.

Required parameters are marked with *

Name `type`	Description
value* `string`	Text
multiline `boolean`	Line break handling. If `true`, `\n` characters will be replaced with `<br>`. Default is `false`
bold `boolean`	Bold text. Default is `false`
size `string`	Text size. Available values: `xs`, `sm`, `md` — default, `lg`, `xl`
color `string`	Text color. Available values: `base_50`, `base_60`, `base_70`, `base_90`, `primary`, `warning`, `danger`, `success`

{
          "type": "text",
          "properties": {
            "value": "Hello!\nWe are starting.",
            "multiline": true,
            "bold": true,
            "size": "lg",
            "color": "base_90"
          }
        }

text

Link

Required parameters are marked with *

Name `type`	Description
text* `string`	Link text, HTML tags are not supported
action* `ActionDto`	Action on clicking the link
size `string`	Text size. Available values: `xs`, `sm`, `md` — default, `lg`, `xl`
bold `boolean`	Bold text. Default is `false`

{
          "type": "link",
          "properties": {
            "text": "Open Deal",
            "action": { "type": "redirect", "uri": "/crm/deal/details/123/" },
            "bold": true
          }
        }

link

Block with Title

The block displays a title and a value. Another content block can be used as the value.

Required parameters are marked with *

Name `type`	Description
title* `string`	Title text
inline `boolean`	Show title and value in one line. Default is `false`
titleWidth `string`	Title width, applied if `inline=true`. Available values: `sm`, `md` — default, `lg`
block* `ContentBlockDto`	Content block that serves as the value. Blocks of types `text`, `link`, `lineOfBlocks` are supported

Example with a text content block:

{
          "type": "withTitle",
          "properties": {
            "title": "Title",
            "block": {
              "type": "text",
              "properties": {
                "value": "Some value"
              }
            }
          }
        }

withTitle1

Example with a link content block:

{
          "type": "withTitle",
          "properties": {
            "title": "Title 2",
            "block": {
              "type": "link",
              "properties": {
                "text": "Open Deal",
                "action": {
                  "type": "redirect",
                  "uri": "/crm/deal/details/123/"
                }
              }
            },
            "inline": true
          }
        }

withTitle2

Multiple Content Blocks in One Line

The block displays multiple content blocks of type text or link in one line. This allows displaying text with different formatting and links in a single line.

Required parameters are marked with *

Name `type`	Description
blocks* `ContentBlockDto[]`	Associative array of content blocks. Blocks of types `text`, `link` are supported

{
          "type": "lineOfBlocks",
          "properties": {
            "blocks": {
              "text": {
                "type": "text",
                "properties": {
                  "value": "Some text"
                }
              },
              "link": {
                "type": "link",
                "properties": {
                  "text": "link",
                  "action": {
                    "type": "redirect",
                    "uri": "/crm/deal/details/123/"
                  }
                }
              },
              "boldText": {
                "type": "text",
                "properties": {
                  "value": "bold text",
                  "bold": true
                }
              }
            }
          }
        }

lineOfBlocks

Dropdown Menu

Required parameters are marked with *

Name `type`	Description
selectedValue `string`	Current selected value. If not filled, the first value from the list will be used
values* `object`	An object where the property names are the code of the value option `vendor`, and the property values are the values that the user will see `supplier`

{
          "type": "dropdownMenu",
          "properties": {
            "selectedValue": "client",
            "values": {
              "": "- not selected -",
              "supplier": "supplier",
              "client": "client"
            }
          }
        }

dropdownMenu

To track value changes, register a callback:

BX24.placement.call('bindValueChangeCallback', null, Callback) to receive changes in any of the blocks
BX24.placement.call('bindValueChangeCallback', 'block id', Callback) to receive changes in the value of only that block.

When the value changes, the callback will receive the id of the dropdown block and its current value: {id: "clientMenu", value: "client"}.

Text Input Field

Required parameters are marked with *

Name `type`	Description
title `string`	Field title
value `string`	Field text
placeholder `string`	Placeholder. Will be shown if the field is not filled
disabled `boolean`	If `true` is passed, the field will be locked for editing. Default is `false`
errorText `string`	Error message. If a non-empty `errorText` is passed, the current value of the field did not pass validation. The user will see the error

{
          "type": "input",
          "properties": {
            "value": "aaa@mail.domain",
            "placeholder": "Enter email",
            "title": "Email",
            "errorText": "Invalid value"
          }
        }

input

To track value changes, register a callback:

BX24.placement.call('bindValueChangeCallback', null, Callback) to receive changes in any of the blocks
BX24.placement.call('bindValueChangeCallback', 'block id', Callback) to receive changes in the value of only that block.

When the value changes, the callback will receive the id of the text input field and its current value: {id: "email", value: "aaa@mail.domain"}.

Multiline Text Input Field

Required parameters are marked with *

Name `type`	Description
title `string`	Field title
value `string`	Field text
placeholder `string`	Placeholder. Will be shown if the field is not filled
disabled `boolean`	If `true` is passed, the field will be locked for editing. Default is `false`
errorText `string`	Error message. If a non-empty `errorText` is passed, the current value of the field did not pass validation. The user will see the error

{
          "type": "textarea",
          "properties": {
            "value": "Go through the gate\nTurn left",
            "title": "Additional Information"
          }
        }

textarea

To track value changes, register a callback:

BX24.placement.call('bindValueChangeCallback', null, Callback) to receive changes in any of the blocks
BX24.placement.call('bindValueChangeCallback', 'block id', Callback) to receive changes in the value of only that block.

When the value changes, the callback will receive the id of the text input field and its current value: {id: "description", value: "Go through the gate\nTurn left"}.

Input Field with List Selection

Required parameters are marked with *

Name `type`	Description
title `string`	Field title
selectedValue `string`	Current selected value. If not filled, the first value from the list will be used
values* `object`	An object where the property names are the code of the value option `nyc`, and the property values are the values that the user will see `New York`
disabled `boolean`	If `true` is passed, the field will be locked for editing. Default is `false`
errorText `string`	Error message. If a non-empty `errorText` is passed, the current value of the field did not pass validation. The user will see the error

{
          "type": "select",
          "properties": {
            "selectedValue": "la",
            "values": {
              "nyc": "New York",
              "la": "Los Angeles",
              "chi": "Chicago"
            },
            "title": "City"
          }
        }

select

To track value changes, register a callback:

BX24.placement.call('bindValueChangeCallback', null, Callback) to receive changes in any of the blocks
BX24.placement.call('bindValueChangeCallback', 'block id', Callback) to receive changes in the value of only that block.

When the value changes, the callback will receive the id of the field and its current value: {id: "city", value: "nyc"}.

Unordered List

Required parameters are marked with *

Name `type`	Description
blocks* `ContentBlockDto[]`	Associative array of content blocks. Blocks of types `text`, `link`, `lineOfBlocks` are supported. Minimum 1 element

{
          "type": "list",
          "properties": {
            "blocks": {
              "li1": {
                "type": "text",
                "properties": {
                  "value": "Import CRM elements without attributes",
                  "color": "base_70"
                }
              },
              "li2": {
                "type": "link",
                "properties": {
                  "text": "Getting Started with CRM",
                  "action": {
                    "type": "layoutEvent",
                    "value": "link2ItemClicked!"
                  }
                }
              },
              "li3": {
                "type": "text",
                "properties": {
                  "value": "How to convert a lead",
                  "bold": true,
                  "color": "base_90"
                }
              }
            }
          }
        }

list

Section

The block displays a grouped set of blocks. An option with an image is possible.

Required parameters are marked with *

Name `type`	Description
blocks* `ContentBlockDto[]`	Associative array of content blocks. Any types of blocks are supported. Minimum 1 element, maximum 20
imageSrc `string`	Full path to the image
imageSize `string`	Image size. Available values: `lg` — default, `md`, `sm`
type `string`	Appearance. Available values: `default` — default, `primary`, `warning`, `danger`, `success`, `withBorder`

Example with multiple blocks and an image:

{
          "type": "section",
          "properties": {
            "type": "withBorder",
            "imageSrc": "https://www.example.com/images/content/products/box/bus.png",
            "blocks": {
              "header": {
                "type": "text",
                "properties": {
                  "value": " Send the client a link to the meeting",
                  "size": "xl",
                  "color": "base_90"
                }
              },
              "notes": {
                "type": "list",
                "properties": {
                  "blocks": {
                    "li1": {
                      "type": "text",
                      "properties": {
                        "value": "The client will choose a convenient slot",
                        "color": "base_70"
                      }
                    },
                    "li2": {
                      "type": "text",
                      "properties": {
                        "value": "The meeting will appear in your tasks",
                        "color": "base_70"
                      }
                    }
                  }
                }
              },
              "howto": {
                "type": "link",
                "properties": {
                  "text": "How does it work?",
                  "action": {
                    "type": "openRestApp",
                    "value": "howto"
                  }
                }
              }
            }
          }
        }

section

Example with one block without an image:

{
        	"type": "section",
        	"properties": {
        		"type": "danger",
        		"blocks": {
        			"errorMessage": {
        				"type": "text",
        				"properties": {
        					"value": "An error occurred. Please try again.",
        					"color": "danger"
        				}
        			}
        		}
        	}
        }

section2

ButtonDto

A button at the bottom of the interface.

Name
type

Description

title*
string

Button text

state
string

State. Available values:

normal — default,
disabled

Actions with Button ActionDto

An action defines the response to a click on a specific element. Available types of actions:

Redirect

Redirecting is possible in two variants:

slider, if it is a relative link to standard Bitrix24 objects that support working in a slider,
regular link redirection in other cases.

Required parameters are marked with *

Name `type`	Description
type* `const`	Action type. Must have the value `redirect`
value* `string`	URI link. For example: `https://example.com` or `/crm/deal/details/1/` for Bitrix24 objects

{
          "type": "redirect",
          "value": "/crm/deal/details/1/"
        }

JS Event

Required parameters are marked with *

Name `type`	Description
type* `const`	Action type. Must have the value `layoutEvent`
value* `string`	Event identifier. For example: `doSomething` or `start_processing`

{
          "type": "layoutEvent",
          "value": "clicked"
        }

Calling the action triggers the handler registered via BX24.placement.call('bindLayoutEventCallback', null, Callback) or BX24.placement.call('bindLayoutEventCallback', 'block id', Callback).

The handler will receive the value of the action and the id of the block that triggered the action: {id: "myLink", value: "clicked"}.

Opening Application Slider

Calling the action will open the slider of the application that registered the integration. The context will be passed to the slider:

entityTypeId is the identifier of the object type to which the deal is linked,
entityId is the identifier of the element.

Required parameters are marked with *

Name `type`	Description
type* `const`	Action type. Must have the value `openRestApp`
value `array`	An array of arbitrary format, the data from which will be passed to the application slider
sliderParams `ActionSliderParamsDto`	Parameters for opening the slider

ActionSliderParamsDto

Name `type`	Description
width `int`	Slider width, px. Cannot be used simultaneously with `leftBoundary`
leftBoundary `int`	Slider full width of the browser window with a left margin, px. Cannot be used simultaneously with `width`
title `string`	Text of the browser window title when opening the slider

{
          "type": "openRestApp",
          "value": {
            "myId": 123,
            "someImportant": "qwerty"
          },
          "sliderParams": {
            "title": "This is the application slider title",
            "width": 700
          }
        }

Examples of LayoutDto

{
        	"blocks": {
        		"section1": {
        			"type": "section",
        			"properties": {
        				"type": "withBorder",
        				"imageSrc": "https://www.example.com/images/content/products/box/bus.png",
        				"blocks": {
        					"header": {
        						"type": "text",
        						"properties": {
        							"value": " Send the client a link to the meeting",
        							"size": "xl",
        							"color": "base_90"
        						}
        					},
        					"notes": {
        						"type": "list",
        						"properties": {
        							"blocks": {
        								"li1": {"type": "text", "properties": {"value": "The client will choose a convenient slot", "color": "base_70"}},
        								"li2": {"type": "text", "properties": {"value": "The meeting will appear in your tasks", "color": "base_70"}}
        							}
        						}
        					},
        					"howto": {
        						"type": "link",
        						"properties": {"text": "How does it work?", "action": {"type": "openRestApp", "value": "howto"}}
        					}
        				}
        			}
        		},
        		"section2": {
        			"type": "section",
        			"properties": {
        				"type": "primary",
        				"blocks": {
        					"sectionText": {
        						"type": "lineOfBlocks",
        						"properties": {"blocks": {"block1": {"type": "text", "properties": {"value": "If you haven't tried the sales generator yet, now is the time to test this tool in action", "color": "base_70"}}, "block2": {"type": "link", "properties": {"text": "Learn more", "action": {"type": "redirect", "value": "/crm/"}}}}}
        					}
        				}
        			}
        		}
        	},
        	"primaryButton": {"title": "Enable"},
        	"secondaryButton": {"title": "Cancel"}
        }

example1

{
        	"blocks": {
        		"errorMessage": {
        			"type": "text",
        			"properties": {"value": "Use all the capabilities of mobile SMS marketing\nSending SMS is easy to set up and use in CRM Bitrix24\nSend messages directly from the deal, lead, client, invoice, or estimate card.", "size": "sm", "color": "base_70", "multiline": true}
        		},
        		"section1": {
        			"type": "section",
        			"properties": {"type": "danger", "blocks": {"errorMessage": {"type": "text", "properties": {"value": "An error occurred. Please try again", "color": "danger"}}}}
        		}
        	},
        	"primaryButton": {"title": "Enable", "state": "disabled"},
        	"secondaryButton": {"title": "Cancel", "state": "disabled"}
        }

example2

{
        	"blocks": {
        		"name": {"type": "input", "properties": {"value": "John", "placeholder": "Enter name", "title": "Name"}},
        		"lastname": {"type": "input", "properties": {"value": "Doe", "placeholder": "", "title": "Last Name"}},
        		"secondname": {"type": "input", "properties": {"value": "", "placeholder": "Enter middle name", "title": "Middle Name"}}
        	},
        	"primaryButton": {"title": "Save"},
        	"secondaryButton": {"title": "Cancel"}
        }

example3

Continue Learning

Button above the timeline of the entity

Dropdown menu item of the top button in the entity

Additional Integration Features for CRM_XXX_DETAIL_ACTIVITY, CRM_DYNAMIC_XXX_DETAIL_ACTIVITY

OPTIONS ParameterOPTIONS Parameter

Registration ExampleRegistration Example

Working with the Integration InterfaceWorking with the Integration Interface

Interface Appearance LayoutDtoInterface Appearance LayoutDto

ContentBlockDtoContentBlockDto

Types of Content BlocksTypes of Content Blocks

TextText

LinkLink

Block with TitleBlock with Title

Multiple Content Blocks in One LineMultiple Content Blocks in One Line

Dropdown MenuDropdown Menu

Text Input FieldText Input Field

Multiline Text Input FieldMultiline Text Input Field

Input Field with List SelectionInput Field with List Selection

Unordered ListUnordered List

SectionSection

ButtonDtoButtonDto

Actions with Button ActionDtoActions with Button ActionDto

RedirectRedirect

JS EventJS Event

Opening Application SliderOpening Application Slider

ActionSliderParamsDtoActionSliderParamsDto

Examples of LayoutDtoExamples of LayoutDto

Continue LearningContinue Learning

OPTIONS Parameter

Registration Example

Working with the Integration Interface

Interface Appearance LayoutDto

ContentBlockDto

Types of Content Blocks

Text

Link

Block with Title

Multiple Content Blocks in One Line

Dropdown Menu

Text Input Field

Multiline Text Input Field

Input Field with List Selection

Unordered List

Section

ButtonDto

Actions with Button ActionDto

Redirect

JS Event

Opening Application Slider

ActionSliderParamsDto

Examples of LayoutDto

Continue Learning