Website widget: advanced settings

Author: Emily Walker

Last update: April 22, 2026.

If you already use the on your website and need to identify guest sessions in Live Chat, you can use the approach below.

For unauthorized users, use Connect Bitrix24 Live Chat to your site.

For authorized users, you can use a better option that does not ask them to enter their contact details again.

2. Manual setup

If you use a third-party system, such as your billing system, add JavaScript to the page where the widget loads.

The basic code for flexible widget setup looks like this:

<script type="text/javascript"> window.addEventListener('onBitrixLiveChat', function(event) {
  var widget = event.detail.widget;

  // 1. Set external user authorization
  ...

  // 2. Pass additional data
  ...

  // 3. Handle events
  ...
});
</script>

Widget methods:

widget.open() — Opens the widget
widget.close() — Closes the widget
widget.subscribe() — Subscribes to an event
widget.setUserRegisterData() — Sets external user authorization
widget.setCustomData() — Passes additional data
widget.setOption() — Sets additional options

1. Set external user authorization

<script type="text/javascript"> window.addEventListener('onBitrixLiveChat', function(event) {
  var widget = event.detail.widget;

  // Set external user authorization
  widget.setUserRegisterData({
    'hash': '12b42ebcec7e3c26a313272c26efddbd',
    'name': 'Victor',
    'lastName': 'Ivanov',
    'avatar': 'http://files.shelenkov.com/images/avatar-ivanov.jpg',
    'email': 'victor@ivanov.ru',
    'gender': 'M',
    'position': 'Honored User'
  });
});
</script>

Note:

hash is a special field that replaces authorization. It must be unique within your Bitrix24 account to avoid conflicts, and must use MD5 format. Example: md5(USER_ID + _site_address_ + _secret_code_)
This value must identify the user and be impossible to guess from the outside.

2. Pass additional data

You can pass additional data by using special blocks:

<script type="text/javascript"> window.addEventListener('onBitrixLiveChat', function(event) {
  var widget = event.detail.widget;

  // Pass additional data at the start of a new session, extended format
  widget.setCustomData([
    {
      "USER": {
        "NAME": "Victor Ivanov",
        "AVATAR": "http://files.shelenkov.com/images/avatar-ivanov.jpg"
      }
    },
    {
      "GRID": [
        {
          "NAME": "Email",
          "VALUE": "victor@ivanov.ru",
          "DISPLAY": "LINE"
        },
        {
          "NAME": "Client code",
          "VALUE": "12234",
          "COLOR": "#ff0000",
          "DISPLAY": "LINE"
        },
        {
          "NAME": "Site",
          "VALUE": location.hostname,
          "DISPLAY": "LINE"
        },
        {
          "NAME": "Page",
          "VALUE": "[url=" + location.href + "]" + (document.title || location.href) + "[/url]",
          "DISPLAY": "LINE"
        }
      ]
    }
  ]);
});
</script>

To pass data as plain text, use the simplified format. You can use these tags in the text: BR, B, U, I, S, URL.

<script type="text/javascript"> window.addEventListener('onBitrixLiveChat', function(event) {
  var widget = event.detail.widget;
  widget.setCustomData("[b]Victor Ivanov[/b] (victor@ivanov.ru)");
});
</script>

Read more about blocks in the Bitrix24 Bot Platform course.

3. Handle events

<script type="text/javascript"> window.addEventListener('onBitrixLiveChat', function(event) {
  var widget = event.detail.widget;

  // Handle events
  widget.subscribe({
    type: BX.LiveChatWidget.SubscriptionType.EVENT_SUBSCRIPTION_TYPE,
    callback: function(data) {
      // any command
      ...
    }
  });
});
</script>

BX.LiveChatWidget.SubscriptionType.configLoaded — Runs when Open Channels configuration data loads.
BX.LiveChatWidget.SubscriptionType.widgetOpen — Runs when the widget opens.
BX.LiveChatWidget.SubscriptionType.widgetClose — Runs when the widget closes.
BX.LiveChatWidget.SubscriptionType.sessionStart — Runs when a session starts.
Example:
```
{sessionId: 123}
```

BX.LiveChatWidget.SubscriptionType.sessionOperatorChange — Runs when the agent changes.
Example:

{operator: {name: '', firstName: '', lastName: '', workPosition: '', avatar: '', online: false}}

BX.LiveChatWidget.SubscriptionType.sessionFinish — Runs when a session ends.
Example:
```
{sessionId: 123}
```

BX.LiveChatWidget.SubscriptionType.operatorMessage — Runs when an agent sends a message.
Example:

{id:"44609041",chatId:711773,senderId:1246,recipientId:"chat711773",date:"2018-11-22T20:17:57.000Z",text:"hello!"}

BX.LiveChatWidget.SubscriptionType.userMessage — Runs when a user sends a message.
Example:
```
{id: 123, text: ''}
```
BX.LiveChatWidget.SubscriptionType.userVote — Runs when a user submits a vote.
Example:
```
{vote: "like"} // like|dislike
```

BX.LiveChatWidget.SubscriptionType.every — Runs for all events, so you can handle everything in one place.
The every event uses a slightly different format:

<script type="text/javascript"> window.addEventListener('onBitrixLiveChat', function(event) {
  var widget = event.detail.widget;

  widget.subscribe({
    type: BX.LiveChatWidget.SubscriptionType.every,
    callback: function(event) {
      if (event.type == BX.LiveChatWidget.SubscriptionType.configLoaded) {
        widget.open();
      }
    }
  });
});
</script>

Example:

{type: "userVote", data: {vote: "like"}}

The type field contains the event code. The data field contains the event payload. See the examples above for each event.

You can combine the final JavaScript from any of the three code sections based on your needs.

Example:

<script type="text/javascript">

window.addEventListener('onBitrixLiveChat', function(event) {
  var widget = event.detail.widget;

  // Set external user authorization
  widget.setUserRegisterData({
    'hash': '12b42ebcec7e3c26a313272c26efddbd',
    'name': 'Victor',
    'lastName': 'Ivanov',
    'avatar': 'http://files.shelenkov.com/images/avatar-ivanov.jpg',
    'email': 'victor@ivanov.ru',
    'gender': 'M',
    'position': 'Honored User'
  });

  // Pass additional data at the start of a new session, extended format
  widget.setCustomData([
    {
      "USER": {
        "NAME": "Victor Ivanov",
        "AVATAR": "http://files.shelenkov.com/images/avatar-ivanov.jpg"
      }
    },
    {
      "GRID": [
        {
          "NAME": "Email",
          "VALUE": "victor@ivanov.ru",
          "DISPLAY": "LINE"
        },
        {
          "NAME": "Client code",
          "VALUE": "12234",
          "COLOR": "#ff0000",
          "DISPLAY": "LINE"
        },
        {
          "NAME": "Site",
          "VALUE": location.hostname,
          "DISPLAY": "LINE"
        },
        {
          "NAME": "Page",
          "VALUE": "[url=" + location.href + "]" + (document.title || location.href) + "[/url]",
          "DISPLAY": "LINE"
        }
      ]
    }
  ]);

  widget.subscribe({
    type: BX.LiveChatWidget.SubscriptionType.every,
    callback: function(event) {
      if (event.type == BX.LiveChatWidget.SubscriptionType.configLoaded) {
        widget.open();
      }
    }
  });
});
</script>

4. Change the default text in the widget window

In some cases, you may want to replace the default text shown in the widget window.

You can do this with JavaScript:

<script>window.addEventListener('onBitrixLiveChat', function(event) {
  var widget = event.detail.widget;

  widget.subscribe({
    type: BX.LiveChatWidget.SubscriptionType.configLoaded,
    callback: function() {
      widget.addLocalize({PHRASE_VARIABLE: 'Replacement text'});
    }
  });
});
</script>

To get the full list of phrase variables, run this command in the browser console:

console.table(BXLiveChat.__privateMethods__.localize);

Read more in the dedicated article Customize phrases used in the website widget.

For developers

You can customize any component located at: bitrix/js/imopenlines/component/widget/src/component

Keep in mind that after customization, you need to track updates to these components and maintain your changes.

Read more about component customization in the Bitrix Framework Developer course.

5. Disable the additional multisite configuration check for the widget

To prevent authorization resets, make the required configuration changes.

By default, the multisite configuration check for the Bitrix24 widget is enabled in the Open Channels (imopenlines) module starting with version 21.400.0. If the system detects this configuration, the widget shows a notification.

Use this code to disable the check:

<script>window.addEventListener('onBitrixLiveChat', function(event){
  var widget = event.detail.widget;
  widget.setOption('checkSameDomain', false);
});
</script>

Go to Bitrix24

Don't have an account? Create for free

Bitrix24 Helpdesk

Website widget: advanced settings

2. Manual setup