Widgets in Messenger: Overview of Embedding Points

This section describes the embedding points for widgets in the Bitrix24 chat interface. Through these points, developers can add a button to the panel above the input field, a separate item in the chat sidebar, an action in the context menu of a specific message, or a section of their own in the messenger navigation menu.

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

Quick navigation: all embedding points

How to Choose an Embedding PointHow to Choose an Embedding Point

The choice of embedding point depends on what the user will be interacting with in the chat interface.

• trigger an action while working with the current chat — IM_TEXTAREA
• show a separate screen with additional information or tools related to the chat — IM_SIDEBAR
• tie an action to a specific chat message — IM_CONTEXT_MENU
• open a separate section of the messenger that is not tied to a chat — IM_NAVIGATION

The mobile application chat is a separate embedding point, IMMOBILE_CONTEXT_MENU: it also receives dialogId, but it lives in the mobile messenger and is not displayed on the web.

How to Get StartedHow to Get Started

1. Choose the embedding point for your scenario: input panel, sidebar, message menu, or navigation menu.
2. Register the handler with the placement.bind method and pass the required code in the PLACEMENT parameter. The method is available to an administrator only and requires the application context: an embedding point 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. Pass the icon name in OPTIONS if the embedding point requires it, and the display restrictions if you need them.
4. Complete the application installation. Until then, the widget is not displayed in the interface.
5. Open a chat and call the widget.
6. Parse PLACEMENT_OPTIONS in the handler to obtain the call context: the identifier of the current chat or message, if the embedding point passes them.
7. If necessary, use the obtained identifiers to call the REST API or open an additional interface.

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 the panel above the input field. For the other embedding points, only the PLACEMENT value and the call context in PLACEMENT_OPTIONS change — their composition is given in the table below.

Array
        (
            [DOMAIN] => xxx.bitrix24.com
            [PROTOCOL] => 1
            [LANG] => de
            [APP_SID] => 99c80eff6378726287350416ee5fef0
            [AUTH_ID] => 6061e72600631fcd00005a4b00000001f0f1076700000000f69dd5fc643d9ce2fdbc1
            [AUTH_EXPIRES] => 3600
            [REFRESH_ID] => 50e00aa340631fcd00005a4b00000001f0f1071111116580a5b83c2de639ef28c12
            [SERVER_ENDPOINT] => https://oauth.bitrix.info/rest/
            [APPLICATION_TOKEN] => ec1b2074a9d3f5c81b6e40d27a95cf38
            [APPLICATION_SCOPE] => im,placement
            [member_id] => da45a03b265ed12127f8a258d793cc5d
            [status] => L
            [PLACEMENT] => IM_TEXTAREA
            [PLACEMENT_OPTIONS] => {"dialogId":"chat2","URI":"\/online\/"}
        )
        

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

{
            "dialogId": "chat2",
            "URI": "/online/"
        }
        

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 value of PLACEMENT_OPTIONS is passed as a JSON string with the context of the call.

The URI key is passed to every embedding point of the web messenger and contains the address of the page the widget is opened from — for the messenger this is /online/. The mobile point IMMOBILE_CONTEXT_MENU does not receive it: there the widget opens as a separate page rather than as a frame inside the interface.

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

The messenger embedding points accept the OPTIONS parameter of the placement.bind method. The set of supported keys differs from point to point.

The key marked with an asterisk is required: without iconName, the placement.bind method returns the ERROR_ARGUMENT error.

The context key restricts the display to a chat type. Possible values: ALL — all chats, USER — personal user chats except chats with bots, CHAT — group chats except LINES and CRM, LINES — open channel chats, CRM — chats created within CRM. Several values are passed separated by ;. The IM_NAVIGATION point does not support this key: a navigation item is not tied to a chat.

The role and extranet keys determine which categories of users have access to the widget. The full description of all keys with their types and default values is on the page of each embedding point.

The table lists the active embedding points. The archive IM_SMILES_SELECTOR accepts context, role, and extranet, but its handler is not called — more details on its page.

Relationships with Other ObjectsRelationships with Other Objects

Chat. The dialogId parameter in PLACEMENT_OPTIONS indicates which chat the handler was invoked for. You can retrieve information about the chat by its identifier using the method im.dialog.get.

User. In a personal conversation, dialogId equals the identifier of the interlocutor, so their data is returned by the user.get method.

Message. The messageId parameter indicates which chat message the handler was invoked for. It arrives only in the IM_CONTEXT_MENU embedding point. Using this identifier, the application works with the message via the methods of the section — for example, updates it with the im.message.update method or deletes it with the im.message.delete method.

Typical ErrorsTypical Errors

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 Embedding PointsOverview of Embedding Points

Scope: placement, im

The placement scope is required to register the handler. To work with a chat from the widget — for example, to get it by the dialogId from the call context — the application also needs the im scope. The exception is the archive IM_SMILES_SELECTOR: it is declared in the global placement scope and requires no second scope.

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
• Chats in Bitrix24: Overview of Methods
• Interactivity in Applications: Overview of Scenarios and Methods