Conversational Web SDK [legacy]

This article pertains to the legacy version of our Conversational Web SDK. 
Please refer to our new Conversational Web SDK article for up-to-date information.

This article covers the definition and examples of all the different functionalities provided by Certainly JS API to handle communication and interaction between the hosting website (the web, from now) and the webchat widget where the conversation with the bot is displayed (the bot, from now).

We will explore:

Different types of communication flows

There are different types of communication flows, as indicated here:

Web to Bot (W2B)

Event(s) on Web

---- trigger --- >

Action(s) by Bot

dataCertainlyTransfer function

Bot to Web (B2W)

Event(s) on Bot Conv. 

---- captured by --- >

Action(s) on Web


getCertainlyTransfer function

End User persistent conversation

getUid function

initCertainly function

Requirements

All the functions specified below can be called from any browser, provided that the webchat script has previously been loaded on your site and is working in the browser from which the JS functions are called.

W2B API Function (dataCertainlyTransfer)

Fired on the Web by an event, it is able to send data to the Bot. Two use cases covered by this function:

First, it takes the conversation to a specific module ID. The bot will then show the message(s) that belong to that module and the conversation will flow normally from there.

Code example:

dataCertainlyTransfer({ 
  data: { 
    type: "go_to_module", 
    cvars: { 
      cvar1: "value cvar1", 
      cvar2 : "value cvar2" 
    }, 
    mod_id: "21890", 
    reset: true || false, 
  }, 
  webchatKey: "1", 
  openWebchat: true || false 
}); 
  • data (object): Object required to be able to render the message in the webchat box. 
       * type (string): "go_to_module" Defines the type of action.  
       * cvars (object): Includes Custom Variables that will be attached to the user profile when the bot continues the conversation. They may be used in placeholders in bot messages, webhooks, etc. 
       * mod_id (string): Module ID from where the conversation will be resumed/restarted. 
       * reset (boolean): Defines whether the Bot must delete the previous conversation messages.
  • webchatKey (string): Unique Identifier for the webchat widget. You may have several widgets in your site and it is necessary to link this action to one of them. 
  • openWebchat (boolean): it opens the webchat box (if it is not open already). Obs! This action only works if the webchat box has been open before and the conversation socket was therefore initiated already.

Second, it allows for simulating a bot message in the conversation. That message is never sent to Certainly's backend, and, therefore, is never processed and stored. The bot won't be aware of it, and the user response to it will be analyzed as a response to the last "real" bot message.

Code example:

dataCertainlyTransfer({ 
  data: { 
    type: "message_bot", 
    message: “This is the content of the simulated message 
  }, 
  webchatKey: "1", 
  openWebchat: true || false 
}); 
  • data (object): Object required to be able to render the message in the webchat box. 
       * type (string): "message_bot" Defines the type of action. 
       * message (string): "content" Message displayed in the webchat box. 
  • webchatKey (string): Unique Identifier for the webchat widget. You may have several widgets in your site and it is necessary to link this action to one of them. 
  • openWebchat (boolean): it opens the webchat box (if it is not open already). Obs! This action only works if the webchat box has been open before and the conversation socket was therefore initiated already.
B2W API Function (getCertainlyTransfer)

Fired on the web, this function is able to capture the Conversation event when the Bot arrives to a specific Module ID. 

Code example:

getCertainlyTransfer({
actionName: "21890" || ["21890", "21891"] || "*",
webchatKey: "1",
callback: ({ message, cvars }) => {
//Custom JS logic having access to the CVars and Bot message content
}
});
  • actionName (string or array): Three possible values here. A string with a module ID or a * for capturing module arrival to ANY module. To capture module arrival to several specific modules, then list the IDs in an array.
  • webchatKey (string): Unique Identifier for the webchat widget. You may have several widgets in your site and it is necessary to link this action to one of them.
  • callback (function): Custom JS function written by the webmaster to take an action triggered by the configured module arrival event on the conversation. The function may make use of two event variables which are:
       * message (object): Object which contains the metadata of the module which triggered the function. See the sample below:
    mceclip0.png
    * cvars (object): Object which contains all the stored End User Custom Variables (CVars) up until that moment. These are dynamically collected by the bot during the conversation via webhooks or end user responses. 

Please note, in order to receive this data, it must be enabled in the Bot Settings panel. Turning on the feature as shown in the image below:

conversationalwebsite.png

Persistent Session across Browsers (getUid)

This function is able to return the unique id to be able to retrieve (and resume) the active conversation of that specific user with the Bot. 
Code example:

uniqueId = getUid("botDeploymentId", "webchatKey");
// "botDeploymentId" = The id value used in initCertainly() function
// "webchatKey" = the key used in initCertainly() function

Once the value is retrieved, this can be stored by the host site linked to other user session ids or profile. The value may be used later in the initCertainly function to resume conversations linked to that user. 

This works very well in websites that already identify users in a logged-in area. The user profile will have to store the collected uniqueId to later inject it next time the same user logs in to the platform. That way, initCertainly will use the uniqueId to always resume the conversation with that user exactly where it was, even in different browsers or devices!This article pertains to the legacy version of our Conversational Web SDK.
Please refer to our >