Codemonkey's Conversational Web SDK

This article covers the definition and examples of all the different functionalities provided by Codemonkey Conversational Web SDK. This JavaScript-based SDK allows you to customize the web deployment of your Codemonkey bots and design powerful interactions between the website and the widget. You can use the SDK in any environment that supports JavaScript. 

Below, we will address:

Take a look at our nontechnical explanation of Codemonkey's Conversational Web SDK if needed.

Codemonkey Widget initialization

initCodemonkeyWidget() is responsible for initiating the Codemonkey Widget. It supports two arguments:

  • Codemonkey configuration object (required)
  • A callback function (optional)
initCodemonkeyWidget(
	{
		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");
}

For a complete reference of all properties supported by the initCodemonkeyWidget() function, please refer to our article on the configuration of the Codemonkey Widget.

Please note that to access Custom Variables associated with the bot, the following option needs to be enabled in Bot Settings:

enablewebsdk.jpg

Codemonkey Web SDK methods

In this section, we will cover the following:

getUid

This method returns the unique Codemonkey visitor ID. This way, visitors behind login can be linked to specific visitor IDs and can thus resume conversations independent of the device they are using. To resume a conversation, please refer to the property uId supported by the Codemonkey configuration object

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

 

Property Description
botDeploymentId (str)

The id property identifying the bot instance as specified in the initCodemonkeyWidget() function.

webchatKey (str) Unique Identifier for the webchat widget. You may have several widgets on your site, and it is necessary to link this action to one of them.

widgetStatus

Allows for controlling the status of the web widget. Supported action properties: open, close, show, hide.

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

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

 

Property Description
action (str)

What action to take on the Codemonkey Widget. Supported values are: "open", "close", "show" and "hide".

webchatKey (str) Unique Identifier for the webchat widget. You may have several widgets on your site, and it is necessary to link this action to one of them.

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 Codemonkey Canvas
    webchatKey: "1", // Only required if specified in initCodemonkeyWidget()
  },
  callback //Function (required)
)

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

 

Property Description
module (str|arr)

The module(s) that should trigger this method execution. Supported values are:

  • A single module ID, e.g. "12345"(str)
  • A list of module IDs, e.g. ["12345", "54321"](arr)
  • A wildcard character *, to catch all modules IDs (str)
webchatKey (str) Unique Identifier for the webchat widget. You may have several widgets on your site, and it is necessary to link this action to one of them.

goTo

Allows for moving the conversation to an arbitrary module ID and passing Custom Variables* to the bot.

certainly.goTo(
  {
    module: "43651", // Required
    webchatKey: "1", // Only required if specified in initCodemonkeyWidget()
    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");
}

 

Property Description
module (str) The module ID the bot should go to. 
cvars (obj) Optional. It is a plain object containing Custom Variables to be passed to the bot.
webchatKey (str) Unique Identifier for the widget instance. You may have several widget instances on your site, and it is necessary to link this action to one of them.

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 initCodemonkeyWidget()
  }
)

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 initCodemonkeyWidget()
  }
)

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 initCodemonkeyWidget()
  }
)

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 initCodemonkeyWidget()
  }
)

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 initCodemonkeyWidget()
  }
)

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 initCodemonkeyWidget()
  }
)

clearChat

Wipes the message bubbles in an existing chat in the Codemonkey Widget. New messages from the visitor will result in the conversation resuming from where it left. If you're looking to restart the chat, check out the certainly.resetChat() method below:

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

 

Property Description
webchatKey (str) Unique Identifier for the webchat widget. You may have several widgets on your site, and it is necessary to link this action to one of them.

resetChat

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

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

 

Property Description
webchatKey (str) Unique Identifier for the webchat widget. You may have several widgets on your site, and it is necessary to link this action to one of them.

getCodemonkeyTransfer

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

certainly.getCodemonkeyTransfer({
  actionName: "*",
  webchatKey: "1", // Only required if specified in initCodemonkeyWidget()
  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);
}

 

Property Description

actionName

(str | arr)

The module(s) that should trigger this method execution. Supported values:

  • A single module ID, e.g. "12345"(str)
  • A list of module IDs, e.g. ["12345", "54321"](arr)
  • A wildcard character *, to catch all modules IDs (str)

webchatKey

(str)

Unique Identifier for the webchat widget. You may have several widgets on your site, and it is necessary to link this action to one of them.

dataCodemonkeyTransfer

Used to send Custom Variables* together with actions to perform. 

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

 

Property Description
data (obj) The information sent to the Codemonkey Widget.
type (str)

The action to be taken by the widget. Supported values are "message_bot" and "go_to_module".

message (str) Required if type is set to message_bot. Property message refers to the text being printed by the bot. 
mod_id (int) Required if type is set to "go_to_module". Property mod_id refers to the module ID the bot should go to. 
cvars (obj) Optional. It is a plain object containing Custom Variables to be passed to the bot.
webchatKey (str) Unique Identifier for the widget instance. You may have several widget instances on your site, and it is necessary to link this action to one of them.
openWebChat (bool) Controls whether the Codemonkey Widget will stay open (or closed) after the action has been executed.

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" }, openChat: true // Change to false and the widget won't open after this action });

 

Property Description
custom_vars (obj) It is a plain object containing Custom Variables to be passed to the bot.
openChat (bool) Controls whether the Codemonkey Widget will stay open (or closed) after the action has been executed.

 

Was this article helpful?

0 out of 0 found this helpful
Have more questions? Submit a request

Comments (0 comments)

Please sign in to leave a comment.