Certainly's Conversational Web SDK

Certainly's Conversational Web SDK allows you to customize the web deployment of your Certainly bots and design powerful interactions between website and widget. This article covers the definition and examples of all the different functionalities provided by our Web SDK.

We will address:

• Certainly Widget initialization
• Certainly Web SDK methods
• Certainly Web SDK events

Certainly Widget initialization

The Certainly Widget allows your users to interact with your bot through a web chat interface that you can embed in your website's HTML. Once embedded, a widget button will appear on your website, which will open the chat view when pressed.

The process is simple! Open Bot Settings from the right sidebar menu, navigate to Channels > Certainly Widget, and find the script below "Embed the Chatbot Widget on your website".

Copy the code snippet, then paste it into the HTML code of your website at the end of the "body" element (before the </body> tag). The "id" defined in the script is your bot's deployment ID. This links the script to your bot and is necessary for it to function.

initCertainlyWidget() supports two arguments:

• Certainly bot configuration object (required)
• A callback function (optional)

initCertainlyWidget(
	{
		id: "0d7ba4fe-1345-4443-a004-c422f44f31c6",
	},
	callback //Function (optional)
);
    
function callback() {
  /*
    This function gets executed after the Widget is loaded and available in the DOM
  */
  console.log("callback");
}

We'll provide an overview of the properties supported by the configuration object passed to the initCertainlyWidget() function. We'll also explain how to use these properties to customize the behavior and styling of the Certainly Widget.

• Bot configuration object
• General properties
• Style properties

Bot configuration object

The initCertainlyWidget() function allows for behavior customization and styling options. These options need to be passed to the function inside an object.

Below, you'll find a code snippet example representing the options that can be passed on to the initCertainlyWidget() function. The following sections dive deeper into the different properties.

<script src="https://app.certainly.io/sdk/webchat.js"></script>
<script>
initCertainlyWidget(
    {
        id: "1b788f3f-f7c8-4349-a541-3baeef52c391",
        uid: "webbot:f9831fe0-68cc-11ec-b0df-9555fa40ac7d",
        autoloadDelay: 0,
        autoloadScrollOffset: 0,
        debuggerMode: 1,
        webchatKey: "xxx",
        greetingText: "...",
        mode: "clear_past_conversations", // Whether the session should persist upon page reload
        cvars: {
            name: "John Doe",
            email: "jd@email.com"
        },
        voice: {
            voiceEnabled: 1, // Integer. By default, it is 0 (disabled).
            continuous: false, // boolean. By default, it is false (disabled).
            autoSend: 0, // Integer. By default, it is 0 (disabled).
            timeToSend: 1, //Integer
            language: "en-US", // String
            startAutomatically: 0, // Integer. By default, it is 0 (disabled).
            speechEnabled: 0, // Integer. By default, it is 0 (disabled).
        },
        width: 400,
        height: 600,
        buttonLogoOpen: "https://xxx.xx.xxx.png",
        buttonLogoClose: "https://xxx.xx.xxx.png",
        buttonWidth: 56,
        buttonHeight: 56,
        right: 40,
        bottom: 79,
        zIndex: 10030,
        buttonMainColor: "#XXXXXX",
        buttonSecondaryColor: "#XXXXXX",
        buttonColor: "transparent",
        background: "#f5f7fb",
        inputType: "bottom",
        chatMessage: {
            bot: {
                color: "#4F4139",
                buttons: {
                    color: "#4F4139",
                    backgroundColor: "#F9F7F0"
                },
                linkColor: "#BFACA8",
                backgroundColor: "#FFFEF8",
                border: "1px solid #DEDEDE",
                card: {
                    backgroundColor: "#F9F7F0",
                    border: "1px solid #F1EDE3",
                    boxShadow: "none",
                    text: {
                        color: "#4F4139",
                    }
                }
            },
            user: {
                color: "#FFFEF8",
                linkColor: "#80837B",
                backgroundColor: "#4F4139",
            },
            header: {
                boxShadow: "none",
                backgroundColor: "#F9F7F0",
            },
            input: {
                backgroundColor: "blue",
                border: "2px solid red",
            }
        }
    }
);
</script>

General properties

Here, you can find a list of all properties that alter the behavior of the Certainly Widget:

voice

Style properties

Styling can be a crucial part of integrating your chatbot onto your website, as the format, look, and call to action can be essential to attracting traffic.

Below, you'll find a list of properties that alter the look and feel of the Certainly Widget:

chatMessage

initCertainlyWidget(
  { 
   id: "1b788f3f-f7c8-4349-a541-3baeef52c391",
   chatMessage: {
      bot: {
        color: "#4F4139",
        buttons: {
          color: "#4F4139",
          backgroundColor: "#F9F7F0"
        },
        linkColor: "#BFACA8",
        backgroundColor: "#FFFEF8",
        border: "1px solid #DEDEDE",
        card: {
          backgroundColor: "#F9F7F0",
          border: "1px solid #F1EDE3",
          boxShadow: "none",
          text: {
            color: "#4F4139",
          }
        }
      },
      user: {
        color: "#FFFEF8",
        linkColor: "#80837B",
        backgroundColor: "#4F4139",
      },
      header: {
        boxShadow: "none",
        backgroundColor: "#F9F7F0",
      },
      input: { 
        backgroundColor: "blue", 
        border: "2px solid red", 
      }
    }
  }
)

Certainly Web SDK methods

In this section, we will cover the following:

• getUid
• isWidgetHidden
• isWidgetOpen
• widgetStatus
• landedAt
• goTo
• sendMessage
• clearChat
• resetChat
• getCertainlyTransfer
• dataCertainlyTransfer
• sendCvars
• logConversion

getUid

This method returns the unique Certainly visitor ID. This way, users behind login can be linked to specific visitor IDs and resume chats independent of the device they're using. To resume a conversation, refer to the property uId supported by the Certainly configuration object.

certainly.getUid("botDeploymentId", "webchatKey"); 

isWidgetOpen

This method returns a boolean value depending on if the widget is currently opened or closed.

certainly.isWidgetOpen();

isWidgetHidden

This method returns a boolean value depending on if the widget is currently shown or hidden.

certainly.isWidgetHidden();

widgetStatus

Allows for controlling the status of the web widget. 

certainly.widgetStatus(
  {
    action: "open", // Required 
    webchatKey: "1", // Only required if specified in initCertainlyWidget()
  },
  callback //Function (optional)
)

function callback() {
  /*
    This function gets executed after the action on the Widget
  */
  console.log("callback");
}

landedAt

Allows for performing arbitrary actions when the bot lands on a certain conversation module.

certainly.landedAt(
  {
    module: "43651", // Module ID as seen on the Certainly Canvas
    webchatKey: "1", // Only required if specified in initCertainlyWidget()
  },
  callback //Function (required)
)

function callback() {
  /*
    This function gets executed after the bot has landed on the specified module ID
  */
  console.log("callback");
}

goTo

Allows for moving the conversation to an arbitrary module ID and passing CVars to the bot.

certainly.goTo(
  {
    module: "43651", // Required
    webchatKey: "1", // Only required if specified in initCertainlyWidget()
    cvars: { // Pass custom variables to the bot (optional)
      key1: "value1",
      key2: "value2"
    }
  },
  callback //Function (optional)
)

function callback() {
  /*
    This function gets executed after the conversation has been pushed to the specified module ID
  */
  console.log("callback");
}

sendMessage

Allows for sending a message on behalf of either the bot or the visitor.

• On the bot side, it supports sending simple messages, messages with Suggested Replies, multiple messages, and images.
• On the visitor side, only plain text messages are supported. 

Examples

Sending a simple text message on behalf of the bot:

certainly.sendMessage(
  {
    sender: "bot", // Required
    message: "Hello! This is the bot", // Required
    webchatKey: "1", // Only required if specified in initCertainlyWidget()
  }
)

Sending a simple text message on behalf of the bot with Suggested Reply options:

certainly.sendMessage(
  {
    sender: "bot", // Required
    message: {
      text: "Hello", // Required
      options: ["Bien", "Mal"], // Suggested Reply options (optional)
    },
    webchatKey: "1", // Only required if specified in initCertainlyWidget()
  }
)

Sending an image message on behalf of the bot:

certainly.sendMessage(
  {
    sender: "bot", // Required
    message: {
      text: "hello", // Required
      options: ["Bien", "Mal"], // Suggested Reply options (optional)
    },
    webchatKey: "1", // Only required if specified in initCertainlyWidget()
  }
)

Making the bot wait for some time, thus rendering a "bot is typing" animation:

certainly.sendMessage(
  {
    sender: "bot", // Required
    message: {
      type: "wait",
      wait: 2000,
    },
    webchatKey: "1", // Only required if specified in initCertainlyWidget()
  }
)

Sending multiple messages on behalf of the bot:

certainly.sendMessage(
  {
    sender: "bot", // Required
    message: [
      {
        type: "text",
        url: "hello",
      },
      {
        type: "wait",
        url: 2000,
      },
      {
        type: "how are you?",
        url: "hello",
      },
    ],
    webchatKey: "1", // Only required if specified in initCertainlyWidget()
  }
)

Sending a simple text message on behalf of the user:

certainly.sendMessage(
  {
    sender: "user", // Required
    message: "Hello! This is the chat visitor", // Required
    webchatKey: "1", // Only required if specified in initCertainlyWidget()
  }
)

clearChat

Wipes the message bubbles in an existing chat in the Certainly Widget. New visitor messages will result in the conversation resuming from where it left off.

If you're looking to restart the chat, check out the certainly.resetChat() method below:

certainly.clearChat(
  {
    webchatKey: "1", // Only required if specified in initCertainlyWidget()
  }
)

resetChat

Resets the Certainly Widget. The chatbot will again prompt the initial chat message, thus starting a new conversation.

certainly.resetChat(
  {
    webchatKey: "1", // Only required if specified in initCertainlyWidget()
  }
)

getCertainlyTransfer

Compared to certainly.landedAt(), this method allows for accessing CVars associated with the conversation. 

certainly.getCertainlyTransfer({
  actionName: "*",
  webchatKey: "1", // Only required if specified in initCertainlyWidget()
  callback: (data) => callback(data) // The data object contains information such as the latest visitor message and custom variables
});

function callback(data) {
  /*
    This function gets executed after the conversation has arrived at the specified module ID
  */
  console.log(data);
}

dataCertainlyTransfer

Used to send CVars together with actions to perform. 

certainly.dataCertainlyTransfer({ 
  data: { 
    type: "message_bot", 
    message: "This is the content of the simulated message" 
  }, 
  webchatKey: "1", // Only required if specified in initCertainlyWidget()
  openWebchat: true // Whether the chat should stay open after the message is sent 
}); 

sendCvars

This method allows you to send Custom Variables at any point.

certainly.sendCvars({ // Pass custom variables to the bot
  custom_vars: { 
    key1: "value1",
    key2: "value2"
  }, 
  webchatKey: "1", // Only required if specified in initCertainlyWidget()
  openChat: true, // Change to false and the widget won't open after this action
  callback //Function (optional)
}); 

function callback() {
/*
This function gets executed after custom variables are passed to the bot
*/
console.log("callback");
}

logConversion

This method allows you to track an ecommerce conversion and associate it with a Certainly user ID.

certainly.logConversion("Add to cart event")

certainly.logConversion("Add to cart event", "Polo Ralph Lauren Green")

certainly.logConversion("Purchase", "Samsung S22", 500, "EUR")

Certainly Web SDK events

The Web SDK exposes the following set of events:

Each event exposes a detail object containing additional info as to what triggered the event.

window.addEventListener('onWidgetOpened',
  ({ detail }) => {
    console.log("Certainly Widget Opened", detail);
  }
);