Web Chat Widget

You can add a pre-built chat widget to your websites with ease which will give you an out of the box solution for customer chat using only a few lines of code included in each of your web sites pages. The widget can have its colours customised from the Comapi portal and operates as a black box solution in isolation in your web page. The widget looks like this:

Configuring Web Chat

See the Webchat get started guide for details of how to configure and embed the Web Chat widget.

Authentication

The web chat widget can be run in two modes:

• Anonymous - The widget creates a unique anonymous profile for each customer so that you can chat with your customers even if they haven't signed in or registered
• Authenticated - The widget calls back to your system in order to identify who it is representing.

Anonymous mode

Anonymous mode will automatically create a unique profile id for each customer who visits your website and allow them to communicate with you via the web chat widget with ease. All you need to do to use this mode is to copy the widget code snippet from the Web Chat configuration screens Usage tab into your web site. The code snippet will be needed on each page you want the web chat widget on, and usually it is simply added to the master page template so it exists on all pages.

Authenticated mode

Authenticated mode will callback to your code for you to provide a JWT that identifies the user on the website. Typically this mode would be used when the chat widget is used with a web site that supports signing in, so that the identity used by web chat matches the logged in user. If your website already uses JWTs then these can be reused with the web chat widget as long as you configure the App Messaging security settings to match your systems e.g. shared secret, nonce etc...

<script>
    var comapiConfig = {
         apiSpace: '{Your API Space Id}',
         urlBase: 'https://api.comapi.com' 
    };
    (function(d, s, id){
        var js, cjs = d.getElementsByTagName(s)[0];
        if (d.getElementById(id)) {return;}
        js = d.createElement(s); js.id = id;
        js.src = '//cdn.dnky.co/widget/bootstrap.js';
        cjs.parentNode.insertBefore(js, cjs);
    }(document, 'script', 'comapi-widget'));
</script>

<script>
    var comapiConfig = {
         apiSpace: '{Your API Space Id}',
         urlBase: 'https://api.comapi.com',
         authCallback: function (nonce, answerAuthenticationChallenge){
            // TODO: generate a JWT and return 
            var jwt = ''; 
            answerAuthenticationChallenge(jwt); 
        } 
    };
    (function(d, s, id){
        var js, cjs = d.getElementsByTagName(s)[0];
        if (d.getElementById(id)) {return;}
        js = d.createElement(s); js.id = id;
        js.src = '//cdn.dnky.co/widget/bootstrap.js';
        cjs.parentNode.insertBefore(js, cjs);
    }(document, 'script', 'comapi-widget'));
</script>

Logging the widget out

If you have the concept of logging out of your website and need the chat widget to clear it cached settings so that a different user can use the widget on next login then please add the following JavaScript snippet to your log out client code:

// Tell the Comapi chat widget to unload itself
if (window.COMAPI_WIDGET_UNLOAD) {
	window.COMAPI_WIDGET_UNLOAD();
}

Advanced Options

Launch Timeout

By default the widget will wait for 5 seconds before it launches. If you want to change this behaviour,
you can specify a different timeout value (in milliseconds) in the comapiConfig object. The name of this property is launchTimeout.

The following config will remove the timeout

var comapiConfig = {
  apiSpace: '{Your API Space Id}',
  launchTimeout: 0
};

Overriding Data Storage

The Webchat widget stores a small amount of context data on the clients browser using HTML 5 local storage mechanism, so it can maintain a consistent profile id between website visits and restore the users messaging history.

It is possible to override where this context data is stored by passing in storage method overrides in the chat widgets config. Reasons to do this include using alternate persistence mechanisms, or to change the widget to use session storage so each visit to a website starts a new user and therefore clears message history.

To override the storage methods for the Webchat widget pass the following object in the configuration for the widget:

storage: {
    removeItem: function(key){
       // The code to remove an item from storage using the "key"
  },
    getItem: function(key){
       // The code to retrieve an item from storage using the "key"
  },
    setItem: function(key, value){
       // The code to store an item in storage using the "key" and "value"
  }
}

e.g.

<script>
   window.comapiConfig = {
       apiSpace: 'fa24cf6e-4352-4b26-a71a-c3032bea7a01',
     	 storage: {
                removeItem: function(key){
                    return sessionStorage.removeItem(key);
                },
                getItem: function(key){
                    return sessionStorage.getItem(key);
                },
                setItem: function(key, value){
                    sessionStorage.setItem(key, value);
                }
            }
   };
   (function(d, s, id){
       var js, cjs = d.getElementsByTagName(s)[0];
       if (d.getElementById(id)) {return;}
       js = d.createElement(s); js.id = id;
       js.src = '//cdn.dnky.co/widget/bootstrap.js';
       cjs.parentNode.insertBefore(js, cjs);
   }(document, 'script', 'comapi-widget'));
</script>

Widget API

The widget exposes an API via some interfaces attached to the window object of the page you added the webchat widget to. The API methods are designed to allow deeper integration and automation with the webchat widget, including updating profile information for the webchat widgets active user.

All interfaces for the webchat widget API hang off window.COMAPI_WIDGET_API and are:

profile

The profile interface provides access to profile functionality for reading and updating the profile associated with the webchat widget.

getProfile

Function to get the current webchat widget user's profile.

Returns a promise with either the profile object for the user or a error object if it fails.

window.COMAPI_WIDGET_API.profile.getProfile()
    .then(function (profile) {
        console.log("getProfile() succeeded", profile);
    })
    .catch(function (error) {
        console.error("getProfile() failed", error);
    });

patchProfile

Function to update (patch) the user's profile. The profile will be merged (patched) with the properties passed in. Any other properties will remain unchanged.

Returns a promise with the updated profile object if successful, or an error object if an error occurs.

window.COMAPI_WIDGET_API.profile.patchProfile(data)
    .then(function (updatedProfile) {
        console.error("patchProfile() succeeded", updatedProfile);
    })
    .catch(function (error) {
        console.error("patchProfile() failed", error);
    });

updateProfile

Function to update the current webchat widget user's profile. The profile will be replaced with the properties passed in. Any previous properties will be removed!

Returns a promise with the updated profile object if successful, or an error object if an error occurs.

window.COMAPI_WIDGET_API.profile.updateProfile(profile)
    .then(function (updatedProfile) {
        console.error("updateProfile() succeeded", updatedProfile);
    })
    .catch(function (error) {
        console.error("updateProfile() failed", error);
    });

device

The device interface provides access to some device functionality, which is largely utilised with Cordova apps:

setFCMPushDetails (packageName, registrationId)

Function to set FCM push details for the current session

Returns a promise indicating whether the call was successful or not.

window.COMAPI_WIDGET_API.device.setFCMPushDetails(packageName, registrationId)
    .then(function (result) {
        console.error("setFCMPushDetails() succeeded", result);
    })
    .catch(function (error) {
        console.error("setFCMPushDetails() failed", error);
    });

setAPNSPushDetails

Function to set APNS push details for the current session

Returns a promise indicating whether the call was successful or not.

window.COMAPI_WIDGET_API.device.setAPNSPushDetails(details)
    .then(function (result) {
        console.error("setAPNSPushDetails() succeeded", result);
    })
    .catch(function (error) {
        console.error("setAPNSPushDetails() failed", error);
    });

removePushDetails

Function to remove push details for the current session

Returns a promise indicating whether the call was successful or not.

window.COMAPI_WIDGET_API.device.removePushDetails()
    .then(function (result) {
        console.error("removePushDetails() succeeded", result);
    })
    .catch(function (error) {
        console.error("removePushDetails() failed", error);
    });

widget

The widget interface allows you to programmatically show or hide the widget:

show

window.COMAPI_WIDGET_API.widget.show();

hide

window.COMAPI_WIDGET_API.widget.hide();

session

The session interface allows you access the current widgets session:

Returns a promise with the session info if successful or an error object if the call failed.

getSessionInfo

window.COMAPI_WIDGET_API.session.getSessionInfo()
    .then(function (sessionInfo) {
        console.error("getSessionInfo() succeeded", sessionInfo);
    })
    .catch(function (error) {
        console.error("removePushDetails() failed", error);
    });