HomeGuidesAPI ReferenceChangelogsDiscussions
GuidesChangelogsAPI ReferencePublic RoadmapService StatusLog In

Webchat SDK

Our webchat comes with a software developer kit with some useful functions and events management mechanisms
Depending on your needs, you can go for the synchronous or asynchronous way.

Synchronous controls

Synchronous controls are powerful and can act on real time with your webchat BUT you have to wait for the SmartlyWebchat library to be loaded in your website and that the webchat is fully ready.
Here is a code you can use:

var SMARTLY_APP_ID = "(YOUR BOT ID)";
var SMARTLY_LANG = "(YOUR BOT LANGUAGE)";
var SMARTLY_USER_DATA={};
(function(){d=document;s=d.createElement("script");
	s.onload = function() {
		// Use setInterval to check if SmartlyWebchat is ready
		// If SmartlyWebchat is ready, we clear the interval
		var interSmartlyWebchatLoaded = window.setInterval(function() {
			if(typeof SmartlyWebchat !== 'undefined' && SmartlyWebchat.ready) {
				window.clearInterval(interSmartlyWebchatLoaded);
				SmartlyWebchat.openWidget();
			}
		},1000);
	};
    s.src="https://(YOUR CDN SUB DOMAIN).smartly.ai/webchat.min.js" + "?ts=" + new Date().getTime();s.async=1;d.getElementsByTagName("head")[0].appendChild(s);}
)();

🚧

Warning

In the code below (YOUR CDN SUB DOMAIN) should be replaced with the subdomain relative to your bot instance, as a reminder here there are

Instance nameCDN url subdomain
Smartly.AI PRODcdn
Virtual Agent PRODcdn-virtual-agent-enriched

And here is all the webchat controls that you can use with our widget.

// Open the webchat 
SmartlyWebchat.openWidget(); 
  
// Open the webchat and display a specific message
SmartlyWebchat.openWidget('Hi, are you interested by a demo?'); 
  
// Close the webchat
SmartlyWebchat.closeWidget();
  
// Hide the webchat
SmartlyWebchat.hideWidget();
  
// Show the webchat
SmartlyWebchat.showWidget();
  
// The webchat will display a specific bot message on the webchat
SmartlyWebchat.showBotMessage('I am the bot');
  
// The webchat will display a specific bot message on the webchat after a certain delay, in ms
SmartlyWebchat.showBotMessage('I am the bot',5000);
  
// Send a user message to the bot 
SmartlyWebchat.sendUserMessage('I am the user');
  
// Send a user message to the bot after a certain delay, in ms
SmartlyWebchat.sendUserMessage('I am the user',5000);
  
// Send a user message to the bot without showing it in web chat
SmartlyWebchat.sendHiddenUserMessage('This is a secret message');

📘

Messages syntax

Messages sent and displayed can be plain text or structured JSON

For instance you could have:

// Simple text message
var message;
message='Hi, are you interested by a demo?';
SmartlyWebchat.openWidget(message); 

// or

// Rich message
var message = ' [{"quick_replies": [{"content_type": "text","title": "Yes","payload": "I agree"},{"content_type": "text","title": "No","payload": "I disagree"}],"text": " Do you agree with our terms and conditions?"}]';
SmartlyWebchat.openWidget(message);

🚧

Wait for SmartlyWebchat to be loaded

Before using the sdk to be fully loaded in your web page

Some use cases based on webchat controls

1. Open the webchat with a specific message if the user clicks 3 times in the current page

const maxCountClick = 3;
function openOnClicks() {
SmartlyWebchat.openWidget('You have clicked 3 times');
}
(function(){var countClick = 0;function bindSmartlyWebchatWithWindowClick(){countClick++;if(countClick == maxCountClick) {document.removeEventListener("click", bindSmartlyWebchatWithWindowClick, false);openOnClicks();}}document.addEventListener("click", bindSmartlyWebchatWithWindowClick, false);})();

2. Open the webchat with if the user load the webpage, then do nothing during a defined amount of time

const inactivityDuration = 10000;
function doActionAfterInactivity() {
SmartlyWebchat.openWidget('Since the page loaded, you have been inactive during 10s!'); 
}
(function(){function stopTimer(){document.removeEventListener("mousemove", stopTimer, false);document.removeEventListener("mousedown", stopTimer, false);window.clearTimeout(myTimeout);}document.addEventListener("mousemove", stopTimer, false);document.addEventListener("mousedown", stopTimer, false);myTimeout = window.setTimeout(doActionAfterInactivity, inactivityDuration);})();

Can I hide the input field of the webchat?

Sure,
If you want your user to only use buttons clics, you can hide the whole input field by setting the following value from the Node.js bloc code.

output.webchat_hidden_input = true;

Can I customize the webchat placeholder?

Sure, you do it by adding the following code in the Node.js bloc code where you want to see the change. Otherwise, the default placeholder will be shown.

output.webchat_input_place_holder = "Please type your phone number"

Can I stop the autocompletion ?

Sure, you do it by adding the following code in the Node.js bloc code where you want to see the change. Otherwise, the default placeholder will be shown.

output.payload.autocompletion = false;

Can I catch events from the webchat?

Yes, here is the event list you will receive in the hosting page
Here is the available events that you can catch

  • conversationRestarted
    This event is fired anytime the user is reintialising the conversation.
SmartlyWebchat.on('conversationRestarted', function(event, output){
	// your code
});
  • webchatClosed
    This event is fired anytime the webchat is closed by the user
SmartlyWebchat.on('webchatClosed', function(){
	// your code
});
  • webchatOpened
    This event is fired anytime the webchat is opened by the user
SmartlyWebchat.on('webchatOpened', function(){
	// your code
});
  • userMessageSent
    This event is fired anytime a message is sent by the user is sent to the platform.
    The message can be the result of a button click or a text
SmartlyWebchat.on('userMessageSent', function(event, output){
	// your code
});

and here is what you can expect in the output field

{
   "message":"hello Mr Robot!"
}
  • botResponseReceived
    This event is fired anytime a bot response is received. A bot response can include multiple messages.
SmartlyWebchat.on('botResponseReceived', function(event, output){
	// your code
});

and here is what you can expect in the output field

{
   "input":"",
   "corrected_input":"",
   "intent":"",
   "intent_slug":"",
   "intent_id":"",
   "confidence":0,
   "confidence_threshold":0,
   "understood":true,
   "understood_nlu":false,
   "never_trained":false,
   "state_id":"98dlp4ptg4",
   "state_name":"Welcome State",
   "answer":"Welcome at Green Money bank!   What is your question?",
   "reprompt":"Sorry, I didn't get that.",
   "end_session":false,
   "user_id":"JWcEwLj0BS_fr-fr",
   "platform":"webchat",
   "muted":false,
   "need_help":false,
   "handover_category_name":"",
   "payload":{
      
   },
   "no_reply_prompt":"",
   "probabilistic_nlu_processing_time":0,
   "rule_based_nlu_processing_time":0,
   "dialog_management_processing_time":0,
   "rich_text":[
      {
         "attachment":{
            "type":"image",
            "payload":{
               "url":"https://media-preprod.smartly.ai/image/1650971620592594d22103c8b910007d3eaa4wctLyPhfXQBDWBkhJpJP.png",
               "internal_url":"/media/image/1650971620592594d22103c8b910007d3eaa4wctLyPhfXQBDWBkhJpJP.png"
            }
         }
      },
      {
         "attachment":{
            "type":"video",
            "payload":{
               "url":"https://media-preprod.smartly.ai/video/1650971745711594d22103c8b910007d3eaa4PUSulAdrZJyfmNHpegTn.mp4",
               "internal_url":"/media/video/1650971745711594d22103c8b910007d3eaa4PUSulAdrZJyfmNHpegTn.mp4"
            }
         }
      }
   ],
   "show_answer_survey":true,
   "show_conversation_survey":false,
   "webchat_input_place_holder":"",
   "webchat_hidden_input":null,
   "lang":"fr-fr",
   "skill_id":"60c0de2ec9455077e4edb1ec",
   "input_type":"text",
   "client_id":"628e03e17dac365b208c33b9",
   "master_bot":false,
   "client_session_id":"6290b227b83016997c7c9df0",
   "first_client_session_id":null,
   "number_of_nounderstood":0,
   "is_smartly_integration":true,
   "is_simulator":false,
   "event_name":"NEW_DIALOG_SESSION",
   "total_processing_time":0.08
}
  • agentMessageReceived
    This event is fired anytime a message from a human agent is received
    This only happens during an escalation
SmartlyWebchat.on('agentMessageReceived', function(event, output){
	// your code
});

and here is what you can expect in the output field

{
   "app_id":"60c0de2ec9455077e4edb1ec",
   "user_id":"JWcEwLj0BS_fr-fr",
   "text":"test",
   "operator":true,
   "image":"[Image URL]",
   "firstName":"Yacine",
   "lang":"fr-fr"
}
  • answerSurveySent
    This event is fired anytime a user is responding to an answer survey
SmartlyWebchat.on('answerSurveySent', function(event, output){
	// your code
});

and here is what you can expect in the output field

{
   "survey_result":{
      "input":"Was this helpful?",
      "response":"Glad to help. Do you have another question?",
      "like_dislike":"like"
   },
   "input":"",
   "bot_answer":"...",
   "client_id":"628e03e17dac365b208c33b9",
   "survey_id":"5fbbd2f756ee9f15ab4278a5",
   "user_id":"JWcEwLj0BS_fr-fr",
   "webchat_main_bot_id":"60c0de2ec9455077e4edb1ec",
   "first_name":"Anonym",
   "last_name":"User",
   "skill_id":"60c0de2ec9455077e4edb1ec",
   "lang":"fr-fr",
   "client_session_id":"6290b227b83016997c7c9df0",
   "answer":"Glad to help. Do you have another question?"
}
  • conversationSurveySent
    This event is fired anytime a user is responding to a conversation survey
SmartlyWebchat.on('conversationSurveySent', function(event, output){
	// your code
});

and here is what you can expect in the output field

{
   "like_dislike":null,
   "rate_stars":4,
   "feedback":"test"
}