Website widget: advanced settings

Author: Emily Walker

Last update: February 19, 2024.

If you already have a website widget connected to your website and you would like to identify clients in Bitrix24 Live Chat, you can use the solutions listed in this article.

For example, you have a Bitrix24 online store and a Bitrix24 website. The customer has bought something in your online store and now visits your website for the first time.

For customers that are not logged in to any of your services, you can use a special CRM web form.

For customers that are logged in to any of your services, we have a more interesting solution, and your customers will not need to fill out the contact form again.

How it works

"Bitrix Site Manager"

Add the b24connector.openline.info component (a component of the Bitrix24 Integration module) to the page where the widget is installed. The component automatically transmits contact information of the authorized clients to the widget.

Manual configuration

For third-party systems, you can add a special JavaScript code to the page your website widget is connected to.

Generally, this code looks like that:

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

	// 1. Setting external user authentication
	...
	
	// 2. Setting custom data
	...
	
	// 3. Event handling
	...
	
});
</script>

Working with the website widget:

widget.open() – open widget;
widget.close() – close widget;
widget.subscribe() – event subscription;
widget.setUserRegisterData() – set external user authentication;
widget.setCustomData() – set custom data;
widget.setOption() - set additional options.

1. Setting external user authentication

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

	// Settings external user authentication
	widget.setUserRegisterData({
		'hash': '12b42ebcec7e3c26a313272c26efddbd',
		'name': 'John',
		'lastName': 'Smith',
		'avatar': 'http://files.smith.com/images/avatar-john.jpg',
		'email': 'john@smith.com',
		'www': 'https://bitrix24.com',
		'gender': 'M',
		'position': 'Loyal Customer'
	});
	
});
</script>

Note:
hash is a special field that "replaces" authentication. This code needs to be MD5 format and unique within your Bitrix24. For example: md5(USER_ID+_website_address_ + _secret_code_)

2. Setting custom data

You can set custom data by using special blocks:

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

	// Setting custom data (get published at the beginning of a new conversation, extended format)
	widget.setCustomData([
		{"USER": {
			"NAME" : "John Smith",
			"AVATAR" : "http://files.smith.com/images/avatar-john.jpg",
		}},
		{"GRID": [
			{
				"NAME" : "E-mail",
				"VALUE" : "john@smith.com",
				"DISPLAY" : "LINE",
			},
			{
				"NAME" : "Customer ID",
				"VALUE" : "12234",
				"COLOR" : "#ff0000",
				"DISPLAY" : "LINE"
			},
			{
				"NAME": "Website",
				"VALUE": location.hostname,
				"DISPLAY": "LINE"
			},
			{
				"NAME": "Page",
				"VALUE": "[url="+location.href+"]"+(document.title || location.href)+"[/url]",
				"DISPLAY": "LINE"
			},
		]}
	]);
	
});
</script>

To publish the data in text format, you can use a simplified construction. In the text, you can use HTML tags: BR, B, U, I, S, URL.

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

	widget.setCustomData("[b]John Smith[/b] (john@smith.com)");

});
</script>

Read more about block and how to use them in the Bitrix24 Bot Platform course.

3. Event handling

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

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

BX.LiveChatWidget.SubscriptionType.configLoaded – "information about the open channel has been loaded" event.
BX.LiveChatWidget.SubscriptionType.widgetOpen – "widget has been opened" event.
BX.LiveChatWidget.SubscriptionType.widgetClose – "widget has been closed" event.
BX.LiveChatWidget.SubscriptionType.sessionStart – "conversation has been started" event.
Example of the result:
```
{sessionId: 123}
```
BX.LiveChatWidget.SubscriptionType.sessionOperatorChange – "the agent has been changed" event.
Example of the result:
```
{operator: {name: '',firstName: '',lastName: '',workPosition: '',avatar: '',online: false}}
```
BX.LiveChatWidget.SubscriptionType.sessionFinish – "conversation has been finished" event.
Example of the result:
```
{sessionId: 123}
```
BX.LiveChatWidget.SubscriptionType.operatorMessage – "the agent has sent a message" event.
Example of the result:
```
{id:"44609041",chatId:711773,senderId:1246,recipientId:"chat711773",date:"2018-11-22T20:17:57.000Z",text:"hi!"}
```
BX.LiveChatWidget.SubscriptionType.userForm – "the customer has filled the web form" event .
Example of the result:
```
{form: "welcome", fields: {name: "", phone: "", email: ""}} // welcome|offline|history
```
BX.LiveChatWidget.SubscriptionType.userMessage – "the customer has sent a message" event.
Example of the result:
```
{id: 123, text:"hi!"}
```
BX.LiveChatWidget.SubscriptionType.userVote – "the customer has rated the conversation" event.
Example of the result:
```
{vote: "like"} // like|dislike
```

BX.LiveChatWidget.SubscriptionType.every – the results of all events can be specified at once in this event.
Event type every is slightly different:

<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 of the result:

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

type shows you an event type, data – event data (examples of these data are given above).

Your final JavaScript code may consist of 3 parts, depending on your needs.

For example:

<script type="text/javascript">

 window.addEventListener('onBitrixLiveChat', function(event)
{
	var widget = event.detail.widget;
	
	// Setting external user authentication
	widget.setUserRegisterData({
		'hash': '12b42ebcec7e3c26a313272c26efddbd',
		'name': 'John',
		'lastName': 'Smith',
		'avatar': 'http://files.smith.com/images/avatar-john.jpg',
		'email': 'john@smith.com',
		'www': 'https://bitrix24.com',
		'gender': 'M',
		'position': 'Loyal Customer'
	});	

	// Setting custom data (get published at the beginning of a new conversation, extended format)
	widget.setCustomData([
		{"USER": {
			"NAME" : "John Smith",
			"AVATAR" : "http://files.smith.com/images/avatar-john.jpg",
		}},
		{"GRID": [
			{
				"NAME" : "E-mail",
				"VALUE" : "john@smith.com",
				"DISPLAY" : "LINE",
			},
			{
				"NAME" : "Customer ID",
				"VALUE" : "12234",
				"COLOR" : "#ff0000",
				"DISPLAY" : "LINE"
			},
			{
				"NAME": "Website",
				"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. Customize phrases used in the website widget

You can customize phrases used in the Bitrix24 Website Widget.

Use JavaScript code to do that:

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

	widget.subscribe({
		type: BX.LiveChatWidget.SubscriptionType.configLoaded,
		callback: function() 
		{
			widget.addLocalize({VARIABLE: 'New Text'});				
		}
	});
	
});
</script>

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

5. Hide the contact information form

You can hide the contact information form:

Use JavaScript code to do that:

<script>window.addEventListener('onBitrixLiveChat', function(event)
{
 var widget = event.detail.widget;
 widget.mutateTemplateComponent('bx-livechat-form-welcome', { template: '<div></div>'});
});
</script>

6. Disabling additional multisite configuration checking for the widget

When you use end-to-end authorization between "Bitrix Site Manager" and "Bitrix24 On-premise Edition" in a multi-site configuration on the same core and on the same subdomain of the primary domain, user authorization resets.

To avoid authorization resetting, you need to do some settings.

By default, the multi-site configuration check for Bitrix24 widget is enabled in the Open channels module (imopenlines) since 21.400.0 version. When such a configuration is detected, you will receive a notification in the widget.

This code disables the check:

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

Was this information helpful?

Integration specialist assistance

That's not what I'm looking for

Complicated and incomprehensible text

The information is outdated

It's too short. I need more information

I don't like the way this tool works

Go to Bitrix24

Don't have an account? Create for free

Tables in Bitrix24 Sites, Stores, and Knowledge bases Transfer sites and online stores to another Bitrix24 account Site access permissions Website favicon Cookie processing Action on click in site block elements Change design in Sites and Stores Add YouTube videos and Shorts to Bitrix24 Sites Unpublish and delete sites Automatic block change, FAQ block, and GIF images

Bitrix24Care