JS API

Introduction

Webstores that use ROBIN need to place the ROBIN script on the site(s). This is done by placing a URL on all pages the website contains. The script that needs to be placed can be obtained in ROBIN by navigating to settings / contact tab. This script is of the form:


<script src="https://selfservice.robinhq.com/external/robin/<apikey>.js" async="async"></script>
	

Where <apikey> is replaced by the apikey of the subscription. When this script is placed, all pages a shopper visits shows a tab. All behavior (labels, content, color and position) of the tab can be configured in the ROBIN app . However, sometimes specific functionality is required on the page. When this is the case, the ROBIN javascript API can be used.

Override default behavior

When the ROBIN script is loaded, it checks for the existence of a property named robin_settings on the current page (window scope). When such a property exists, its values are combined with the properties of the values that are configured in the ROBIN app. All properties that exist in the robin_settings object have a higher priority, hence the configured properties can be overruled. So, for instance it is possible to hide a tab on a specific page. The following recommended properties are supported:

Overview of overridable options

Name Description Possible values
tab_theme, mobile_tab_theme The theme of the tab (on a mobile site) light, dark, grey, blue, red
tab_style, mobile_tab_style The style of the tab (on a mobile site) single-tab, channel-tab, floating-tab
tab_position, mobile_tab_position The position of the tab (on a mobile site) right, left, bottom-right, bottom-left
hide_tab, mobile_hide_tab Indicates whether a tab should be hidden (on a mobile site). This is a separate property and not combined with position like the ROBIN app configuration. It is possible to have a hidden tab and let the position property specify where the dialog is positioned in case it is requested manually. true, false. The default value depends on configured position
animateTab Indicates whether the tab appears animated when appropriate. true (default), false
animatePopups Indicates whether pro active chat (PAC) dialogs appear animated when appropriate. true (default), false
tabAnimationDelayInSecondse The number of seconds before the tab appears, only relevant when shown animated. an integer, default is 2
tabAnimationDurationInSeconds The number of seconds the animation of the tab lasts, only relevant when shown animated. an integer, default is 1

Events

When the ROBIN script is loaded, the init-method is called automatically. This script initializes the tab according to settings specified in the ROBIN app (and possibly overruled by specifying a robin_settings object). The init-method also invokes events when can be specified in the robin_settings objects object. Using these events, additional steps can be performed. An example of such a step is display information regarding online employees. Specifying an event handler is done by defining it in the robin_settings object object as follows:


robin_settings = {
	callback: function(event, data){
		if (event == 'init'){
			// specify initialization code here
		}
	}
}

Retrieve information

When the ROBIN script is loaded, or when the callback method is invoked, it is possible to access methods available on the ROBIN javascript API. Methods that retrieve information, are the following:

Retrieval methods

Property Description Possible values Value description
getOnlineStatus() Returns a boolean indicating whether a user is online on the current page (so a chat is possible)
getAllUsers() Returns an array of all users that are available on one of the webstores that are available in this subscriptions. This list does include users that are not assigned to the webstore that is assigned to the URL this request originates from, but does not include users that are not assigned to any webstore at all. Every user object has the following properties: avatar The avatar that is uploaded in the ROBIN app
avatar20
avatar36
avatar128
email The email address of this user
firstName The first name of this user
lastName The last name of this user
name The first name and last name of this user combined
function The function of this user
presence The presence of this user (can be 'online', 'offline' or 'servicehours')
actualPresence The actual presence of this user, can be 'online' or 'offline' taking into account whether the current webstore is currently open.
getWebStoreUsers() Returns an array containing all users that are assigned to the webstore the page the request originates from belongs to. The properties of every user object are the same as described above
getUserByEmail(email) Returns a user that has the email address specified, or null when it does not exist.
getWebStore() Returns a webstore object containing properties of the web store the page the request originates from. Such a webStore object has all properties that are assigned in the ROBIN app: name
language
defaultStore
addressOne
addressTwo
phoneNumber
contactTabTemplate
conversationTemplate
serviceHoursTemplate
proActiveChatTemplate
personalTemplate
users
referrers

Invoke methods

When a custom tab is required on a page, it is possible to create an HTML element instead of the ROBIN tab (make sure to hide the ROBIN tab using robin_settings.hide_tab = true). The click event on the HTML element needs to activate the ROBIN contact form. This and other things can be done by invoking methods on the ROBIN javascript API. The Supported methods are the following:

Invoke methods overview

Property Description
show(channel) Activates the ROBIN contact form using the specified channel ('contact_form', 'chat' or 'phone'). When channel is undefined, the channel is determined depending on the online status of the webstore.
hide() Hides the ROBIN contact form.
setShopper(emailAddress, name) Identify a user on a page, when this method is invoked, ROBIN shows the name and email address specified in the contact form when it is shown. When anonymous chat is enabled, the name and email address are sent when a conversation is started, so the information becomes available to the agent that handles the conversation.
chat(emailAddress) Starts a chat conversation with a specific agent identified by emailAddress. When the agent is not online, an offline conversation is started with that agent (making the specific agent more important than the online status). This feature is known as personal routing.
reset() ROBIN uses session cookies that identify current channel, current agent, shopper data etc. Using the reset method, all session cookies are deleted, making it a fresh (first) visit to the page after a refresh.

Examples

Behavior can be changed to modify properties. There are a lot of properties to be changed, it is recommended to set a breakpoint and examine the webstore object that is retrieved and look for the property that needs to be changed.

Autofill customers information

Using the following code it is possible to specify the shopper name and email address in case he is logged in, and making the conversation ‘anonymous’ (so the shopper does not have to enter his name).


var robin_settings = {
	callback: function(event, data) {
		if (event == 'init'){
			var name = 'name';		// determine real name
			var email = 'name@cm.com';	// determine real email

			if (email != null && email != '') {
				var ws = __robin.getWebStore();
				ws.conversationTemplate.useAnonymousChat = true;
				__robin.setShopper(email, name);
			}
		}
	}
};	
						

Get the list of online user

If you want to create your own tab with online presence from the right agents, you can use the example below.


var robin_settings = {
    callback: function(event, data) {
        if (event == 'init') {
            var onlineUsers = [];
            var users = __robin.getWebStoreUsers();
            for (var i = 0; i < users.length; i++) {
                if (users[i].actualPresence == 'online') {
                    onlineUsers.push(users[i]);
                }
            }
            if (onlineUsers.length >= 1) {
                var d = document.getElementById("robin_tab");
                d.className += " robin-online";
            }

        }
    }
};
						

Disable Google Analytics

If you don't want to receive the Google Analytics events from our widget, you can use the following script.


var robin_settings = {
    callback: function(event, data) {
        if (event == 'init') {
            var oldtracker = ga.getAll()[0];
            var tracker = {
                set: function(a, b) {
                    oldtracker.set(a, b);
                },
                send: function(a, b, c, d) {
                    if (b !== 'ROBIN-PAGES' && b !== 'ROBIN-TAB') {
                        oldtracker.send(a, b, c, d);
                    }
                }
            };
            ga.getAll = function() {
                return [
                    tracker
                ];
            }
        }
    }
};
						

Viewed Products

Introduction

With the ‘viewed product functionality’, it is possible to gain insight into all products viewed by the customer and the contents of the shopping cart. This is possible with a method that is loading the products in the conversation and display the cart in the panel. If you use this method, you are not dependent on a page load.

Viewed products

To register a viewed product, the following method should be used.


__robin.addViewedProduct(viewedProduct)
						
						

Properties

Name Description
id Product Id or code
name Name of the product
url The URL of the product
imageURL The URL of the image of product
price The price of the product
currency The currency of the product price
availabilty Stock description

Example


__robin.addViewedProduct({
	id: "p1",
	name: "prod 1",
	description: "product 1",
	url: "http://robinhq.com/",
	imageUrl: "https://robinhq.nl/img/home/robin-quickscan.png",
	price: "1.23",
	currency: "€",
	availability: "Available"
});		
				
						

Shopping cart

To publish the complete contents of the shopping cart, the following method should be used. It is important to keep the update the all shopping cart contents and not just the mutations.


__robin.setCartContents(cart)
						
						

Properties

Name Description
id Product Id or code
name Name of the product
quantity The quantity of the product that are placed in the cart
unitPrice The price of the product
currency The currency of the product price

Example


__robin.setCartContents ([
	{
		id: "p1",
		name: "prod 1",
		quantity: "1",
		unitPrice: "1.23",
		currency: "€"
	},
	{
		id: "p2",
		name: "prod 2",
		quantity: "2",
		unitPrice: "4.56",
		currency: "€"
	}
]);