Widgets in Telephony: Overview of Placements

Placements of the section add the application interface to telephony: a tab in the call card during a conversation and a report in the call analytics menu. Both placements need the telephony scope in addition to placement.

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

An external WebRTC client is embedded differently. It has no placement code of its own: the client is loaded into the PAGE_BACKGROUND_WORKER placement, and telephony is connected with the methods of the Telephony: Overview of Methods and Events section. The scenario is described on the WebRTC page.

Quick navigation: all placements

How to Choose a PlacementHow to Choose a Placement

Choose a placement by the task your application solves:

• show client data right during a conversation — CALL_CARD
• add your own report to the built-in call analytics — TELEPHONY_ANALYTICS_MENU

The placements differ in the condition that invokes them. The CALL_CARD handler is invoked when the user opens the tab in the call card, and it receives the conversation context. This placement exists only during a call: without an active call there is no card and nothing to check the widget against.

The TELEPHONY_ANALYTICS_MENU handler is invoked when the user selects an item in the call statistics menu. The placement has no context of its own, but it is available at any moment.

How to Get StartedHow to Get Started

1. Choose a placement for your scenario.
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. Reload the Bitrix24 page. The lists of call card tabs and analytics menu items are built when the page loads.
5. Call the widget. For TELEPHONY_ANALYTICS_MENU, open the /report/telephony/ page and select the application item. For CALL_CARD, you need a call: register an external call with the telephony.externalCall.register method and the SHOW = 1 parameter.
6. Parse PLACEMENT_OPTIONS in the handler — it carries the call context.

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

Both placements pass the same set of standard parameters to the handler. The example is shown for a tab in the call card: for the analytics menu, the PLACEMENT value and the call context in PLACEMENT_OPTIONS change.

Array
        (
            [DOMAIN] => xxx.bitrix24.com
            [PROTOCOL] => 1
            [LANG] => en
            [APP_SID] => 588b8a98e848778a4ffb38fbcf70f2b9
            [AUTH_ID] => 4172bb6600705a0700005a4b00000001f0f107c42ca5bd5f61030c5d9c3e4d60d11b5a
            [AUTH_EXPIRES] => 3600
            [REFRESH_ID] => 31f1e26600705a0700005a4b00000001f0f107b1918506d8a2ed9ecf76e8fdac962471
            [SERVER_ENDPOINT] => https://oauth.bitrix.info/rest/
            [APPLICATION_TOKEN] => 5b2f8c1d7e3a9046b8c5d2f1a7e3b904
            [APPLICATION_SCOPE] => telephony,crm,placement
            [member_id] => da45a03b265edd8787f8a258d793cc5d
            [status] => L
            [PLACEMENT] => CALL_CARD
            [PLACEMENT_OPTIONS] => {"CALL_ID":"externalCall.c3ee67f1a63f6e6117c230ab59cc49ea.1723556778","PHONE_NUMBER":"+4930123456","LINE_NUMBER":"+49 30 000-00-00","LINE_NAME":"+49 30 000-00-00","CRM_ENTITY_TYPE":"COMPANY","CRM_ENTITY_ID":"17","CRM_ACTIVITY_ID":"undefined","CRM_BINDINGS":[{"ENTITY_TYPE":"DEAL","ENTITY_ID":"25"},{"ENTITY_TYPE":"COMPANY","ENTITY_ID":"17"}],"CALL_DIRECTION":"incoming","CALL_STATE":"connected","CALL_LIST_MODE":"false","URI":"\/crm\/company\/details\/17\/"}
        )
        

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

{
            "CALL_ID": "externalCall.c3ee67f1a63f6e6117c230ab59cc49ea.1723556778",
            "PHONE_NUMBER": "+4930123456",
            "LINE_NUMBER": "+49 30 000-00-00",
            "LINE_NAME": "+49 30 000-00-00",
            "CRM_ENTITY_TYPE": "COMPANY",
            "CRM_ENTITY_ID": "17",
            "CRM_ACTIVITY_ID": "undefined",
            "CRM_BINDINGS": [
                { "ENTITY_TYPE": "DEAL", "ENTITY_ID": "25" },
                { "ENTITY_TYPE": "COMPANY", "ENTITY_ID": "17" }
            ],
            "CALL_DIRECTION": "incoming",
            "CALL_STATE": "connected",
            "CALL_LIST_MODE": "false",
            "URI": "/crm/company/details/17/"
        }
        

The values arrive as strings, including CALL_LIST_MODE and CRM_ACTIVITY_ID: compare them with the strings "true", "false", and "undefined", not with a boolean type.

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 both placements on the general terms described above, while own keys exist only for the call card.

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

Neither placement of the section supports the OPTIONS parameter of the placement.bind method: the values passed are not retained, and placement.get returns an empty array for such a registration.

This rule does not apply to the WebRTC scenario. It works not on a telephony placement but on PAGE_BACKGROUND_WORKER, and there OPTIONS[errorHandlerUrl] is required: without it, placement.bind returns the EMPTY_ERROR_HANDLER_URL error.

Relationship With Other ObjectsRelationship With Other Objects

Call. The CALL_ID identifier from the CALL_CARD context is the same one returned by telephony.externalCall.register. The handler uses it to finish the call with the telephony.externalCall.finish method and to attach a call recording.

CRM items. The CRM_ENTITY_TYPE and CRM_ENTITY_ID keys point to the item the call is linked to, and CRM_BINDINGS points to all linked items. The data is returned by the methods of the corresponding CRM sections.

CRM activity. The CRM_ACTIVITY_ID identifier points to the activity created for the call. The activity data is returned by the crm.activity.get method.

Phone lines. The line name in LINE_NAME refers to a line added with the telephony.externalLine.add method.

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, telephony

The third material of the section — WebRTC — is not listed in the table: it has no placement code of its own, and the client runs on top of the PAGE_BACKGROUND_WORKER placement.

Continue Your ExplorationContinue Your Exploration

• Widget Embedding Mechanism
• Placement Catalog
• WebRTC
• 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
• Telephony: Overview of Methods and Events
• Interactivity in Applications: Overview of Scenarios and Methods