top_en
Log In

Bitrix24Care

Website widget: advanced settings

Rating:

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

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;

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.
This helped Thanks :) This didn't help Sorry :(
Could you please tell us why:
It's not what I'm looking for
It's too complicated