Convrs Web Chat API

Settings for the Web Chat widget are typically set within the Convrs UI but sometimes it’s necessary to set certain settings dynamically - this document explains what options are available.

The widget should always be loaded by the script directly and should never be saved directly on your servers. This is to allow the widget to be updated manually via the Convrs UI and automatically by Convrs when changes such as bug fixes and security patches are made to the widget. 

To allow maximum flexibility the settings can be set in two  ways:

  • Within the HTML markup
  • Calling a JS method 

Testing the Widget

The widget is delivered by a world-wide content delivery network and when changes are made to it via the Convrs UI it can take a couple of minutes to be updated on the CDN’s servers. You’ll then need to press CTRL-F5 to flush your local cache and reload the page to see any changes.

When a user engages with the web chat component of the widget, state will be remembered about that user session (for example, history and the language). This can be problematic when testing and to reset the widget, in the text entry field, hold down CTRL and press Z. This will then remove the session data and when you refresh the page a new session will be created.

Method Calls

The Convrs object on the page is always called ConvrsChat and the method Settings is used to change the settings of the Web Chat widget. For example:

ConvrsChat.Settings({"background": "red"})

HTML Markup

As part of the script tag the field data-settings can be set to change the default values as the script loads

<script defer id="convrs-webchat" data-settings='{"background": "red"}' src="..."></script>

As a rule of thumb using the HTML is the better approach unless you need to have dynamic functionality/behaviour.

Available settings

The following settings are available:

z-index: Sets the z-index of the widget, the default value of 30000 is used.  

disabletooltips: When set to true, will disable tool tips for the various channels

background: Sets the background colour of the main icons, the default being #42a5f5

direction: The direction of the widget, accepts two options, “ltr”, (left to right), which is the default and places the widget on the right hand side of the screen. “rtl”  the default being ltr. 

offset: Sets the starting position of the widget relative to the bottom right corner (left corner when the direction is set to “rtl”). 

title:Sets the title bar of the web-chat, default string is “Web Chat”

botavatar: Sets the bot image URL for web-chat. The image should be square in dimensions and should use HTTPS.

lang: Sets the language code for the bot. This sets the channels that are made available. See more detail below.

The Language Code

The language code is typically set via the HTML of the page:

<!doctype html>
<html lang="en">
…
</html>


However, as some pages dynamically change language via user interaction (ie, the lang tag can change) the widget will always dynamically check this tag when rendering the available channels. 

Once a user has engaged the chatbot, the language will stick to for that session. Engagement is classified as the user responding to the chatbot. If the user has not engaged the chat bot and the language has been detected as changed, the the language of the flow will change, even if the webchat is open. This behaviour can also be be forced with the SetLang method. 

To override this behaviour you can explicitly set the language code as part of the settings object, once set, it will not change, even if the html tag on the page changes.

 

Offset Setting

The offset setting required an object in the following form:

{ "horizontal": 20, "vertical": 20}

Where the value is the number of pixels for the offset. The default for both is 10 pixels.

Examples

Setting the widget to have a 50 pixel offset on the vertical and 20 on the horizontal, with tooltips off, with a blue background.


Via HTML:

<script defer id="convrs-webchat" data-settings='{"disabletooltips": true,"background": "blue", "offset": { "horizontal": 20, "vertical": 50} }' src="..."></script>

Via Javascript:

<script>
ConvrsChat.Settings({"disabletooltips": true,"background": "blue", "offset": { "horizontal": 20, "vertical": 50} });
</script>

Convrs Web Chat Method Calls

The Convrs object is always called ConvrsChat and the the following method calls are supported:

Start

This method call is used to start the Widget. Typically this is never needed as the widget is automatically started via the load window event. If the script is loaded dynamically, then this method can be used to start the widget and will automatically display the appropriate content.

ConvrsChat.Start();

ShowWebChat

Show the web chat regardless of toggle value, sets the toggle value to be “show”.

ConvrsChat.ShowWebChat();

HideWebChat

Hide the web chat regardless of toggle value, sets the toggle value to be “hide”.

ConvrsChat.HideWebChat();

DisplayWebChat

Display the web chat based on the current toggle value, it may show or hide the web chat.

ConvrsChat.DisplayWebChat();

ToggleWebChat

Toggle the web chat, and then show/hide the web chat.

ConvrsChat.ToggleWebChat();

SetLang

This method sets the language code and stops checking the html tag for any language changes. See the section about language code for more information.

If the user has not engaged the chatbot and the language has changed then the flow will be restarted in the new language, even if the chat is open.

ConvrsChat.SetLang(“en”);

To force a language change and always restart the flow in the new language you can pass true as an optional parameter:

ConvrsChat.SetLang(“en”,true);

However, this is typically the wrong approach as the user could be talking to an agent and this will in effect kick the user out of the chat with the agent and restart the flow in the new language.

Settings

See above for more information on the available settings.

ConvrsChat.Settings({});


 

Salesforce
In this article