Read FAQ
NEW
Bitrix24 Support
Registration and Authentication
How to start
My Profile
Feed
Chats and Calls
Calendar
Bitrix24.Docs
Bitrix24.Drive
Bitrix24.Mail
Workgroups
Tasks and Projects
CRM
CoPilot - AI in Bitrix24
Contact Center
Sales Center
CRM Analytics (beta)
BI Builder
Sales Intelligence
Inventory Management
Marketing
Sites
Online Store (beta)
CRM + Online Store
CRM Store (beta)
Bitrix24.Sign
Company
Knowledge base (beta)
Automation
Workflows
Telephony
Market
Subscription
Settings
Enterprise
Mobile App
Desktop App
General questions
Bitrix24 On-Premise

Bitrix24Care

Website widget: advanced settings

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