Widgets in CRM: Overview of Placements

Placements add the application interface inside CRM: its own tab in an object card, an item in the list context menu, a button above the timeline, an item in the automation rules designer, or a report in CRM Analytics.

Placements fall into two groups. The first group works with a specific object type, and the placement code contains the name of that type: CRM_DEAL_DETAIL_TAB, CRM_LEAD_LIST_MENU. The second group belongs to the CRM section as a whole, and the code carries no object name: CRM_ANALYTICS_MENU, CRM_ANALYTICS_TOOLBAR, CRM_DETAIL_SEARCH.

Pipelines stand apart: for deals the code carries no object name — CRM_FUNNELS_TOOLBAR, while for new invoices and custom object types it does — CRM_SMART_INVOICE_FUNNELS_TOOLBAR and CRM_DYNAMIC_XXX_FUNNELS_TOOLBAR.

To register a widget, use the placement.bind method and pass the required code in the PLACEMENT parameter.

Quick navigation: all placements

How to Choose a PlacementHow to Choose a Placement

Choose a placement by the task your application solves:

• add an action to an element in a list — CRM_XXX_LIST_MENU
• add an action to the whole list rather than to a single element — CRM_XXX_LIST_TOOLBAR
• add a separate screen with application data to a card — CRM_XXX_DETAIL_TAB
• add a button next to the activities and comments of a card — CRM_XXX_DETAIL_ACTIVITY, and to build its interface with Bitrix24 tools — additional placement features
• add an action for the whole card, next to tasks and documents — CRM_XXX_DETAIL_TOOLBAR
• add an action to an individual activity record in the timeline — CRM_XXX_ACTIVITY_TIMELINE_MENU
• generate a document for an object — CRM_XXX_DOCUMENTGENERATOR_BUTTON
• extend automation — CRM_XXX_ROBOT_DESIGNER_TOOLBAR
• extend pipelines and tunnels — CRM_FUNNELS_TOOLBAR and the codes of the other object types
• show your own report — CRM_ANALYTICS_MENU, and to add an action for the analytics section — CRM_ANALYTICS_TOOLBAR
• show a report next to the ready-made BI analytics reports — BI_ANALYTICS_MENU
• search for a client in an external source and fill it into the form — CRM_DETAIL_SEARCH
• fill in company data from an external source — details autofill

How to Get StartedHow to Get Started

1. Choose a placement for your scenario and assemble the placement code: substitute LEAD, DEAL, CONTACT, COMPANY, QUOTE, SMART_INVOICE, ORDER, or ACTIVITY for XXX. For custom object types, substitute DYNAMIC_ and the numeric type identifier — CRM_DYNAMIC_183_DETAIL_TAB. The set of supported types differs from placement to placement: the exact list of codes is given on each placement page, the assembly rules are in the placement catalog, and the places actually available to the application are returned by the placement.list method.
2. Register the handler with the placement.bind method and pass the code in the PLACEMENT parameter. The method is available to an administrator only and requires the application context: a placement cannot be bound with a webhook. On successful registration, the method returns result: true — the response breakdown and the error codes are on its page.
3. Complete the application installation. Until then, the widget is not displayed in the interface.
4. Open the place in the interface and call the widget. Where exactly the item is located is described on each placement page in the "Where to Find It in the Interface" section.
5. Parse PLACEMENT_OPTIONS in the handler — it carries the call context: the identifier of the object or activity, or the address of the page the widget was opened from.

For three placements of the section the work does not end there. CRM_DETAIL_SEARCH and the two details autofill placements exchange data with the card in both directions: the handler returns the found options with an interface command and subscribes to the user's choice. The exchange order is described on their pages.

What the Handler ReceivesWhat the Handler Receives

Data is sent in a POST request: some parameters come in the handler URL query string, the rest in the request body

Placements of the section pass the same set of standard parameters to the handler. The exception is BI_ANALYTICS_MENU: this placement opens the handler address with a regular GET request and passes nothing to it.

The example is shown for a tab in a deal card. For the other placements, only the PLACEMENT value and the call context in PLACEMENT_OPTIONS change.

Array
        (
            [DOMAIN] => xxx.bitrix24.com
            [PROTOCOL] => 1
            [LANG] => en
            [APP_SID] => 5552d735db7b7b4d5c16dd9c272bfe7d
            [AUTH_ID] => 9d4c7166007e9c94001e30ba00000001f0f107e28b5a4310c7f6d9b3025ea814
            [AUTH_EXPIRES] => 3600
            [REFRESH_ID] => 8c3b9966007e9c94001e30ba00000001f0f107f19c6b3e04d182ac5b73f9052d
            [SERVER_ENDPOINT] => https://oauth.bitrix.info/rest/
            [APPLICATION_TOKEN] => ec1b2074a9d3f5c81b6e40d27a95cf38
            [APPLICATION_SCOPE] => crm,placement
            [member_id] => d897063e1ce7c5eb9f04b9751eef5915
            [status] => L
            [PLACEMENT] => CRM_DEAL_DETAIL_TAB
            [PLACEMENT_OPTIONS] => {"ID":"8061","URI":"\/crm\/deal\/details\/8061\/?any=details%2F8061%2F&IFRAME=Y&IFRAME_TYPE=SIDE_SLIDER"}
        )
        

After parsing, the PLACEMENT_OPTIONS string from this example looks like this:

{
            "ID": "8061",
            "URI": "/crm/deal/details/8061/?any=details%2F8061%2F&IFRAME=Y&IFRAME_TYPE=SIDE_SLIDER"
        }
        

Required parameters are marked with *

Parameters in the Handler URL Query String

Parameters in the POST Request Body

Bitrix24 adds a URI key to PLACEMENT_OPTIONS — the path with the query string of the page from which the widget was opened. It arrives for any placement, along with the keys of that placement itself. The key is absent if the browser did not send the Referer header or if the widget was opened from a page on a different domain.

How to Parse the Call Context

PLACEMENT_OPTIONS arrives as a JSON string, not as an array: parse it on the handler side before use. The set of keys is specific to each placement and is described in the PLACEMENT_OPTIONS section of this page.

$placement = $_POST['PLACEMENT'] ?? '';
        $options = json_decode($_POST['PLACEMENT_OPTIONS'] ?? '{}', true);
        

options = json.loads(request.form.get("PLACEMENT_OPTIONS", "{}") or "{}")
        

In B24JsSDK, there is no need to parse the string: the $b24.placement.options property returns a ready object, and $b24.placement.placement returns the placement code.

What the Handler Must Return

The handler responds with a regular HTML page — Bitrix24 displays it in a frame in place of the widget. The page must allow embedding: if the application server sends the X-Frame-Options or Content-Security-Policy headers that prohibit framing, an empty area remains in place of the widget. How to fix it is described in the article Site Does Not Allow Connection.

PLACEMENT_OPTIONSPLACEMENT_OPTIONS

The PLACEMENT_OPTIONS value is passed as a JSON string with the call context. The universal URI key arrives for every placement, while the set of the remaining keys is specific to each placement.

OPTIONS When Registering via placement.bindOPTIONS When Registering via placement.bind

Only three placements of the section support the OPTIONS parameter of the placement.bind method.

The other placements of the section do not support OPTIONS: Bitrix24 accepts the passed values without an error but does not retain them, and the placement.get method returns an empty array for such a registration.

Connection with Other ObjectsConnection with Other Objects

CRM object. The identifier from PLACEMENT_OPTIONS indicates which element the handler was called for. Object data can be retrieved with the crm.item.get method by passing the entityTypeId of the required object type, or with the method of its own section: crm.deal.get, crm.lead.get, crm.contact.get, crm.company.get, crm.quote.get.

Activity. The ASSOCIATED_ENTITY_ID key indicates which activity record the widget is opened on. Activity data is returned by the crm.activity.get method.

Custom object type. The type identifier does not arrive as a separate key. It can be taken from the PLACEMENT parameter value: for the CRM_DYNAMIC_183_DETAIL_TAB code, the type identifier is 183.

Call page. The universal URI key contains the path of the Bitrix24 page the widget was opened from. The handler uses it to restore the scenario when the placement has no keys of its own. The exception is CRM_BANK_DETAIL_AUTOCOMPLETE: the widget is opened from the details form, so URI carries the address of the component document, while the client identifier comes in its eid and external_context_id parameters.

Common MistakesCommon Mistakes

The error arrives in the response body — the code in the error field, the text in error_description:

{
            "error": "WRONG_AUTH_TYPE",
            "error_description": "Current authorization type is denied for this method Application context required"
        }
        

Other registration error codes are listed in the "Possible Error Codes" section of the placement.bind page.

Overview of PlacementsOverview of Placements

Scope: placement, crm

The exception is BI_ANALYTICS_MENU: the placement is declared in the global placement scope and requires no separate CRM access.

The interface of the button above the timeline can be built with Bitrix24 tools instead of your own markup. This is an addition to the CRM_XXX_DETAIL_ACTIVITY placement, not a separate placement: it has no code of its own and cannot be registered with the placement.bind method. How to enable such an interface is described in the article Additional features of CRM_XXX_DETAIL_ACTIVITY.

Continue LearningContinue Learning

• Widget Embedding Mechanism
• Placement Catalog
• Register a Widget Handler placement.bind
• Get Handlers Registered by the Application placement.get
• Get Placements Available to the Application placement.list
• Delete a Widget Handler placement.unbind
• Interaction with UI: Overview of Methods
• Methods of BX24 SDK for Widgets
• CRM: Overview of Sections and Methods
• How to embed widgets in CRM
• Interactivity in Applications: Overview of Scenarios and Methods