This method installs the embedding location handler.

The handler is limited by the following conditions:

  • request is executed under administrator authorization,
  • handler is located at the same domain, as the registered redirect_uri of the application
  • . To install the embedding location handler in the CRM interface, provide access to the CRM.
  • each embedding location is associated with the access permission (scope). To set the embedding location in the CRM UI you need to grant corresponding permissions to CRM.

After installing applications with UI, you need to execute the method BX24.installFinish after query. Otherwise buttons won't be displayed in embedding locations. Placements are displayed immediately for GUI-less server local applications.

Starting from rest 21.200.0 method supports multiple languages.


Parameter Description
PLACEMENT Required embedding location ID. Required.
HANDLER URL for embedding location handler. Required.
LANG_ALL Array with parameters for each language. Array keys:
  • TITLE - handler title, will be displayed immediately at the embedding location. Optional, by default - app name
  • DESCRIPTION - handler description, can be displayed at the embedding location. Optional.
  • GROUP_NAME - group name, allows to group handlers at the embedding location. Optional.
USER_ID Receives an integer and allows to show the embedding for specified user (one user only!). With ''0'' or without this field - embedding is registered for all users.

Attention! This field is not supported by all embedding locations Presently, this field is supported by PAGE_BACKGROUND_WORKER. . Upon attempting to register an embedding location without this feature enabled, you'll get an error ERROR_PLACEMENT_USER_MODE: User mode is not available. Please see registration availability in embedding locations description.

Also, HANDLER for an embedding location must be unique for the application, in addition to various USER_ID.


HTTP/1.1 200 OK

    "result": true

Example with several languages supported:

      'HANDLER' => '',
      'LANG_ALL' => [
         'en' => [
            'TITLE' => 'title',
            'DESCRIPTION' => 'description',
            'GROUP_NAME' => 'group',
         'de' => [
            'TITLE' => 'title',
            'DESCRIPTION' => 'description',
            'GROUP_NAME' => 'group',

© «Bitrix24», 2001-2024