Thousands of businesses rely on Hipmob to keep their customers happy. See some here.

Hipmob For HTML5 and the Web


Overview

Hipmob provides hosted live chat for mobile applications. You sign up with us, we give you a code, you download our library, you integrate it into your app, and you can then talk to your users, figure out what they want and what problems they are having, and make them happy. No servers, no extra steps or code to write, wherever the users are, you get to focus on what you do well. This document covers integrating the Hipmob experience into your website or HTML5-based mobile app.

5-minute integration

The easiest way to see it working is with our instant chat page: register for an account at https://manage.hipmob.com (if you don't already have an account), get your application ID (you can copy it from https://manage.hipmob.com/livechat/) and then pass it as a parameter to our instant chat page at https://hipmob.s3.amazonaws.com/chat.html?app=<application ID>. To see it in action right now (and talk to us!) visit https://hipmob.s3.amazonaws.com/chat.html?app=2ea7d86854df4ca185af84e68ea72fe1.
To test it out with your own Hipmob application ID, use the form below:
 
To integrate Hipmob into your own web page, read on.
  1. Register for an account at https://manage.hipmob.com/ (if you haven't already done so). Once you register a Hipmob application entry will be created for you and an application ID will be generated. Remember this application ID: you'll use it later.
  2. Add the Hipmob Javascript snippet to your page:
    			<script type="text/javascript">
    			var _hmc = _hmc || [];
    			_hmc.push(['app', '<application ID>']);
    			(function() {
    			var hm = document.createElement('script'); hm.type = 'text/javascript';
    			hm.async = true;
    			hm.src = 'https://hipmob.s3.amazonaws.com/hipmobchat.min.js';
    			var b = document.getElementsByTagName('script')[0]; b.parentNode.insertBefore(hm, b);
    			})();
    			</script>
    		      
  3. And you're done. A tab will appear in the lower right corner of the browser window: clicking the tab will open the chat window.
To chat with a user, you will need to log into your Hipmob XMPP account using your username and password from step 1 above.
Once you are logged in, ensure that your status is set to Available (we don't send any messages to administrators marked as Away).
Now open the chat window in your browser, and type something. It should pop up in your XMPP client! Go ahead and reply in your XMPP client. It should show up in the browser!

Compatibility

The Hipmob library is compatible with a wide range of desktop and mobile browsers. It uses progressive enhancement, using Websockets where available and falling back to standard HTTP requests when necessary. Tested/supported browsers include:
  • Google Chrome: 6.0 or higher.
  • Mozilla Firefox: 5.0 or higher.
  • Internet Explorer: 7, 8, 9
  • Opera: 10.5, 11.0, 11.5, 11.6
  • Mac OSX Safari: 5.05, 5.1
  • iOS Safari: 4.3, 5.0, 5.1, 6.0
  • Android: 2.1 or higher. Also works on the Kindle Fire.

Details


Library Options

Hipmob's HTML5/Javascript library includes all necessary dependencies: include the snippet above and you're ready to go.

User Interaction

As soon as the library loads it establishes a connection with the Hipmob communication network. The user can then immediately start chatting: all messages will be routed to all available admins. When the first admin responds, all subsequent messages are then routed to that admin.

Figure 1: Closed chat tab

The green status indicator shows whether or not there are operators available, as seen in Figure 1 above. Clicking anywhere on the tab will expand the tab as shown in Figure 2 below.

Figure 2: Open chat tab

If the chat tab is closed and messages are received by the user, a simple title alert is used to signal to the user that there are messages waiting, and a message waiting indicator appears on the tab.

Figure 3: message waiting indicator

For mobile browsers (where space is limited) and other special circumstances the Hipmob chat window can be initialized in full screen mode, providing maximum screen area in situations where the user is generally expected to be performing a single task at a time and the conventional tab-based interface may not be ideal: this is shown in Figure 4 below.

Figure 4: full screen interface

This can also be used in iframes where the support chat should be a component on the page, as seen in Figure 5 below.

Figure 5: embedded in a page

User Information

Useful user information can be provided to the HipmobChat client as configuration options: this information can include the user's name or email, as well as context about what activity the user may be doing. Certain browser information is also sent: see the full range of configuration options available.

Localization

The Hipmob HTML5/Javascript library currently is still US English-only: future releases will support additional languages.

Available Messages

Hipmob stores messages received when a user is unavailable (offline message delivery): every unique chat client is maintained within the Hipmob network as a distinct entity and messages received when the client is offline are stored for future delivery when next the client connects. To help you make the most of this the Hipmob chat widget provides a simple function to let you check for pending messages: if this is called an messages are available a messagesavailable event will be fired.
To request the pending message count, use the check_for_messages method on the hipmob object (the user id is optional):
if(hipmob.check_for_messages(appid, userid)){
		    hipmob.once('messagesavailable', function(hm, count){
		    if("log" in console) console.log("There are "+count+" messages waiting.");
		    });
		    }
		
See the full Javascript API for additional functions that may be useful.

Web Analytics

Hipmob can be configured to send events to your existing web analytics provider: this lets you analyze your usage of Hipmob with the same tools you already use and improve the results you get from live chat. This is so important we gave it a page of its very own! Read more in our Web Analytics guide.

Configuration Options


All configuration options are provided to the Hipmob chat widget before the javascript is loaded:
		    <script type="text/javascript">
		    var _hmc = _hmc || [];
		    _hmc.push(['app', '<application ID>']);
		    (function() {
		    var hm = document.createElement('script'); hm.type = 'text/javascript';
		    hm.async = true;
		    hm.src = 'https://hipmob.s3.amazonaws.com/hipmobchat.min.js';
		    var b = document.getElementsByTagName('body')[0]; b.appendChild(hm);
		    })();
		    </script>
		  
The _hmc.push call passes an array with 2 entries: the option name and the option value (which could be a string, a number or a Javascript associative array). The available options are shown below with usage examples.

Application ID

Description
The unique identifier that distinguishes this application from any other application that uses the Hipmob network. The app identifier is obtained from the Hipmob management interface.
Required
Yes
Since:
Version 0.3.0
Option Name:
appid
Option Type:
string
Usage
If the application ID provided by the management interface is fefed30c17f0409f89d5a4953c0fce1f, then it would be used like this:
		    <script type="text/javascript">
		    var _hmc = _hmc || [];
		    _hmc.push(['app', 'fefed30c17f0409f89d5a4953c0fce1f']);
		    (function() {
		    var hm = document.createElement('script');
		    hm.type = 'text/javascript';
		    hm.async = true;
		    hm.src = 'https://hipmob.s3.amazonaws.com/hipmobchat.min.js';
		    var b = document.getElementsByTagName('body')[0]; b.appendChild(hm);
		    })();
		    </script>
		  

User ID

Description
The host web page can provide a user identifier that is passed back to the Hipmob communication network. If this isn't passed, a custom identifier will be generated. The user identifier can be used with the Hipmob API to send messages that will be delivered next time the user connects to the chat.
Required
No
Since:
Version 0.3.0
Option Name:
uid
Option Type:
any (will be converted to string)
Usage
After a user has logged into your web application, you can use an internal identifier (such as a database ID) as shown below (this assumes the database ID is 42).
		    <script type="text/javascript">
		    var _hmc = _hmc || [];
		    _hmc.push(['app', 'fefed30c17f0409f89d5a4953c0fce1f']);
		    _hmc.push(['uid', 42]);
		    (function() {
		    var hm = document.createElement('script');
		    hm.type = 'text/javascript';
		    hm.async = true;
		    hm.src = 'https://hipmob.s3.amazonaws.com/hipmobchat.min.js';
		    var b = document.getElementsByTagName('body')[0]; b.appendChild(hm);
		    })();
		    </script>
		  

User Name

Description
The host web page can provide the user's name: this will then be displayed to the operator talking to the user.
Required
No
Since:
Version 0.3.0
Option Name:
name
Option Type:
string
Usage
Just pass the name option:
		    <script type="text/javascript">
		    var _hmc = _hmc || [];
		    _hmc.push(['app', 'fefed30c17f0409f89d5a4953c0fce1f']);
		    _hmc.push(['uid', 42]);
		    _hmc.push(['name', 'Jack Hawksmoor']);
		    (function() {
		    var hm = document.createElement('script');
		    hm.type = 'text/javascript';
		    hm.async = true;
		    hm.src = 'https://hipmob.s3.amazonaws.com/hipmobchat.min.js';
		    var b = document.getElementsByTagName('body')[0]; b.appendChild(hm);
		    })();
		    </script>
		  

User Email

Description
The host web page can provide the user's email: this will then be displayed to the operator talking to the user.
Required
No
Since:
Version 0.3.0
Option Name:
email
Option Type:
string
Usage
Just pass the email option:
		    <script type="text/javascript">
		    var _hmc = _hmc || [];
		    _hmc.push(['app', 'fefed30c17f0409f89d5a4953c0fce1f']);
		    _hmc.push(['uid', 42]);
		    _hmc.push(['email', 'jack@theauthority.com']);
		    (function() {
		    var hm = document.createElement('script');
		    hm.type = 'text/javascript';
		    hm.async = true;
		    hm.src = 'https://hipmob.s3.amazonaws.com/hipmobchat.min.js';
		    var b = document.getElementsByTagName('body')[0]; b.appendChild(hm);
		    })();
		    </script>
		  

User Phone Number

Description
The host web page can provide the user's phone number: this will then be displayed to the operator talking to the user and attached to the user's Hipmob record.
Required
No
Since:
Version 0.5.0
Option Name:
phone
Option Type:
string
Usage
Pass the phone option:
		    <script type="text/javascript">
		    var _hmc = _hmc || [];
		    _hmc.push(['app', 'fefed30c17f0409f89d5a4953c0fce1f']);
		    _hmc.push(['uid', 42]);
		    _hmc.push(['phone', '+1234567890']);
		    (function() {
		    var hm = document.createElement('script');
		    hm.type = 'text/javascript';
		    hm.async = true;
		    hm.src = 'https://hipmob.s3.amazonaws.com/hipmobchat.min.js';
		    var b = document.getElementsByTagName('body')[0]; b.appendChild(hm);
		    })();
		    </script>
		  

User Context

Description
The host web page can provide context information (such as the activity the user was involved in when they launched the chat window). This context information will then be displayed to the operator talking to the user.
Required
No
Since:
Version 0.3.0
Option Name:
context
Option Type:
string
Usage
Just pass the context option:
		    <script type="text/javascript">
		    var _hmc = _hmc || [];
		    _hmc.push(['app', 'fefed30c17f0409f89d5a4953c0fce1f']);
		    _hmc.push(['uid', 42]);
		    _hmc.push(['context', 'navigating the Bleed on the Carrier']);
		    (function() {
		    var hm = document.createElement('script');
		    hm.type = 'text/javascript';
		    hm.async = true;
		    hm.src = 'https://hipmob.s3.amazonaws.com/hipmobchat.min.js';
		    var b = document.getElementsByTagName('body')[0]; b.appendChild(hm);
		    })();
		    </script>
		  

Title

Description
The host web page can provide a title: this text is then displayed in the tab of the Hipmob chat widget. If this is not provided the chat widget title will be the string Live Help. In addition, a custom title can be specified that will be shown if there are no operators available.
Required
No
Since:
Version 0.3.0
Option Name:
title, title_away
Option Type:
string
Usage
Just pass the title option:
		    <script type="text/javascript">
		    var _hmc = _hmc || [];
		    _hmc.push(['app', 'fefed30c17f0409f89d5a4953c0fce1f']);
		    _hmc.push(['uid', 42]);
		    _hmc.push(['title',"Talk to us - we're real people"]);
		    _hmc.push(["title_away","Be back soon!"]);
		    (function() {
		    var hm = document.createElement('script');
		    hm.type = 'text/javascript';
		    hm.async = true;
		    hm.src = 'https://hipmob.s3.amazonaws.com/hipmobchat.min.js';
		    var b = document.getElementsByTagName('body')[0]; b.appendChild(hm);
		    })();
		    </script>
		  

Load Callback

Description
The host web page can provide a function to be called when the chat widget is fully loaded and first displayed. This will be called with the Hipmob chat widget BEFORE the connection to the Hipmob chat network is initiated.
Required
No
Since:
Version 0.3.1
Option Name:
on_load
Option Type:
function
Usage
Just pass the on_load option:
		    <script type="text/javascript">
		    var loaded = function(){
		    if("log" in console) console.log("Hipmob is loaded!");
		    };

		    var _hmc = _hmc || [];
		    _hmc.push(['app', 'fefed30c17f0409f89d5a4953c0fce1f']);
		    _hmc.push(['uid', 42]);
		    _hmc.push(['on_load', loaded]);
		    (function() {
		    var hm = document.createElement('script');
		    hm.type = 'text/javascript';
		    hm.async = true;
		    hm.src = 'https://hipmob.s3.amazonaws.com/hipmobchat.min.js';
		    var b = document.getElementsByTagName('body')[0]; b.appendChild(hm);
		    })();
		    </script>

Widget Settings

Description
The host web page can configure the top-level widget behavior and look and feel by passing a Javascript associative array with the options listed below. These are all applied when the Hipmob chat widget is being displayed for the first time. All values are optional.
Required
No
Since:
Version 0.3.1
Option Name:
settings
Option Type:
Associative array
Option Fields:
Key Value Type Description
fullscreen boolean If true, the chat widget will fill the entire window.
closable boolean If false, the chat widget will not be closable (i.e once the tab is expanded clicking on the tab will not collapse it).
hide boolean If true, the chat widget will be created but not displayed. A call to the show function will be needed to display the chat widget. This allow the chat widget to be entirely hidden until it is needed.
ifavailable boolean If true, the chat widget will be created, but will stay hidden unless there is an operator available. A call to the show function can be used to force the widget to become visible. This allow the chat widget to be entirely hidden if no operators are available.
open boolean If true, the chat widget will automatically open immediately after it loads. Clicking on the tab will collapse it (as long as the closable setting has not been applied).
openonmessage boolean If true, the chat widget will automatically open whenever a new message is received. If the widget is already open, no change will occur. If the widget is not visible, it will be made visible.
hideonclose boolean If true, the chat widget will disappear when the conversation is closed. Only use this if using the data-hipmob-toggle option.
width string OR number Sets the width of the chat widget in pixels: either a number (like 275) or a string (like '275px') are acceptable. The minimum allowable width is 240.
height string OR number Sets the height of the opened chat widget in pixels: either a number (like 275) or a string (like '275px') are acceptable. The minimum allowable height is 275.
position string Sets the position of the tab: the possible values are topleft, bottomleft, topright, bottomright, topcenter, or bottomcenter: the default is bottomright.
offset string OR number Sets the offset from the left if the position is topleft or bottomleft or the offset from the right if the position is topright or bottomright in pixels: either a number (like 275) or a string (like '275px') are acceptable. The minimum allowable offset is 50.
font-weight string The value bold to make the tab text bold.
font-style string The value italic to make the tab text italic.
font-family string The font family to apply to all text (by default).
font-size string The font size to apply to all text (by default).
border-color string The color to use for the border.
border-style string The style of border to use: can be any valid CSS border-style value.
border-width string OR number The width in pixels of the border for the chat box: either a number (like 1) or a string (like '1px') are acceptable. The minimum allowable width is 0.
background-color string The background color to use for the tab.
background-image string The URL for the background image to be used for the tab.
background-repeat string The CSS background-repeat setting for the tab.
background-postion string The CSS background-position setting for the tab.
greeting string A greeting message to be displayed as soon as the chat widget is loaded. This will not appear in the transcript.
userlabel string The label to use for messages sent by the user: defaults to Me. This will not appear in the transcript.
placeholder string The placeholder to display in the text input area: defaults to Send us a message.
name_placeholder string The placeholder to display in the pre-chat form name input field: defaults to Your name?.
email_placeholder string The placeholder to display in the pre-chat form email address input field: defaults to Your email address?.
phone_placeholder string The placeholder to display in the pre-chat form phone number input field: defaults to Your phone number?.
question_placeholder string The placeholder to display in the pre-chat form question input field: defaults to How can we help?.
Usage
Just pass the settings option:
		    <script type="text/javascript">
		    var _hmc = _hmc || [];
		    _hmc.push(['app', 'fefed30c17f0409f89d5a4953c0fce1f']);
		    _hmc.push(['uid', 42]);
		    _hmc.push(['settings', { 'fullscreen': true, 'open': true, 'closable': false }]);
		    (function() {
		    var hm = document.createElement('script');
		    hm.type = 'text/javascript';
		    hm.async = true;
		    hm.src = 'https://hipmob.s3.amazonaws.com/hipmobchat.min.js';
		    var b = document.getElementsByTagName('body')[0]; b.appendChild(hm);
		    })();
		    </script>

Tab Settings

Description
The host web page can configure the chat widget tab look and feel by passing a Javascript associative array with the options listed below. These are all applied when the Hipmob chat widget is being displayed for the first time. All values are optional.
Required
No
Since:
Version 0.3.1
Option Name:
tab
Option Type:
Associative array
Option Fields:
Key Value Type Description
height string or number This sets the height of the widget's tab (that is displayed when the widget is closed).
font-weight string The value bold to make the tab text bold.
font-style string The value italic to make the tab text bold.
font-size string The font size to apply to all text (by default).
font-family string The font family to apply to the tab text.
color string The color to use for the text in the tab.
background-color string The background color to use for the tab.
background-image string The URL for the background image to be used for the tab.
background-repeat string The CSS background-repeat setting for the tab.
background-postion string The CSS background-position setting for the tab.
Usage
Just pass the settings option:
		    <script type="text/javascript">
		    var _hmc = _hmc || [];
		    _hmc.push(['app', 'fefed30c17f0409f89d5a4953c0fce1f']);
		    _hmc.push(['uid', 42]);
		    _hmc.push(['tab', { 'background-color': '#dedede', 'color': '#383838' }]);
		    (function() {
		    var hm = document.createElement('script');
		    hm.type = 'text/javascript';
		    hm.async = true;
		    hm.src = 'https://hipmob.s3.amazonaws.com/hipmobchat.min.js';
		    var b = document.getElementsByTagName('body')[0]; b.appendChild(hm);
		    })();
		    </script>

Input Settings

Description
The host web page can configure the chat widget's input fields by passing a Javascript associative array with the options listed below. These are all applied when the Hipmob chat widget is being displayed for the first time. All values are optional.
Required
No
Since:
Version 0.3.1
Option Name:
input
Option Type:
Associative array
Option Fields:
Key Value Type Description
height string or number This sets the height of the tab widget.
width string or number This sets the width of the input text-areawidget.
placeholder string The placeholder text to be used with the input.
font-weight string The value bold to make the tab text bold.
font-style string The value italic to make the tab text bold.
font-size string The font size to apply to all text (by default).
font-family string The font family to apply to the tab text.
Usage
Just pass the settings option:
		    <script type="text/javascript">
		    var _hmc = _hmc || [];
		    _hmc.push(['app', 'fefed30c17f0409f89d5a4953c0fce1f']);
		    _hmc.push(['uid', 42]);
		    _hmc.push(['input', { 'height': '40px' }]);
		    (function() {
		    var hm = document.createElement('script');
		    hm.type = 'text/javascript';
		    hm.async = true;
		    hm.src = 'https://hipmob.s3.amazonaws.com/hipmobchat.min.js';
		    var b = document.getElementsByTagName('body')[0]; b.appendChild(hm);
		    })();
		    </script>

Icon

Description
A custom icon to be displayed in the chat widget tab bar.
Required
No
Since:
Version 0.3.1
Option Name:
icon
Option Type:
string
Usage
Just pass the icon option:
		    <script type="text/javascript">
		    var _hmc = _hmc || [];
		    _hmc.push(['app', 'fefed30c17f0409f89d5a4953c0fce1f']);
		    _hmc.push(['uid', 42]);
		    _hmc.push(['icon', 'my_site_icon.png']);
		    (function() {
		    var hm = document.createElement('script');
		    hm.type = 'text/javascript';
		    hm.async = true;
		    hm.src = 'https://hipmob.s3.amazonaws.com/hipmobchat.min.js';
		    var b = document.getElementsByTagName('body')[0]; b.appendChild(hm);
		    })();
		    </script>

Status Icons

Description
The host web page can customize the icons to be shown when the connection changes state: the available states are connection offline, operator online or operator offline. All values are optional.
Required
No
Since:
Version 0.3.1
Option Name:
statusicons
Option Type:
Associative array
Option Fields:
Key Value Type Description
offline string The URL for the icon to be used when the operator is away.
online string The URL for the icon to be used when the operator is available.
disconnected string The URL for the icon to be used when the connection to the Hipmob server is unavailable.
Usage
Just pass the statusicons option:
		    <script type="text/javascript">
		    var _hmc = _hmc || [];
		    _hmc.push(['app', 'fefed30c17f0409f89d5a4953c0fce1f']);
		    _hmc.push(['uid', 42]);
		    _hmc.push(['statusicons', { 'online': 'http://www.hipmob.com/images/open.png', 'offline': 'http://www.hipmob.com/images/close.png', 'disconnected': 'http://www.hipmob.com/images/test.png' }]);
		    (function() {
		    var hm = document.createElement('script');
		    hm.type = 'text/javascript';
		    hm.async = true;
		    hm.src = 'https://hipmob.s3.amazonaws.com/hipmobchat.min.js';
		    var b = document.getElementsByTagName('body')[0]; b.appendChild(hm);
		    })();
		    </script>

Control Icons

Description
The host web page can customize the icons to be used to indicate that the tab widget is open or closed. All values are optional.
Required
No
Since:
Version 0.3.1
Option Name:
controlicons
Option Type:
Associative array
Option Fields:
Key Value Type Description
open string The URL for the open icon.
close string The URL for the close icon.
Usage
Just pass the controlicons option:
		    <script type="text/javascript">
		    var _hmc = _hmc || [];
		    _hmc.push(['app', 'fefed30c17f0409f89d5a4953c0fce1f']);
		    _hmc.push(['uid', 42]);
		    _hmc.push(['controlicons', { 'open': 'http://www.hipmob.com/images/open.png', 'close': 'http://www.hipmob.com/images/close.png' }]);
		    (function() {
		    var hm = document.createElement('script');
		    hm.type = 'text/javascript';
		    hm.async = true;
		    hm.src = 'https://hipmob.s3.amazonaws.com/hipmobchat.min.js';
		    var b = document.getElementsByTagName('body')[0]; b.appendChild(hm);
		    })();
		    </script>

Javascript API

Set Title

Description
Sets the title that displays in the chat tab.
Parameters
Name Type Required Description
title string YES The new title.
Example Code
hipmob.set_title("This is my new title.");
		  

Check for Messages

Description
Checks the server to see if any undelivered messages are waiting.
Parameters
Name Type Required Description
appid string YES The Hipmob app identifier.
userid string NO The host application user identifier for the current user. If this is not specified a default site user identifier will be generated and preserved in a cookie.
Notes
The available message check is asynchronous: the call will return immediately. Register for the messagesavailable event on the Hipmob chat object to receive the result of the check.
Example Code
if(hipmob.check_for_messages(appid, userid)){
		    hipmob.once('messagesavailable', function(hm, count){
		    if("log" in console) console.log("There are "+count+" messages waiting.");
		    });
		    }
                  

Get Version

Description
Returns the implementation version string for the Hipmob chat widget.
Parameters
None
Return Type
string
Example Code
if("log" in console){
		    console.log("Hipmob Chat Widget Version: "+hipmob.get_version()+".");
		    }

on (addListener)

Description
Adds a listener for a Javascript event generated by the Hipmob chat widget. This listener will be called with the event parameters whenever the event is generated.
Parameters
Name Type Required Description
event string YES The event name to listen to.
callback function YES The listener function to be called.
Example Code
hipmob.on('show', function(){
		    if("log" in console){
		    console.log("The chat tab is now visible.");
		    }
		    });

once

Description
Adds a listener for a Javascript event generated by the Hipmob chat widget. This listener will only be called the next time the event is generated: it will NOT be called on subsequent events.
Parameters
Name Type Required Description
event string YES The event name to listen to.
callback function YES The listener function to be called.
Example Code
hipmob.once('show', function(){
		    if("log" in console){
		    console.log("The chat tab is now visible.");
		    }
		    });

removeListener

Description
Removes an existing event listener that has been attached to the Hipmob chat widget.
Parameters
Name Type Required Description
event string YES The event name to listen to.
callback function YES The listener function to be removed.
Example Code
var show = function(){
		    if("log" in console){
		    console.log("The chat tab is now visible.");
		    }
		    };
		    hipmob.on('show', on_show);

		    // some time later
		    hipmob.removeListener('show', on_show);
		  

show

Description
Displays the tab widget (if it is currently invisible). This can be used from custom Javascript code to control the visibility of the chat widget.
Parameters
None
Example Code
hipmob.show();
		  

hide

Description
Hides the tab widget (if it is currently visible). This can be used from custom Javascript code to control the visibility of the chat widget.
Parameters
None
Example Code
hipmob.hide();
		  

open

Description
Opens the chat widget tab (if it is currently closed). This can be used to open the tab from custom Javascript code.
Parameters
None
Example Code
hipmob.open();
		  

close

Description
Closes the chat widget tab (if it is currently opened). This can be used to close the tab from custom Javascript code.
Parameters
None
Example Code
hipmob.close();
		  

Set Name

Description
Sets the name that should be displayed to the operator for this user. This allows the user's name to be updated after the connection to the Hipmob communication network has been established.
Parameters
Name Type Required Description
name string YES The new name.
Example Code
hipmob.set_name("Jack Hawksmoor");
		  

Set Email

Description
Sets the email address that should be displayed to the operator for this user. This allows the user's email address to be updated after the connection to the Hipmob communication network has been established.
Parameters
Name Type Required Description
email string YES The new email address.
Example Code
hipmob.set_email("jack@theauthority.com");
		  

Set Phone Number

Description
Sets the phone that should be attached to the user. This allows the user's phone number to be updated after the connection to the Hipmob communication network has been established.
Parameters
Name Type Required Description
number string YES The new phone number.
Example Code
hipmob.set_phone("+1234567890");
		  

Set Context

Description
Sets the context for this user: this can be used to inform the operator about the user's actions in the host web site or application after the connection to the Hipmob communication network has been established.
Parameters
Name Type Required Description
context string YES The new context value.
properties associative array NO An associative array with additional information to be stored with the context update. This could be (for example) order information or details about a page action taken by the user.
Example Code
hipmob.set_context("updating their billing info.");

		    hipmob.set_context("buying windshield wipers.", { quantity: 2 });

Events

Ready

Event Name
ready
Description
Fired when the Hipmob chat widget has successfully connected to the Hipmob communication network and is ready to send and receive messages.
Parameters
# Type Description
1 Hipmob chat widget The Hipmob chat widget that generated the event.
Notes
This will be the very first event generated once the Hipmob chat widget is fully loaded and has connected to the Hipmob communication network: this will only fire if we were able to successfully establish a network connection.

Start Conversation

Event Name
startconversation
Description
Fired when the first user-generated message in the conversation is sent (either by the website visitor or a human operator; this will not fire for automated messages such as greetings or away messages).
Parameters
# Type Description
1 Hipmob chat widget The Hipmob chat widget that generated the event.
2 boolean true if the operator started the conversation, false otherwise.
Notes
This can be used to tell when the conversation is started, and by whom.

Operator Accepted

Event Name
operatoraccepted
Description
Fired when an operator accepts the conversation.
Parameters
# Type Description
1 Hipmob chat widget The Hipmob chat widget that generated the event.
2 string The name of the operator that acceted the conversation.

Text Message Received

Event Name
textmessagereceived
Description
Fired whenever a text message is received from the Hipmob communication network.
Parameters
# Type Description
1 Hipmob chat widget The Hipmob chat widget that generated the event.
2 string The display name of the entity (person or automated process) that sent the message.
3 string The text of the message
4 string The identifier of the entity that sent the message: this is only useful for peer-to-peer messages.
Notes

Text Message Sent

Event Name
textmessagesent
Description
Fired whenever a message is sent to the Hipmob communication network.
Parameters
# Type Description
1 Hipmob chat widget The Hipmob chat widget that generated the event.
2 string The text of the message that was sent.

Show

Event Name
show
Description
Fired whenever the chat tab is opened up.
Parameters
# Type Description
1 Hipmob chat widget The Hipmob chat widget that generated the event.

Hide

Event Name
hide
Description
Fired whenever the chat tab is closed.
Parameters
# Type Description
1 Hipmob chat widget The Hipmob chat widget that generated the event.
Notes

Messages Available

Event Name
messagesavailable
Description
Fired whenever unread messages are available.
Parameters
# Type Description
1 Hipmob chat widget The Hipmob chat widget that generated the event.
2 number The number of unread messages.
Notes
Generally this event is fired in response to a call to check_for_messages, however the Hipmob chat widget may periodically fire this message on its own.