ChatShipper Web Widget

Enabling the widget

The Web Widget integration is used to show a chat window on the website of Organizations. When a consumer (someone visiting the site of the customer, also known as Contact) types a message in the widget for the first time, a new conversation will be created in ChatShipper and queued for the agents and/or bots to pick it up. Enabling the Web Widget for your organization is done in two steps:

Activating the integration

Enabling the Web Widget

The widget is loaded on the configuration page as you can see in the video. This way you can see the changes you made and test the widget by typing a message in it.

Adding the script

All that is needed next is to place the widget on the consumer's website with this little script:

<script defer src="https://cdn.chatshipper.com/widget/bundle.min.js"
  data-chatshipper-appid="paste your app id here">
</script>

You can find your appid in the top right of the widget properties panel.

Adding the script via GTM

When loading the script via Google Tag Manager (GTM) you have to use a slightly different variant:

<script>
  (function(d) {
    var appid='paste your app id here';
    var el = d.createElement('script');
    el.setAttribute('src', 'https://cdn.chatshipper.com/widget/bundle.min.js');
    el.setAttribute('defer', '');
    el.setAttribute('data-chatshipper-appid', appid);
    d.getElementsByTagName('head')[0].appendChild(el);
  })(document);
</script>

This alternative way is needed because GTM removes the data-chatshipper-appid attribute from the script

You will have to ask your customer to add the script to their website. Once the customer has placed the script the web widget will show on their site.

Advanced widget scripts

You can load the widget code in many ways as we will show next.

Passing extra widget options

Normally you would disable the shoutout in the Advanced Config Editor in ChatShipper. But, if for some reason a customer want to overrule any setting of the Web Widget on there website, they can do this by defining an object on the main window and passing it to the widget like this:

<script>
    window.widgetOptions = {
        shoutout: false
    }
</script>
<script defer
    src="https://cdn.chatshipper.com/widget/bundle.min.js"
    data-chatshipper-appid="<your appid should be pasted here>"
    data-chatshipper-options='widgetOptions'>
</script>

You can find your appid in the top right of the widget properties panel.

To make it work in GTM write the second script tag as explained here. Don't forget to add the el.setAttribute('data-chatshipper-options', 'widgetOptions'); to it.

Listen to widget events

<script>
    window.widgetLoaded = function() {
        console.log('widget was loaded and has ' + window.chatshipper.getConversation().messages.length + ' messages');

        window.chatshipper.on('widget:opened', function() {
            console.log('widget:opened: you could send statistics here')
        });

        window.chatshipper.on('widget:closed', function() {
            console.log('widget:closed: you could send statistics here')
        });

        window.chatshipper.on('message:sent', function(message) {
            console.log('message:sent: you could send statistics here', window.chatshipper.getConversation().messages.length)
        });

        window.chatshipper.on('message:received', function(message) {
            console.log('message:received: you could send statistics here')
        });
    }
</script>
<script defer
    src="https://cdn.chatshipper.com/widget/bundle.min.js"
    data-chatshipper-appid="<your appid should be pasted here>"
    data-chatshipper-callback='widgetLoaded'>
</script>

To make it work in GTM write the second script tag as explained here. Don't forget to add the el.setAttribute('data-chatshipper-callback', 'widgetLoaded'); to it.

Script attributes

Embedded Attribute

<script defer
    src="https://cdn.chatshipper.com/widget/bundle.min.js"
    data-chatshipper-appid="<your appid should be pasted here>"
    data-chatshipper-embedded='elementid'>
</script>

Will start the widget in embedded mode on the DOM element with id 'elementid'

Bot Attribute

<script defer
    src="https://cdn.chatshipper.com/widget/bundle.min.js"
    data-chatshipper-appid="<your appid should be pasted here>"
    data-chatshipper-nosound="true"
    data-chatshipper-bot='botname'>
</script>

Will start the widget, open it immidiately and start the bot named botname

important We have to add the data-chatshipper-nosound="true" attribute when autostarting bot as otherwise we get soun play error of the browser, because there was no interaction with the client yet. Sound are not allowed before that .

DOM element examples

Opening the widget

Adding the data-chatshipper-open attribute to any dom element on the website where the widget is active, will open the widget

<button data-chatshipper-open="">Open the widget</button>

Opening the widget fullscreen

<!doctype html>
<html>
    <head>
        <title>fullscreen</title>
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <meta http-equiv="X-UA-Compatible" content="ie=edge">
        <script
            defer
            src="https://cdn.chatshipper.com/widget/bundle.min.js"
            data-chatshipper-appid="5e16007a4c80460010c2717c"
            data-chatshipper-embedded="fullscreen"
            data-chatshipper-nosound="true"></script>
        <style>
          #fullscreen {
            position: absolute;
            top: 0px;
            left: 0px;
            width: 100%;
            height: 100%;
          }
        </style>
    </head>
    <body>
      <div id="fullscreen"></div>
    </body>
</html>

We use the embedded mode of the widget to load it inside the div element named fullscreen, and style it with css to be fullscreen.

<a href="http://www.google.com" data-chatshipper-open="" data-chatshipper-preventdefault="true">Open the widget</a>

Adding the data-chatshipper-preventdefault= will stop the default link behaviour of going to the website defined in the href attribute.

Bot examples

At the moment only botmock bots are described here, but in the near future all bots will have this functionality.

Opening the widget and starting a bot

Adding the data-chatshipper-bot="botname" attribute to any dom element on the website where the widget is active, will open the widget and start that bot.

<button data-chatshipper-bot="helloworld">Start the bot</button>

Will open the widget and start the helloworld bot if it is configured in the organization.

Send text to the bot

Adding the data-chatshipper-bot=">cs botname reset text to send" attribute to any dom element on the website where the widget is active, will open the widget and start that bot and send text to send as the first line the bot should process.

<button data-chatshipper-bot=">cs helloworld reset hello mister">Start the bot</button>

Will open the widget and start the helloworld bot, sending hello mister to it as the first message.

Adding metadata on the bot

Adding the data-chatshipper-bot=">cs botname reset meta=key1:value,key2:value" attribute to any dom element on the website where the widget is active, will open the widget and start that bot but only after setting the meta keys key` and key2 on the conversation. Those can be used inside the bot to make decisions.

<button data-chatshipper-bot=">cs helloworld reset meta=key1:value,key2:value">Start the bot</button>

Let's have a look at all the ways the widget can be configured next.