Widget Embedding Mechanism

Scope: placement, depends on the placement

A widget is an application interface embedded into a Bitrix24 page. The user opens a tab in a deal card, selects a menu item, or clicks a button in a chat and sees the application in a frame without leaving the working interface. Along with the frame, Bitrix24 passes the user authorization and the call context to the application — for example, the identifier of the deal whose card the widget was opened from.

The location where the interface is embedded is called a placement and is identified by a code: CRM_DEAL_DETAIL_TAB, LEFT_MENU, IM_TEXTAREA. The handler for a placement is registered by the application with the placement.bind method. There is a single exception — the SETTING_CONNECTOR placement, whose handler is connected by the imconnector.register method.

This page describes the mechanism: the registration procedure, permissions, handler data, and common mistakes.

Quick navigation: all placements

How an Application Appears in the Bitrix24 InterfaceHow an Application Appears in the Bitrix24 Interface

An application can show its interface to the user in different ways. Widgets are one of them.

Application Page of Its OwnApplication Page of Its Own

An application item in the main menu is not a widget. No handler is registered for it: the item opens the main application URL.

In a local application, specify the menu item name.

In a mass-market solution, enable the Add your page and item to the main menu option. The item name is specified in the application description for the required language, in the Application Name in Menu field.

A main menu item can also open a registered handler with a call context. To do this, use the LEFT_MENU placement.

How a Widget WorksHow a Widget Works

1. The application registers a handler with the placement.bind method: it passes the placement code in the PLACEMENT parameter and the URL of its handler in the HANDLER parameter.
2. The user calls the widget: opens a tab, selects a menu item, or clicks a button.
3. Bitrix24 sends a POST request to the handler URL and passes the user authorization and the call context in it.
4. The handler responds with a page that is allowed to open in a frame, and Bitrix24 displays it in place of the widget.
5. From the frame, the application calls the REST API on behalf of the user and controls the Bitrix24 interface with JavaScript methods.

What Permissions Are RequiredWhat Permissions Are Required

Permissions consist of two layers.

The placement scope is always required — without it, the application cannot call placement.bind.

The tool scope is required to work with the data of that tool from the widget: to retrieve a deal by the identifier from the call context, a chat by dialogId, or a task by its identifier. For some placements, the same scope is also required for the registration itself: CRM placements are declared in the crm scope, task placements in task. For messenger placements, on the contrary, the placement scope alone is enough for registration, while im is needed to work with the chat.

The required set is specified in the header of each placement page — rely on it rather than on the product section.

Application permissions are not the only condition. Only the employees who have access to the application see the widget: Bitrix24 checks the access every time the widget is displayed.

The placement.bind, placement.unbind, and placement.get methods are available only to the Bitrix24 administrator, and placement.list to any user. All of them work in the application context: a call made with a webhook returns the WRONG_AUTH_TYPE error.

How to Get StartedHow to Get Started

1. Choose a placement for your scenario in the list of placements. Its code is required in the PLACEMENT parameter.
2. Specify the placement scope in the application settings, and the tool scope as well if the placement requires it. The set is specified in the header of the placement page.
3. Register the handler with the placement.bind method. This is usually done during the application installation.
4. Complete the application installation and open the placement in the interface.
5. Parse the POST request data in the handler: the user authorization and the call context from PLACEMENT_OPTIONS.

How to Use Examples in Documentation

curl -X POST \
          -H "Content-Type: application/json" \
          -H "Accept: application/json" \
          -d '{
            "PLACEMENT": "CRM_DEAL_DETAIL_TAB",
            "HANDLER": "https://your-domain.com/widgets/deal-tab-handler.php",
            "TITLE": "Deal supplies",
            "auth": "**put_access_token_here**"
          }' \
          https://**put_your_bitrix24_address**/rest/placement.bind
        

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

The example is shown for a tab in a deal card. Other placements receive the same set of data: only the PLACEMENT value and the call context in PLACEMENT_OPTIONS change. The exception is BI_ANALYTICS_MENU: this placement opens the handler URL with a regular GET request and passes nothing to it.

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"}
        )
        

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.

The handler URL is reachable from an external network, so verify that the request came from Bitrix24: compare APPLICATION_TOKEN with the value the application received and retained during the installation. How an application retains the token is described in the Security in Handlers article. Do not write the AUTH_ID and REFRESH_ID tokens to logs and do not pass them to third parties.

PLACEMENT_OPTIONSPLACEMENT_OPTIONS

The call context comes as a JSON string in the PLACEMENT_OPTIONS parameter. The set of keys depends on the placement:

• in a CRM card — the object identifier
• in a chat — the dialog identifier, and for the message menu placement also the message identifier
• for universal placements — the placement code or the arbitrary parameters the application passed in the link itself
• for placements without a context of their own — only the universal URI key

The full set of keys is described on the page of each placement.

A complete handler — receiving the POST request, parsing PLACEMENT_OPTIONS, and responding with a page for the frame — is shown step by step in the How to Embed a Widget into a CRM Item Tab tutorial. The code in it suits any placement: only the code in PLACEMENT and the call context keys change.

What You Can Do from a WidgetWhat You Can Do from a Widget

A widget runs in a frame but is not isolated from Bitrix24:

• call the REST API on behalf of the user with the AUTH_ID token from the handler data
• open standard Bitrix24 pages and interfaces of your own in a slider — BX24 SDK methods for widgets
• control the CRM card and the call card from your interface — UI interaction from widgets
• style the interface to match Bitrix24 — Bitrix24 UI Kit

JavaScript methods work only after the library is connected to the handler page. How to connect it is described in the BX24.js: Library Overview overview.

The widget interface is limited by the frame size: a popup wider than this area is cut off, and scrollbars appear at the edges. Open settings forms, object detail cards, and creation forms in a separate slider with BX24.openApplication — arbitrary application parameters can be passed to it.

Handler LifecycleHandler Lifecycle

Handlers are removed together with the application, there is no need to remove the registration separately. What else Bitrix24 clears when an application is removed is described in the Application Removal article.

Common MistakesCommon Mistakes

Continue LearningContinue Learning

• Placement Catalog
• Item in the Main Menu LEFT_MENU
• Register a Widget Handler placement.bind
• Get Placements Available to the Application placement.list
• Get Handlers Registered by the Application placement.get
• Delete a Widget Handler placement.unbind
• Methods of BX24 SDK for Widgets
• Interaction with UI: Overview of Methods
• Bitrix24 UI Kit: Overview
• How to embed widgets in CRM