In this article, we'll explain how to go live using the Certainly Widget, which is an easy way to integrate your chatbot.
We'll provide an overview of the properties supported by the configuration object passed to the initCertainlyWidget() function. Additionally, we'll address how to use these properties to customize both the styling and the behavior of the Certainly Widget.
Below, we cover:
- How to implement the Certainly Widget
- All properties supported by the initCertainlyWidget() function
- How to customize the behavior of the Certainly Widget
- How to style the Certainly Widget
How to implement the Certainly Widget
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.
Luckily, this process is simple! Just copy the following code snippet and paste it into the HTML code of your website at the end of the "body" element (before the </body> tag).
Make sure to substitute the bot ID inside the initCertainlyWidget() function with your bot ID. Then, if you copy the snippet from your bot builder interface, it will already include the ID of your bot.
To find the bot deployment ID, open Bot Settings from the right sidebar menu, then navigate to Channels > Certainly Widget and locate "id" in the widget script. Please note that the bot ID links this script to your bot, so it is necessary for it to function.
All properties supported by the initCertainlyWidget() function
The initCertainlyWidget() function allows for behavior customization and styling options. These options need to be passed to the function inside an object.
Below, you will find an example of a code snippet representing the various options that can be passed on to the initCertainlyWidget() function. In the following sections, we'll dive deeper into the different properties.
How to customize the behavior of the Certainly Widget
Here, you can find a list of all properties that alter the behavior of the Certainly Widget:
id
(required)
The deployment ID of your chatbots links the script specifically to your bot.
The value may also include some referrer ID as a URL parameter, which will take the bot to launch the conversation on that specific Module. For help finding your bot's deployment ID, see the instructions in the first section above.
uid
(optional)
Identifies an existing Certainly conversation.
If specified, Certainly will resume the existing conversation instead of starting a new session. It can be used to sync user sessions behind login. You can retrieve the uId through the certainly.getUid() method.
autoload
(optional)
Autoload allows your bot to automatically pop up after a set amount of time has passed, or after a specific amount of pixels scrolled.
This can also be configured directly from the bot-building canvas. Open Bot Settings from the right sidebar menu, then navigate to Channels > Certainly Widget > Autoloading.
debuggerMode
(optional)
This boolean parameter can be used to display the debugger alongside the chat, which is especially useful during development. Setting the property to 1 will display the debugger and 0 will hide it.
webchatKey
(optional)
The webchatKey is useful when you deploy multiple webchats on the same webpage. This property identifies each chat instance.
greetingText
(optional)
Whatever value you add to this parameter will appear as a greeting text in the webchat.
mode
(optional)
When this property is set to the value "clear_past_conversations", any page reload will result in the chat starting from scratch.
cvars
(optional)
The initCertainlyWidget() function allows you to pass any Custom Variables you may need during the conversation from the website to the bot. Custom Variables passed to the initCertainlyWidget() function can be used throughout a conversation.
The object only supports strings as values. Anything else will be stringified. You can pass as many Custom Variables as the bot requires.
ref
(optional)
This stands for referral. It is possible to pass a Module ID of the bot as a value. When that is the case, the Module ID passed as ref will override the default starting Module of the chatbot, as defined in the Certainly Platform. The Module number can be found in the top left side corner of a Module.
voice
(optional)
As of October 20th, 2020, the Certainly Widget supports voice control. Certainly Voice leverages the browser built-in text-to-speech* and speech-to-text** functionalities.
* See the browser compatibility for text-to-speech
** See the browser compatibility for speech-to-text
| Property | Description |
| voiceEnabled (bool) |
Shows the microphone option in the Certainly Widget. |
| continuous (bool) |
Controls whether text-to-speech remains active when the visitor stops speaking (true) or not (false). If false, and autosend is enabled, then the bot will stop hearing and process the visitor voice immediately. |
| autoSend (bool) |
Controls whether the bot will send the transcribed text immediately (true) or wait for the visitor to send it (false). |
| timeToSend (int) |
If continuous and autoSend are set to true, this property controls the time (in seconds) the bot will wait between when the visitor stops speaking and the message is sent. |
| language (str) |
Controls the language locale used by the bot. It is related to speechEnabled. |
| startAutomatically (bool) |
Controls whether the bot will activate listening mode automatically each time it replies to the visitor. |
| speechEnabled (bool) |
(BETA) Activates the text-to-speech function of the bot, which is used to narrate the chat. If set to true, it uses the locale specified in language. |
How to style the Certainly Widget
Styling is a crucial part of integrating your chatbot onto your website, as the format, look, and call to action can be essential to attracting traffic to your bot. Below, you'll find a list of properties that alter the look and feel of the Certainly Widget:
- width
- height
- buttonLogoOpen
- buttonLogoClose
- buttonWidth
- buttonHeight
- right
- bottom
- zIndex
- buttonColor
- background
- chatMessage
width
(optional)
The width of the webchat window, measured in pixels. Make sure width is set in accordance with height to keep the desired ratio.
height
(optional)
The height of the webchat window, measured in pixels.
buttonLogoOpen
(optional)
The image displayed as the widget button when the webchat window is closed. This allows you to change the standard chatbot widget icon with something you have customized. Note that the property name "buttonLogoOpen" represents the button you need to click in order to open the widget, not its current state.
Media files must be hosted online. If you'd like the same image displayed when the chat is closed and open, you'll need to insert that image for both buttonLogoOpen and buttonLogoClose.
buttonLogoClose
(optional)
The image displayed as the widget button when the webchat window is open. Note that the property name "buttonLogoClose" represents the button you need to click in order to close the widget, not its current state.
Media files must be hosted online. If you'd like the same image displayed when the chat is open and closed, you'll need to insert that image for both buttonLogoClose and buttonLogoOpen.
buttonWidth
(optional)
The width of the webchat button, measured in pixels. Make sure width is set in accordance with height to keep the desired ratio.
buttonHeight
(optional)
The height of the webchat button, measured in pixels.
right
(optional)
The distance of the widget button in respect to the right side margin of the browser window, measured in pixels.
bottom
(optional)
The distance of the widget button in respect to the bottom side margin of the browser window, measured in pixels.
zIndex
(optional)
The z-index specifies the stack order. The greater the stack order, the further to the front the Certainly Widget will be in relation to other elements on the webpage.
buttonColor
(optional)
You can customize the color of the widget button through multiple parameters. The color values must be indicated as Hex values.
Make sure you are setting these parameters only if you use the default buttonLogoOpen and buttonLogoClose icons. If you are using a custom image as a button, then that image will take priority over your color settings.
background
(optional)
Hex color for the background color of the entire webchat widget. You can set this value to "transparent" or a color code such as "#FF004F".
chatMessage
The Certainly webchat colors can also be customized in order to align the widget with your brand identity and website style. This can be done through the chatMessage object. Inside this object, you can find four other objects that contain the styling options.
| Property | Description |
| bot (obj) |
(optional) For messages sent by the bot, this object allows you to modify the:
|
| user (obj) |
(optional) For messages sent by the user, this object allows you to modify the color of message bubbles, text, and links. |
| header (obj) |
(optional) This object allows you to modify the background color and box shadows of the webchat header. |
| input (obj) |
(optional) This object allows you to modify the background color and border of the input field. |
Looking for something not addressed here? Just reach out to our Customer Success team!