Hooks

ConvoKraft hooks are functions that can be configured by the developers in the global scope of a Catalyst web application and can be accessed using the ConvoKraft object. The ConvoKraft JS SDK provisions the below listed hooks :

• handleResponse
• handleMissed
• handleError
• minimizeChat
• didConnect
• setOnBoarding
• setOnBoardingSentences
• setClientSessionData
• handleUpload
• handleWelcome

handleResponse

Based on the response provided by ConvoKraft for any action, you can handle the data and customize the visual representation of the response as per your specific requirements.

The original response sent will be sent in the data key of a Deluge function from your web application. In order to customize the response, you need to pass the data value to the following hook along with the HTML element, within which the web application can render the ConvoKraft’s original response.

Syntax

    

        
copy
        

            

        
    
    

         convokraft.handleResponse=function(actionName,data,element,responseHandled,fromHistory,fromPagination)
{
//Enter logic here
return true;
}

    

The below table provides details about the various elements of the function :

Element	Description
actionName	The namespace of the action invoked.
data	It holds the custom data that is being sent from Deluge to the hook.
element	It holds ConvoKraft's custom reply element that will be displayed in the chat window.
responseHandled	This is a mandatory callback function, which helps the bot to know that DOM operations are complete and it can scroll the chat div to top.
fromHistory	This key contains a Boolean value that represents whether the current message being constructed is from the current session or any past sessions.
fromPagination	This key contains a Boolean value that represents whether the current message being constructed is a message after a pagination call. If true, it is not advisable to call responseHandled(), so that messages don't scroll all the way down.

Sample code

    

        
copy
        

            

        
    
    

         convokraft.handleResponse = function(actionName,data,element,responseHandled,fromHistory,fromPagination)
{
if(actionName=="schedule_event")
{
element.innerHTML="This is a test function from "+data.name;
element.style.padding="10px";
responseHandled();
return false; //Renders the above constructed response
}
return true; //Renders original convokraft response
}

    

handleMissed

If the user’s message doesn’t match with any of the configured actions of your bot, and in that case if you have defined the convokraft.handleMissed() hook in your web application’s global scope, then ConvoKraft would display the custom response as rendered through this hook.

Syntax

    

        
copy
        

            

        
    
    

         convokraft.handleMissed = function(element, responseHandled, fromHistory, fromPagination)
{
//Enter the logic of the element which will be rendered as convokraft's response 
}

    

The following table describes the syntax elements and their descriptions :

Element	Description
element	It holds ConvoKraft's custom reply element that will be displayed in the chat window.
responseHandled	This is a mandatory callback function, which helps the bot to know that DOM operations are complete and it can scroll the chat div to top.
fromHistory	This key contains a boolean value that represents whether the current message being constructed is from the current session or any past sessions.
fromPagination	This key contains a boolean value that represents whether the current message being constructed is a message after a pagination call. If true, it is not advisable to call responseHandled(), so that messages don't scroll all the way down.

Sample code

    

        
copy
        

            

        
    
    

         convokraft.handleMissed= function(element,responseHandled,fromHistory){
element.innerHTML = "
Sorry! Not found!

";
responseHandled();
return false;
}

    

handleError

If any API error occurs while executing an action, you can use this hook to display a custom error response by defining convokraft.handleError in your Catalyst web application’s global scope.

Syntax

    

        
copy
        

            

        
    
    

         convokraft.handleError = function(element, responseHandled, fromHistory, fromPagination)
{
//Enter logic to customize error message
}

    

The following table describes the syntax elements and their descriptions :

Element	Description
element	It holds ConvoKraft's custom reply element that will be displayed in the chat window.
responseHandled	This is a mandatory callback function, which helps the bot to know that DOM operations are complete and it can scroll the chat div to top.
fromHistory	This key contains a boolean value that represents whether the current message being constructed is from the current session or any past sessions.
fromPagination	This key contains a boolean value that represents whether the current message being constructed is a message after a pagination call. If true, it is not advisable to call responseHandled(), so that messages don't scroll all the way down.

Sample code

    

        
copy
        

            

        
    
    

         convokraft.handleError= function(element,responseHandled){
if(typeof data !== "undefined"){
messageString = data.data.code;
}
else{
messageString = "Api Error!";
}
element.innerHTML = "
Sorry! "+messageString+"

";
responseHandled();
}

    

minimizeChat

This hook enables the user to minimize or maximize the chat window when clicked on its header.

Syntax

    

        
copy
        

            

        
    
    

         convokraft.minimizeChat=function()
{
//obtain your chat div and apply minimize animation and styles as you need
}

    

Sample code

    

        
copy
        

            

        
    
    

         convokraft.minimizeChat=function()
{
if(document.getElementById("zdivid").style.marginBottom=="-400px"||document.getElementById("zdivid").style.marginBottom=="")
{ 
document.getElementById("zdivid").style.marginBottom="-0px";
}
else
{ 
document.getElementById("zdivid").style.marginBottom="-400px";
}
}

    

didConnect

This hook is used to notify the Catalyst web application that the chat is loaded completely.

Syntax

    

        
copy
        

            

        
    
    

         convokraft.didConnect=function()
{
//Enter logic here        
}

    

Sample code

    

        
copy
        

            

        
    
    

         convokraft.didConnect=function()
{
var loadingDiv=document.getElementById("loadingDiv");
if(loadingDiv)
{
loadingDiv.style.display='none';
}
}

    

setOnBoarding

If there is no history of chat, then the onboarding screen would be displayed by default. This hook can be defined in the global scope of your web application in order to customize the ConvoKraft bot’s onboarding screen as per your requirements.

Syntax

    

        
copy
        

            

        
    
    

         convokraft.setOnBoarding=function(element,sentences,placeholders)
{
//construct HTML and styles as per your need and push it to the element
}

    

The following table explains the syntax elements and their descriptions :

Element	Description
element	It holds the HTML element that needs to be customized.
sentences	It holds the sample sentences of that particular action.
placeholders	It is an array of strings that can be used to hold different parameters for sentences displayed in the onboarding screen

Sample code

    

        
copy
        

            

        
    
    

         convokraft.setOnBoarding=function(element,sentences,placeholders)
{
var html="
This is a custom onboarding screen by client app and here are the list of sentences:


";
sentences.forEach(function(item)
{
html+="
"+item+"
";
})
html+="
";
element.innerHTML=html;
element.style.padding="10px";
}

    

setOnBoardingSentences

This hook is used to customize the onboarding sentences or action suggestions that appear when you open a ConvoKraft chat window. By default, the chat window displays the suggestions based on the configured sample sentences of the ConvoKraft actions. An array of objects can be passed in the JSON format as arguments to this hook as listed below. Also note that with the help of sentences in the JSON, different values for placeholders can be set and returned.

    

        
copy
        

            

        
    
    

         [
{
"id": "1",
"sentence": "Apply leave for {{fromdate}} and {{todate}}",
"actual_sentence": "Apply leave for today and tomorrow"
},
{
"id": "2",
"sentence": "What is the {{property}} of {{country}}?",
"actual_sentence": "What is the capital of India?"
}
]
//Filter or modify the sentences to be shown in the onboarding screen

    

Syntax

    

        
copy
        

            

        
    
    

         convokraft.setOnBoardingSentences=function(sentences)
{
//define the HTML and styles as per your need and push it to the elemen
}

    

Sample code

    

        
copy
        

            

        
    
    

         convokraft.setOnBoardingSentences=function(sentences)
{
sentences.splice(0,8);
return sentences;
}

    

setClientSessionData

This hook is used to get the custom client session data of your Catalyst web application. Please make sure to define it in your Catalyst web application’s global scope for Convokraft to access it.

Syntax

    

        
copy
        

            

        
    
    

         convokraft.setClientSessionData=function()
{
//return a JSON Object
}

    

Sample Code

    

        
copy
        

            

        
    
    

         convokraft.setClientSessionData=function()
{
return 
{
portal_name: "zylker",
ui_version: "2.0"
}
}

    

handleUpload

This hook is used to define the operations to be performed after uploading a file. If the chosen development platform is Deluge or Function, then the file will be uploaded in the Catalyst cloud environment. In case of Webhooks, you will need to define your own file path in the file attribute. You can configure the respective messages in the onSucces and onFailure callback arguments, based on your specific requirements.

Syntax

    

        
copy
        

            

        
    
    

         convokraft.handleUpload = function(input){
//do whatever you want to to the element which will be rendered as convokraft's response 
}

    

The following attributes are supported for this hook:

Attribute Name	Usage
sessionId	The ID of current transcript session.
param	The param information of current prompt like param name, type and prompt message.
file	The file object provided by user.
action	The current conversation's action namespace.
bot	The current conversation's bot namespace.
onSuccess	The mandatory call back that accepts file ID as input.
onProgressChange	The mandatory call back that accepts calculated upload percentage as parameter. This should be called as and when the upload percentage changes. If the upload is complete, please set percentage to 100 and a message to show success state such as onProgressChange(100,“File upload completed”);
onFailure	The mandatory call back that accepts string input with a message stating the reason for upload failure.

Sample Code

    

        
copy
        

            

        
    
    

         convokraft.handleUpload=function(uploadObject){
let percentage = 20;
let onSuccess = uploadObject.onSuccess;
let onFailure = uploadObject.onFailure;
var percentageInterval = setInterval(function() {
if(percentage === 100){
clearInterval(percerntageInterval);
uploadObject.updateProgress(100,"Your file is being processed. Please wait...");
setTimeout(function() {
if(zia.fileUploadCount > 1){
onSuccess((Date.now()).toString());
}
else{
onFailure("Your file is over 2MB. Please upload a file of less size.");
}
}, 5000);
return;
}
percentage+=20;
uploadObject.onProgressChange(percentage);
}, 500);
}

    

handleWelcome

This hook is used to modify the welcome message (the first message displayed in the chat session). This hook can be used when you need to customize only the UI. If you need a backend logic to be executed to display the welcome message, then use the welcome message handler function.

Syntax

    

        
copy
        

            

        
    
    

         convokraft.handleWelcome = function(config){
//do whatever you want to to the element which will be rendered as convokraft's response 
}

    

Sample Code

    

        
copy
        

            

        
    
    

         convokraft.handleWelcome = function(config) {
config.element.innerHTML = `Hello Guest! Here are few things I can do for you. <div class='suggestion'>Raise a ticket</div> <div class='suggestion'>List my inventory and assets</div>`;
}