The chat widget can have its colours customised from the portal and operates as a black box solution in isolation on your web page.

The widget looks like this:

Configure web chat

Learn how to set up web chat in the Get started guide .

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 automatically creates a unique profile ID for each customer who visits your website and allows them to communicate with you through the web chat widget.

All you need to do to use this mode is to copy the widget’s code snippet from the Web Chat configuration screen’s Usage tab into your website. The code snippet is needed on each page you want the chat widget on, and usually it is simply added to the master page template so it exists on all pages.

Authenticated mode

Authenticated mode initiates a callback to your code for you to provide a JWT that identifies the user on the website. Typically, this mode is 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 system’s, for example, shared secret or nonce.

<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>

Log the widget out

If you have the concept of logging out of your website and need the chat widget to clear cached settings so that a different user can use the widget on next login, 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 waits for five seconds before it launches. If you want to change this, you can specify a different timeout value, in milliseconds, in the comapiConfig object. The name of this property is launchTimeout.

The following config removes the timeout:

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

Override data storage

The web chat widget stores a small amount of context data on the client’s browser using HTML5 local storage mechanism, so it can maintain a consistent profile ID between website visits and restore the user’s messaging history.

It’s possible to override where this context data is stored by passing in storage method overrides in the chat widget’s 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 web chat 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"
  }
}

Example

<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 through some interfaces attached to the window object of the page you added the widget to. The API methods are designed to allow deeper integration and automation with the web chat widget, including updating profile information for the widget’s active user.

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

Profile

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

getProfile

Function to get the current web chat widget user's profile. Returns a promise with either the profile object for the user, or an 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 - or patch - the user's profile. The profile is merged with the properties passed in. Any other properties remain unchanged.

Name	Type	Description
data	object	Data to patch the profile with.

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 web chat widget user's profile. The profile is replaced with the properties passed in. Any previous properties are removed.

Name	Type	Description
profile	object	The profile to update.

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

Name	Type	Description
packageName	string	The Android package name of your Cordova app.
registrationId	string	The push registration ID.

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.

Name	Type	Description
bundleId	string	the iOS bundleId of your cordova app
environment	number	the environment (development = 0, production = 1)
token	string	the device token

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);
    });