BLiP Chat Widget — Tips and Tricks

6 min readJan 20, 2020

Written by:
@andrebnassis — https://github.com/andrebnassis
@phabh — https://github.com/phabh

Introduction

BLiP Chat is the messaging channel created by BLiP, used on websites and apps. On this tutorial, We will show you some tips and tricks about its use.

Script

How to install it on a website

To install it on a website, just follow the steps on this article:
https://help.blip.ai/docs/channels/blip-chat/adicionar-bot-site-blip-chat/

How to test it as localhost

1. Install node LTS
https://nodejs.org/en/download/

2. Install package serve
npm -g i serve --save

3. Execute the command ‘serve’ inside the folder that the webpage script (with BLiP Chat script on it) is located.
serve

4. Open the localhost url created (in this example, http://localhost:5000) and BLiP Chat Widget will show up in the lower left corner.

Usage Tips

Basic script example

<script src="https://unpkg.com/blip-chat-widget" type="text/javascript">
</script>
<script>
    (function () {
        window.onload = function () {
            new BlipChat()            
            .withAppKey('YOUR-BLIPCHAT-API-KEY')
            .withButton({"color":"#2CC3D5","icon":""})
            .build();
        }
    })();
</script>

A) Defining a userId

function withAuth()
This function allows you to set the authentication type as well as the user identifier.
This function usually is used to define a user in an authenticated area (keeping the same identifier when logged, having the conversation thread history). Other way of use is in a non authenticated area (setting up a new user identifier on every new access, loosing the conversation thread history)

.withAuth({
       authType: BlipChat.DEV_AUTH,
       userIdentity: '1234567',
       userPassword: 'passwrd',
  })

To generate a random id, you could use the followed function:

function uuidv4() {
              return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
                var r = Math.random() * 16 | 0, v = c == 'x' ? r : (r & 0x3 | 0x8);
                return v.toString(16);
              });
            }

Resulting the script below:

(function () {
        window.onload = function () {
		
		function uuidv4() {
              return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
                var r = Math.random() * 16 | 0, v = c == 'x' ? r : (r & 0x3 | 0x8);
                return v.toString(16);
              });
            } 
		
			var blipClient = new BlipChat();
			blipClient			.withAppKey('YOUR-BLIPCHAT-API-KEY')
			.withAuth({
				authType: BlipChat.DEV_AUTH,
				userIdentity: uuidv4(),
				userPassword: 'passwrd',
			})
            .build();
        }
    })();

B) Setting contact information on the first interaction

function withAccount()
With this function, you can define initial parameters of the user account information and its data is replicated on the user contact information.
Note: After the first user access, this function will not update user account neither contact information. To update contact information, you could:

— Option 01 (Recommended) Use the message metadata to send updated informations (item G of this article). Next, inside the Builder Framework, you can access the message metadata and update the contact information using Set Contact action.

— Option 02: Call the update contact information command (using BLiP SDK or HTTP request). Next, inside the Builder framework, you must create a SetContact action, to update the cache contact of the Builder Framework, and then you could access the updated contact information on Builder.

(function () {
        window.onload = function () {
			var blipClient = new BlipChat();
			blipClient
.withAppKey('YOUR-BLIPCHAT-API-KEY')
			.withAccount({
				fullName: 'John Doe',
				email:'johndoe@gmail.com',
				phoneNumber: '+15055034455',
				city: 'Decatur',
				extras:{
					key: 'value'
				}
			})
            .build();
        }
    })();

C) Do something based on BLiP Chat Widget events

function withEventHandler()
Using this function, it is possible to do some activities based on the following events:
OnEnter — Execute some action on opening the chat
OnLeave — Execute some action on closing the chat
OnLoad — Execute some action on finish loading the chat
OnCreateAccount — Execute some action on creating new user account

(function () {
        window.onload = function () {
          var blipClient = new BlipChat()
.withAppKey('YOUR-BLIPCHAT-API-KEY')
            .withEventHandler(BlipChat.ENTER_EVENT, function () {
              console.log('enter')
            })
            .withEventHandler(BlipChat.LEAVE_EVENT, function () {
              console.log('leave')
            })
            .withEventHandler(BlipChat.LOAD_EVENT, function () {
              console.log('chat loaded')
            })
            .withEventHandler(BlipChat.CREATE_ACCOUNT_EVENT, function () {              console.log('account created')
            })          blipClient.build()
      }
    })();

D) Sending a message

function sendMessage()
Ex: Sending a message after BLiP Chat load

(function () {
        window.onload = function () {
			var blipClient = new BlipChat();
			blipClient
            .withAppKey('YOUR-BLIPCHAT-API-KEY')
		.withEventHandler(BlipChat.LOAD_EVENT, function () {
		blipClient.sendMessage({
              "type": "text/plain",
              "content": "Start"
			});
			})
            .build();
        }
    })();

E) Sending a hidden message

function sendMessage() + metadata
Ex: Sending a message after BLiP Chat load

(function () {
        window.onload = function () {
			var blipClient = new BlipChat();
			blipClient
                  .withAppKey('YOUR-BLIPCHAT-API-KEY')
        		.withEventHandler(BlipChat.LOAD_EVENT, function () {
			blipClient.sendMessage({
                  "type": "text/plain",
                  "content": "Start",
                  "metadata":{
                    "#blip.hiddenMessage": true
                   }
                  });
			})
            .build();
        }
    })();

function sendMessage() + chatstate
Ex: Sending a message after BLiP Chat load

(function () {
        window.onload = function () {
			var blipClient = new BlipChat();
			blipClient
                  .withAppKey('YOUR-BLIPCHAT-API-KEY')
      		.withEventHandler(BlipChat.LOAD_EVENT, function () {
			blipClient.sendMessage(
			{
			"type":"application/vnd.lime.chatstate+json",
			"content": {
			"state": "starting"
			  }
			});
			})
            .build();
        }
    })();

F) Disable message thread history

function withoutHistory()
With this function, the message thread history will not appear to the user

(function () {
        window.onload = function () {
			var blipClient = new BlipChat();
			blipClient
                  .withAppKey('YOUR-BLIPCHAT-API-KEY')
			.withoutHistory()
                  .build();
        }
    })();

G) Sending custom metadata in all messages sent by user

function withCustomMessageMetadata()
With this function, you can define a custom metadata to all the messages sent by the user.

(function () {
	window.onload = function () {
      var blipClient = new BlipChat()
	  .withAppKey('YOUR-BLIPCHAT-API-KEY')
	  .withCustomMessageMetadata({ "user origin" : "browser" });
	  blipClient.build();
	}
	})();

H) Targeting BLiP Chat to an HTML element

function withTarget()
The HTML element target will have the BLiP Chat on it

<html>
<head>
</head>
<body id="sdkTarget">
<script src="https://unpkg.com/blip-chat-widget" type="text/javascript">
</script>
<script>
(function () {
	window.onload = function () {
			new BlipChat()
				.withAppKey('YOUR-BLIPCHAT-API-KEY')
				.withButton({"color":"#2CC3D5","icon":""})
				.withTarget('sdkTarget')
				.build();
			}
	})();
</script>
</body>
</html>

I) Allow user to send files

https://help.blip.ai/docs/channels/blip-chat/permitir-envio-de-arquivos-blip-chat/

J) Execute command to open or close BLiP Chat window

function toogleChat()
With this command, if BLiP Chat window is opened, it will close. And if it is closed, it will open it.
client.toogleChat();

K) Delete the BLiP Chat Widget

function destroy()
Destroy the BLiP Chat Widget instance, and remove the element from the HTML target if set.
client.destroy();

L) Setting BLiP Chat icon button

function withButton()

(function () {
        window.onload = function () {
            new BlipChat()            
            .withAppKey('YOUR-BLIPCHAT-API-KEY')
.withButton({"color":"#EF3340","icon":"https://www.google.com.br/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png"})
            .build();
        }
    })();

M) Customizing BLiP Chat through CSS

function withCustomStyle()
With this function, you can customize BLiP Chat by passing a CSS code as a parameter.

(function () {
  window.onload = function () {
        var customStyle = `#message-input {
        box-sizing: border-box;
        border: 1px solid #0CC8CC;
        border-radius: 6px;
        background: #252B39;
      }
      #message-input textarea {
        background: #252B39;
        font-size: 12px;
        color: white;
      }`
    var blipClient = new BlipChat()
       .withAppKey('YOUR-BLIPCHAT-API-KEY')
       .withCustomStyle(customStyle);
       blipClient.build();
     }
})();