Universal Widgets: Overview of Placements

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.

Universal widgets are not tied to a specific Bitrix24 tool: they have neither their own button nor their own menu. The handler is called either through a link that the application itself placed in the content, or on every Bitrix24 page without any user action. Both placements require the placement scope.

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 Placement

The placements differ in who launches the handler.

Placement	Who Launches It	When to Use
REST_APP_URI	The user — by following the application link	The application places a link in a message, comment, task, or other content, and the handler opens in a slider over the current page. Custom parameters can be passed in the link
PAGE_BACKGROUND_WORKER	Bitrix24 — on every page load	The application needs code that runs on all Bitrix24 pages: receiving signals from its own backend, telephony integration, opening the application interface automatically. The placement has no visible element

How to Get Started

Choose the placement by who launches the handler: the user through a link or Bitrix24 on every page
Register the handler with the placement.bind method and pass the placement code in PLACEMENT. For PAGE_BACKGROUND_WORKER, OPTIONS[errorHandlerUrl] is mandatory
Complete the application installation: until then the handler is not called
Call the placement: follow the link /marketplace/view/#APP_CODE#/ or open any Bitrix24 page
Parse PLACEMENT_OPTIONS to get the launch context
If the widget has to open the application interface, use the JavaScript methods for widgets

Both placements are registered in a single copy: a repeated placement.bind for the same application returns the error ERROR_PLACEMENT_MAX_COUNT.

What 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

REST_APP_URI

PAGE_BACKGROUND_WORKER

Array
        (
            [DOMAIN] => xxx.bitrix24.com
            [PROTOCOL] => 1
            [LANG] => en
            [APP_SID] => 9ecab44f06b9efb6c37d7b02180422b2
            [AUTH_ID] => 913374660070f28d001e30ba00000001f0f1073c8a5e2b7d94f16c0a3e58d271
            [AUTH_EXPIRES] => 3600
            [REFRESH_ID] => 81b29b660070f28d001e30ba00000001f0f107e4d1a9b3f508c72e6d95af3b04
            [SERVER_ENDPOINT] => https://oauth.bitrix.info/rest/
            [APPLICATION_TOKEN] => ec1b2074a9d3f5c81b6e40d27a95cf38
            [APPLICATION_SCOPE] => placement
            [member_id] => da45a03b265edd8787f8a258d793cc5d
            [status] => L
            [PLACEMENT] => REST_APP_URI
            [PLACEMENT_OPTIONS] => {"test":"y","docId":"42","URI":"\/company\/personal\/user\/1\/blog\/"}
        )

Array
        (
            [DOMAIN] => xxx.bitrix24.com
            [PROTOCOL] => 1
            [LANG] => en
            [APP_SID] => 588b8a98e848778a4ffb38fbcf70f2b9
            [AUTH_ID] => 4172bb660070f28d001e30ba00000001f0f107c42ca5bd5f61030c5d9c3e4d60
            [AUTH_EXPIRES] => 3600
            [REFRESH_ID] => 31f1e2660070f28d001e30ba00000001f0f107b1918506d8a2ed9ecf76e8fdac
            [SERVER_ENDPOINT] => https://oauth.bitrix.info/rest/
            [APPLICATION_TOKEN] => ec1b2074a9d3f5c81b6e40d27a95cf38
            [APPLICATION_SCOPE] => placement
            [member_id] => da45a03b265edd8787f8a258d793cc5d
            [status] => L
            [PLACEMENT] => PAGE_BACKGROUND_WORKER
            [PLACEMENT_OPTIONS] => {"ID":"PAGE_BACKGROUND_WORKER","URI":"\/company\/personal\/user\/1\/blog\/"}
        )

Required parameters are marked with *

Parameters in the Handler URL Query String

Parameter `type`	Description
DOMAIN* `string`	The Bitrix24 address where the widget handler was invoked
PROTOCOL* `string`	Secure or non-secure HTTP protocol: `0` - HTTP `1` - HTTPS
LANG* `string`	The user interface language of Bitrix24 that invoked the widget. You can localize the interface language in your widget based on this value
APP_SID* `string`	Application session identifier. Bitrix24 generates a new one each time the widget is rendered and uses it to link the js library with the application environment

Parameters in the POST Request Body

Parameter `type`	Description
AUTH_ID `string`	Authorization token OAuth 2 issued for the user who invoked the widget. Can be used for REST API calls on behalf of this user
AUTH_EXPIRES `integer`	Time in seconds after which the authorization token will become invalid
REFRESH_ID `string`	Refresh token OAuth 2 issued for the user who invoked the widget. Can be used to refresh the authorization token on behalf of this user
SERVER_ENDPOINT* `string`	Address of the Bitrix24 authorization server needed to refresh OAuth 2 tokens
APPLICATION_TOKEN* `string`	Application token. The same value is passed in the `application_token` parameter when event handlers are invoked. The widget handler can use it to verify that the request came from Bitrix24
APPLICATION_SCOPE* `string`	List of scopes granted to the application, separated by commas. Shows which REST API methods are available with the authorization token received
member_id* `string`	Unique string identifier of Bitrix24 where the widget handler was invoked.
status `string`	Type of application that registered the handler for this widget. Accepts values: `L` - local application `F` - free mass-market application `D` - demo version of a mass-market application `T` - trial version of a mass-market application, time-limited `P` - paid mass-market application
PLACEMENT* `string`	The placement code. You can use the same handler URL for all your widgets. The value that Bitrix24 will report in the `PLACEMENT` parameter will help determine from which specific placement your handler was invoked in each case
PLACEMENT_OPTIONS `string`	Additional data in the form of a JSON string that defines the context of the widget execution. For example, this could be an array containing the numeric identifier of the CRM object in the detail form where the widget handler was invoked, etc. The `PLACEMENT_OPTIONS` parameter, along with the `PLACEMENT` parameter, allows you to accurately determine for which specific placement and object the widget handler was invoked

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_OPTIONS

The value of PLACEMENT_OPTIONS is passed as a JSON string with the call context.

Placement	Keys	What They Contain
REST_APP_URI	Keys from the link `params`, `URI`	The parameters the application set in the link itself and the address of the page the user came from
PAGE_BACKGROUND_WORKER	`ID`, `URI`	The placement code and the address of the page where the handler loaded

The URI key is universal: it is passed to any placement and carries the path with the query string of the Bitrix24 page the widget is opened from.

Relationship With Other Objects

Application interface. Both placements open the application in its own frame, so the JavaScript methods for widgets work further: openApplication opens the application slider, closeApplication closes it.

Signal exchange. PAGE_BACKGROUND_WORKER is the only placement that works without any user action, so the application backend passes a signal to the browser through it using the interactive interaction mechanism.

Call card. Telephony applications control the call card from the background handler. The methods and events are described in the Manage the Call Card of a WebRTC Client: Overview of Commands and Events section.

Common Mistakes

Mistake	Solution
`placement.bind` returns `EMPTY_ERROR_HANDLER_URL`	The `PAGE_BACKGROUND_WORKER` placement requires an address for deactivation messages. Pass `OPTIONS[errorHandlerUrl]`
`placement.bind` returns `ERROR_PLACEMENT_MAX_COUNT`	A handler for this placement is already registered. Remove the old registration with the placement.unbind method
The `/marketplace/view/#APP_CODE#/` link opens an empty slider	Check that the application installation is complete and that the link contains the application code, not the handler registration identifier
The background handler stopped being called	The registration is deleted if the handler took longer than five seconds to load more than ten times a day. Bitrix24 reports this to the address from `errorHandlerUrl`

Overview of Placements

Scope: placement

Placement	When to Use
REST_APP_URI	Open the application in a slider through a link in a message, comment, task, or other content
PAGE_BACKGROUND_WORKER	Run a background scenario on all Bitrix24 pages without a visible interface element

Continue Learning

Was the article helpful?

Item in the Main Menu

Opening the Application via a Link

Universal Widgets: Overview of Placements

How to Choose a PlacementHow to Choose a Placement

How to Get StartedHow to Get Started

What the Handler ReceivesWhat the Handler Receives

PLACEMENT_OPTIONSPLACEMENT_OPTIONS

Relationship With Other ObjectsRelationship With Other Objects

Common MistakesCommon Mistakes

Overview of PlacementsOverview of Placements

Continue LearningContinue Learning