Invisible Widget on Every Page PAGE_BACKGROUND_WORKER

Scope: placement

You can add an "invisible" widget that will be displayed on all pages of Bitrix24. This widget allows you to implement a scenario with an external WebRTC client in telephony integrations, but it is not the only possible use case.

For example, using the interactive interaction mechanism between backend and frontend applications, you can send a "signal" to the PAGE_BACKGROUND_WORKER widget, and upon receiving the "signal," open the application slider using the openApplication method.

The widget embedding code is specified in the PLACEMENT parameter of the placement.bind method.

The embedding will not be displayed in the interface until the application installation is complete. Check the application installation

Unlike other types of widgets, for PAGE_BACKGROUND_WORKER, the application can register only one handler.

Since this widget loads on all pages, a handler that takes longer than 3-5 seconds to load may cause delays in rendering the Bitrix24 user interface. If this occurs more than 10 times within a day on the same Bitrix24, the handler will be automatically disabled.

Bitrix24 will inform the application about the handler's disablement. To do this, in the placement.bind method, you need to specify the URL in the OPTIONS[errorHandlerUrl] parameter. Bitrix24 will call this URL in case the PAGE_BACKGROUND_WORKER widget handler is disabled.

cURL (Webhook)

cURL (OAuth)

PHP

BX24.js

PHP CRest

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"PLACEMENT":"PAGE_BACKGROUND_WORKER","HANDLER":"http://myapp.com/handler/?type=1","OPTIONS":{"errorHandlerUrl":"http://myapp.com/error/"}}' \
        https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/placement.bind

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"PLACEMENT":"PAGE_BACKGROUND_WORKER","HANDLER":"http://myapp.com/handler/?type=1","OPTIONS":{"errorHandlerUrl":"http://myapp.com/error/"},"auth":"**put_access_token_here**"}' \
        https://**put_your_bitrix24_address**/rest/placement.bind

try
        {
        	const response = await $b24.callMethod(
        		"placement.bind",
        		{ 
        			PLACEMENT: "PAGE_BACKGROUND_WORKER",
        			HANDLER: "http://myapp.com/handler/?type=1",
        			OPTIONS: {
        				errorHandlerUrl: "http://myapp.com/error/"
        			}
        		}
        	);
        	
        	const result = response.getData().result;
        	if(result.error())
        		console.error(result.error());
        	else
        		console.info(result);
        }
        catch(error)
        {
        	console.error('Error:', error);
        }

try {
            $response = $b24Service
                ->core
                ->call(
                    'placement.bind',
                    [
                        'PLACEMENT' => 'PAGE_BACKGROUND_WORKER',
                        'HANDLER'   => 'http://myapp.com/handler/?type=1',
                        'OPTIONS'   => [
                            'errorHandlerUrl' => 'http://myapp.com/error/'
                        ]
                    ]
                );
        
            $result = $response
                ->getResponseData()
                ->getResult();
        
            if ($result->error()) {
                error_log($result->error());
            } else {
                echo 'Success: ' . print_r($result->data(), true);
            }
        
        } catch (Throwable $e) {
            error_log($e->getMessage());
            echo 'Error binding placement: ' . $e->getMessage();
        }

BX24.callMethod(
            "placement.bind",
            { 
                PLACEMENT: "PAGE_BACKGROUND_WORKER",
                HANDLER: "http://myapp.com/handler/?type=1",
                OPTIONS: {
                    errorHandlerUrl: "http://myapp.com/error/"
                }
            },
            function(result)
            {
                if(result.error())
                    console.error(result.error());
                else
                    console.info(result.data());
            }
        );

require_once('crest.php');
        
        $result = CRest::call(
            'placement.bind',
            [
                'PLACEMENT' => 'PAGE_BACKGROUND_WORKER',
                'HANDLER' => 'http://myapp.com/handler/?type=1',
                'OPTIONS' => [
                    'errorHandlerUrl' => 'http://myapp.com/error/'
                ]
            ]
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';

What the Handler Receives

Data is sent as a POST request


        Array
        (
            [handler] => 1
            [DOMAIN] => restapi.bitrix24.com
            [PROTOCOL] => 1
            [LANG] => de
            [APP_SID] => 588b8a98e848778a4ffb38fbcf70f2b9
            [AUTH_ID] => 4172bb6600705a0700005a4b00000001f0f107c42ca5bd5f61030c5d9c3e4d60d11b5a
            [AUTH_EXPIRES] => 3600
            [REFRESH_ID] => 31f1e26600705a0700005a4b00000001f0f107b1918506d8a2ed9ecf76e8fdac962471
            [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 *

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`	String identifier of the application that registered the widget handler
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
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
PLACEMENT* `string`	Code for the widget embedding location. 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 widget embedding location 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 entity 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 widget embedding location and object the widget handler was invoked.

PLACEMENT_OPTIONS

The value of PLACEMENT_OPTIONS is a JSON string containing an array of one or more keys.

Required parameters are marked with *

Parameter	Description
ID* `string`	Always equals `PAGE_BACKGROUND_WORKER` and is used for internal purposes
URI* `string`	URL-encoded address of the current page where the widget was opened.