JavaScript API

Chat window API

Use the chat window API to manipulate the chat widget displayed on your website.

Some popular use–cases are:

  • maximizing the chat window after a given time,
  • hiding the window during the weekends.

You can also get some basic visitor’s statistics. For instance, chat window API will tell you how many chats the visitor had in the past.

Support for AJAX–based and Flash-based websites

LiveChat has a built–in support for AJAX-based and Flash-based websites that do not physically refresh the browser.

Just make sure that the address bar in the browser changes (using the anchor element in the URL: #somepage – you can use the swfaddress library to do so). LiveChat will display it just as a normal page refresh.

Support for the JavaScript API in chat window installed in native mobile apps

When you install the chat window in a native mobile app, you can still interact with the JavaScript API using LC_API object.

Use the LC_API global variable to invoke any API method.
Use the on_after_load callback to make sure LC_API is already loaded.

Using chat window API

var LC_API = LC_API || {};
LC_API.on_after_load = function()
{
	// your code here
};

Open the chat window

Maximizes the chat window (when using the embedded chat window) or opens the chat window (when using the pop-up window).

Open chat window

LC_API.open_chat_window();

Minimize the chat window

Minimizes the chat window (not supported with the pop-up chat window).

Minimize chat window

LC_API.minimize_chat_window();

Hide the chat window

Hide the chat window (not supported with the pop-up chat window).

Hide chat window

LC_API.hide_chat_window();

Hide chat window on page load

var LC_API = LC_API || {};
var livechat_chat_started = false;

LC_API.on_before_load = function()
{
	// don't hide the chat window only if visitor
	// is currently chatting with an agent
	if (LC_API.visitor_engaged() === false && livechat_chat_started === false)
	{
		LC_API.hide_chat_window();
	}
};

LC_API.on_chat_started = function()
{
	livechat_chat_started = true;
};

Agents are available

Returns true if your agents are available to chat, returns false otherwise.

This function is available only when using the embedded chat window (not the pop–up window).

Agents are available

var LC_API = LC_API || {};
LC_API.on_after_load = function()
{
	if (LC_API.agents_are_available())
	{
		// your code here which will fire only
		// when your agents are available to chat
	}
};

Check if the chat window is maximized

Returns true if the chat window is maximized, returns false otherwise (not supported with the pop-up chat window).

Check if chat window is maximized

var is_maximized = LC_API.chat_window_maximized();

Check if the chat window is minimized

Returns true if the chat window is minimized, returns false otherwise (not supported with the pop-up chat window).

Check if chat window is minimized

var is_minimized = LC_API.chat_window_minimized();

Check if the chat window is hidden

Returns true if the chat window is hidden, returns false otherwise (not supported with the pop-up chat window).

Check if chat window is hidden

var is_hidden = LC_API.chat_window_hidden();

Check if the visitor is currently waiting in the queue

Returns true if the visitor is currently waiting in the queue, returns false otherwise (not supported with the pop-up chat window).

Check if visitor is waiting in the queue

var visitor_in_queue = LC_API.visitor_queued();

Check if the visitor is currently chatting with an agent

Returns true if the visitor is currently chatting with an agent, returns false otherwise (not supported with the pop-up chat window).

Check if visitor is chatting with an agent

var is_chatting = LC_API.chat_running();

Check if the visitor is engaged

Returns true if the visitor is currently chatting, waiting in the queue or the greeting is displayed to him. Returns false otherwise (not supported with the pop-up chat window).

Check if visitor is engaged

var is_engaged = LC_API.visitor_engaged();

Return current chat window type

Returns embedded if the chat window is embedded on the website or popup if the chat window opens in a new window.

You can change the chat window type in the LiveChat app.

Get window type

var window_type = LC_API.get_window_type();

Set custom variables

You can set custom variables that LiveChat agents will see in their apps.

Custom variables will be saved in the chat transcript, so you will see them in the Archives even after the chat is finished. (Note: if variables are set after the chat is started, they will not be saved in Archives.)

Please note that custom variables can also be set in the tracking code __lc.params variable (read more). The above method should be used if you want to update the custom variables without a page refresh.

Set custom variables

var custom_variables = [
  { name: 'page', value: 'Store' },
  { name: 'user_id', value: '12345' }
];
LC_API.set_custom_variables(custom_variables);

Close chat

Closes an ongoing chat.

Close chat

LC_API.close_chat();

Callbacks

Callbacks let you bind a custom JavaScript function to an event.

For example, your function can be invoked every time the chat window is opened.

On before load

Callback function invoked when LC_API object is loaded and ready to use, before the chat window is rendered (not supported with the pop-up chat window).

You may want to use this callback to perform some operations with the chat window before it's displayed to the visitor. See the example code for hide_chat_window function.

On before load

var LC_API = LC_API || {};
LC_API.on_before_load = function()
{
	// your code here
};

On after load

Callback function invoked when LC_API object is loaded and ready to use, right after the chat window is rendered (not supported with the pop-up chat window).

On after load

var LC_API = LC_API || {};
LC_API.on_after_load = function()
{
	// your code here
};

On chat window opened

Callback function invoked when the chat window is opened.

On chat window opened

var LC_API = LC_API || {};
LC_API.on_chat_window_opened = function()
{
	// your code here
};

On chat window minimized

Callback function invoked when the chat window is minimized (not supported with the pop-up chat window).

On chat window minimized

var LC_API = LC_API || {};
LC_API.on_chat_window_minimized = function()
{
	// your code here
};

On chat window hidden

Callback function invoked when the chat window is hidden (not supported with the pop-up chat window).

On chat window hidden

var LC_API = LC_API || {};
LC_API.on_chat_window_hidden = function()
{
	// your code here
};

On chat state changed

This callback has not been released yet. It will be available on Sunday, 21 December.

Callback function invoked when the chat state is changed. It accepts one argument which contains an object with state property. Possible values:

  • offline – chat agents are not available to chat.
  • online_for_chat – chat agents are available to chat. Visitor entering the chat will be connected to the agent immediately.
  • online_for_queue – chat agents are available to chat. Visitor entering the chat will be put in a chat queue and will need to wait for the available agent.

On chat state changed

var LC_API = LC_API || {};
LC_API.on_chat_state_changed = function(data)
{
	alert('Chat state changed to: ' + data.state);
};

On chat started

Callback function invoked when the chat is started.

The only argument, data, contains additional information regarding the chat:

  • data.agent_name – the name of the agent that handles the chat.

On chat started

var LC_API = LC_API || {};
LC_API.on_chat_started = function(data)
{
	alert('Chat started with agent: ' + data.agent_name);
};

On chat ended

Callback function invoked when the chat is ended.

On chat ended

var LC_API = LC_API || {};
LC_API.on_chat_ended = function()
{
	alert('Chat ended');
};

On message

Callback function invoked when the message was sent or received.

The only argument, data, contains additional information regarding the message:

  • data.text – the content of message
  • data.user_type – visitor or agent
  • data.timestamp – unix timestamp created at the time the message arrives.
If message was sent by agent (data.user_type is 'agent'), data contains additional information:
  • data.agent_name – the name of the agent that sent the message
  • data.agent_login – the login of the agent that sent the message
If message was sent by visitor (data.user_type is 'visitor'), data contains additional information:
  • data.visitor_name – the name of the visitor that sent the message

On message

var LC_API = LC_API || {};
LC_API.on_message = function(data)
{
	alert('Message ' + data.text + ' sent by ' + data.user_type);
};

Statistics

Get last visit timestamp

Returns timestamp (in seconds) of the previous user’s visit on the website.

Get last visit timestamp

var timestamp = LC_API.get_last_visit_timestamp();

Get visits number

Returns total number of user’s visit on the website.

Get visits number

var visits = LC_API.get_visits_number();

Get page views number

Returns total number of user’s page views (including past visits).

Get page views number

var pageviews = LC_API.get_page_views_number();

Get chats number

Returns total number of user’s chats.

Get chats number

var chats = LC_API.get_chats_number();

Get visitor’s ID

Returns the unique identificator of the current visitor.

Get visitor id

var visitor_id = LC_API.get_visitor_id();

Get current chat ID

Returns the unique identificator of the current chat.

The chat ID is remembered even when the chat ends until the page is refreshed. Returns null if chat ID is unknown (e.g. chat has not yet started).

Get chat id

var chat_id = LC_API.get_chat_id();

Tracking code

LiveChat tracking code is available in the LiveChat app.

You can customize the tracking code to send additional information about your visitors to LiveChat applications.

Tracking code

<script type="text/javascript">
var __lc = {};

/**
 * LiveChat license number
 */
__lc.license = 123456;

/**
 * Chat window group (defaults to "0").
 * You can divide LiveChat agents into different departments,
 * such as "Billing" or "Support".
 * For example, if this parameter will point to group "Billing",
 * all visitors entering the chat will talk with agents
 * from this group and not the "Support" group.
 *
 * Create your group in LiveChat app:
 * https://my.livechatinc.com/agents/groups
 */
__lc.group = 1;

/**
 * Visitor's data. If your visitor is already logged in
 * to your system, you can pass his name and e-mail to LiveChat apps.
 * Agents will see the information on the "Visitors" list
 * and in the Archives.
 */
__lc.visitor = {
	name: 'Joe Public',
	email: 'joe.public@gmail.com'
};

/**
 * Custom variables sent to LiveChat applications.
 * These can be your visitor's account ID, login
 * or any other information that is important for
 * LiveChat agent during the chat.
 */
__lc.params = [
  { name: 'Login', value: 'joe_public' },
  { name: 'Account ID', value: 'ABCD1234' },
  { name: 'Total order value', value: '$123' }
];

(function() {
  var lc = document.createElement('script'); lc.type = 'text/javascript'; lc.async = true;
  lc.src = ('https:' == document.location.protocol ? 'https://' : 'http://') + 'cdn.livechatinc.com/tracking.js';
  var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(lc, s);
})();
</script>