Javascript API

Welcome to the Chatstack Javascript API! You can use our Javascript API to configure and customize the live chat widget that is displayed on your website. For example you can open the chat widget, close the chat widget, detect when a chat is accepted.

We have language examples available for Javascript! You can view code examples in the dark area to the right.

This API is constantly updated with new endpoints and features. We recommend always running the latest version of Chatstack so you can access the latest API features.

Getting Started

To get started, use this HTML code on your website:

<!--  START Chatstack Live Chat HTML Code - chatstack.com -->
<script type="text/javascript">
    var Chatstack = { server: 'www.example.com' };
    (function(d, undefined) {
        // JavaScript
        Chatstack.e = []; Chatstack.ready = function (c) { Chatstack.e.push(c); }
        var b = d.createElement('script'); b.type = 'text/javascript'; b.async = true;
        b.src = ('https:' == d.location.protocol ? 'https://' : 'http://') + Chatstack.server + '/livehelp/scripts/js.js';
        var s = d.getElementsByTagName('script')[0];
        s.parentNode.insertBefore(b, s);
    })(document);
</script>
<!--  END Chatstack Live Chat HTML Code - chatstack.com -->

Make sure to replace www.example.com with your installation address.

Chatstack uses a global settings object Chatstack to access the Javascript API. You can access the settings object within your live chat HTML code.

Chatstack requires the live chat HTML code on your website to monitor your website visitors and display the live chat widget. The HTML code should be configured

var Chatstack = { server: 'www.example.com' };

Chat Widget

Open Chat

Chatstack.openChat();

The above function doesn’t return any data.

This function allows you to open the live chat widget. If the widget is already opened then the function will do nothing.

If the live chat is offline then this will open the offline email interface or redirect to your Offline URL redirection setting.

Close Chat

Chatstack.closeChat();

The above function doesn’t return any data.

This function allows you to close the live chat widget. If the widget is already closed then the function will do nothing.

Get Window State

if (Chatstack.windowState === 'opened') {

}

The above function returns a string value the indicates the current window state.

This property allows you to check the state of the chat widget / window to see if the widget / window is opened or closed.

Results

The property may return one of the following values.

Value	Type	Description
opened	string	The chat window is opened
closed	string	The chat window is closed

Get Status Mode

if (Chatstack.statusMode === 'online') {

}

The above property returns a string value the indicates if the live chat is online / offline etc.

This property allows you to check the status mode of the live chat.

Results

The property may return one of the following values.

Value	Type	Description
online	string	The live chat is Online
offline	string	The live chat is Offline
brb	string	The live chat is Be Right Back
away	string	The live chat is Away

Get Chat State

if (Chatstack.chatState === 'chatting') {

}

The above property returns a string value the indicates if the chat is active etc.

This property allows you to check the status of the chat.

Results

The property may return one of the following values.

Value	Type	Description
idle	string	The chat hasn’t started
waiting	string	The chat is connecting / waiting for a team member to accept
connected	string	The chat is connected and active
disconnected	string	The chat is disconnected / completed

Chat Tab Color

There are two options for changing the chat tab color without having to edit CSS files or make any advanced changes. The basic option will allow you to select a preset theme and the advanced option will allow you to set exact color codes.

Basic Color Themes

Chatstack.theme = 'turquoise';

The above property can be used to change the chat theme to a preset theme. There are 7 preset themes available.

Various basic theme options are available if you don’t wish to set the colors specifically using the advanced options.

Color	Theme
	default
	green
	turquoise
	blue
	purple
	pink
	orange

Advanced Color Themes

Chatstack.colors = {tab: {normal: '#dddedf', hover: '#c9cacc'}};
Chatstack.theme = 'dark'; // light or dark

The above advanced properties can be used to change the chat tab color and theme.

These advanced properties will allow you to change the chat tab colors to exact CSS color codes. You can change the color for both the normal and hover state.

You can also change the theme text color to either light or dark depending on your desired colors.

Initiate Chat

Open Initiate Chat

Chatstack.openInitiateChat();

The above function doesn’t return any data.

This function allows you to open the initiate chat. If the initiate chat is already opened then the function will do nothing.

Close Initiate Chat

Chatstack.closeInitiateChat();

The above function doesn’t return any data.

This function allows you to close the initiate chat. If the initiate chat is already closed then the function will do nothing.

Get Initiate Chat State

if (Chatstack.initiateChatState === 'declined') {

}

The above property returns a string value the indicates if the initiate chat feature has been displayed / accepted or declined etc.

This property allows you to check the status mode of the initiate chat.

Results

The property may return one of the following values.

Value	Type	Description
idle	string	The initiate chat hasn’t been displayed
waiting	string	The initiate chat is displayed and waiting for input
opened	string	The initiate chat was click but no message sent yet
accepted	string	The initiate chat was clicked
declined	string	The initiate chat was closed

Custom Data

Name

Chatstack.name = 'John Doe';

The above property can be used to automatically assign the customer’s name to the chat.

Chatstack.name = '<?php echo $customer->name ?>';

You can use some server side code to complete this property if you have an object available with the customer’s name.

This property will allow you to automatically pass the customer’s name into the chat so you can identify the customer. This is useful so the customer doesn’t have to provide their name.

Email

Chatstack.email = '[email protected]';

The above property can be used to automatically assign the customer’s email to the chat.

Chatstack.email = '<?php echo $customer->email ?>';

You can use some server side code to complete this property if you have an object available with the customer’s email address.

This property will allow you to automatically pass the customer’s email into the chat so you can identify the customer. This is useful so the customer doesn’t have to provide their email address.

Department

Chatstack.department = 'Technical Support';

The above property can be used to automatically route the chat to a given department that you have configured with your live chat installation.

This property will allow you to automatically route the chat to a given department.

This is useful if you would like to direct the customer to certain departments depending on what web page that they are currently viewing. For example your sales web pages could automatically route the visitor to the Sales department and your documentation web pages could automatically route to your Technical Support team.

Feedback Widget

Chatstack.feedback = ['How do you feel about this page?',
    'How do you feel about Chatstack?',
    'How do you feel about using live chat software?'];

The above property can be used to specify and array of random questions that will be used to request feedback from the customer when the live chat is offline.

This property will allow you to specify a list of questions that will be used for the feedback widget. The feedback widget only appears when the live chat is offline.

This is useful to gather feedback from your customers when you are unavailable on the live chat. You can customize these questions based on the web page that the customer is viewing.

Callbacks / Events

Ready Event

We have a ready event for when Chatstack is ready to setup the event handlers. You would place all your event handlers within this anonymous function.

Chatstack.ready(function () {
  // Place Event Code Here
});

The above ready event indicates when you can setup your other event handlers. You would place your other event handles within the above anonymous function.

Status Mode Changed

This event occurs when the live chat status mode changes. For example when the chat switches from offline to online or from online to away mode.

Chatstack.events.on('StatusModeChanged', function (e, data) {
  // Chat Status Changed Event Received
});

The above callback returns a Javascript object containing the following result. An example object is shown below formatted as JSON for your easy reference.

{
  "status": "online"
}

Callback Parameters

The callback includes an event object and a data object. The data object contains the following properties that you might find useful.

Property	Type	Description
status	string	The status of the chat (see status values)

Status Values

Value	Type	Description
online	string	The live chat is Online
offline	string	The live chat is Offline
brb	string	The live chat is Be Right Back
away	string	The live chat is Away

Chat State Changed

Chatstack.events.on('ChatStateChanged', function (e, data) {
  // Chat State Changed Event Received
});

The above callback returns a Javascript object containing the following. An example object is shown below formatted as JSON for your easy reference.

{
  "state": "connected",
  "user": {
    "id": 6,
    "name": "John",
    "department": "Sales",
    "image": "https://secure.gravatar.com/avatar/{md5}"
  }
}

This event occurs when the chat state changes. For example the event will be triggered when the chat is idle and the customer then starts the chat, when the chat is connected to a customer service representative and when the chat is disconnected. Additionally, the event will be triggered when the page is refreshed and the chat reconnects.

Callback Parameters

The callback includes an event object and a data object. The data object contains the following properties that you might find useful.

Property	Type	Description
state	string	The state of the chat (idle, waiting, connected, disconnected)
user	object	An object for the team member that accepted the chat (optional)

User Object

Property	Type	Description
id	int	The ID of the team member (optional)
name	string	The name of the team member (optional)
department	string	The department assigned to the team member (optional)
image	string	The URL of the team member’s avatar image (optional)

Initiate Chat State Changed

Chatstack.events.on('InitiateChatStateChanged', function (e, data) {
  // Initiate Chat State Changed Event Received
});

The above callback returns a Javascript object containing the following. An example object is shown below formatted as JSON for your easy reference.

{
  "state": "waiting",
  "message": "Hello!  Did you have any questions regarding our pricing?",
  "image": "https://secure.gravatar.com/avatar/{md5}"
}

This event occurs when the initiate chat is initially displayed to the browsing site visitor or customer.

Callback Parameters

The callback includes an event object and a data object. The data object contains the following properties that you might find useful.

Property	Type	Description
state	string	The status of the initiate chat (idle, waiting, accepted, declined)
message	string	The message that is shown within the initiate chat (optional)
image	string	The URL of the team member’s avatar image (optional)

State Values

Value	Type	Description
idle	string	The initiate chat hasn’t been displayed
waiting	string	The initiate chat is displayed and waiting for input
opened	string	The initiate chat was click but no message sent yet
accepted	string	The initiate chat was clicked
declined	string	The initiate chat was closed

Troubleshooting

If you are experiencing issues with the Javascript API such as the API not returning the correct objects or values then please contact us for technical support. If you believe that you have located an error within our API documentation then please contact [email protected]

Enterprise customers can also email for development assistance under their priority support plan.