Javascript API

$zopim.livechat

Zopim Live Chat API

The Javascript API lets you customize various aspects of the Zopim Live Chat Widget.

You can use a different color scheme on a special marketing page, set the widget language based on the user’s preferences and much more.

Need more customizations?

If you are currently on a Premium plan, you have the flexibility of fully customizing the entire chat widget by developing your own using the Zendesk Chat Web SDK.

For more information, head to https://api.zopim.com/web-sdk for details.

Usage

API calls must be inserted after the Live Chat Script and wrapped within $zopim(function() { ... })

Examples

<script>

  $zopim(function() {
    $zopim.livechat.setName('Logged in name');
    $zopim.livechat.setEmail('user@somewhere.com');
  });

</script>

Note: Some API calls are unavailable for accounts using the Lite package.

Summary

$zopim.livechat	The Javascript API lets you customize various aspects of the Zopim Live Chat Widget.
Functions
getName	Get the name of the visitor.
getEmail	Get the email address of the visitor.
getPhone	Get the phone number of the visitor.
isChatting	Check whether a chat session is in progress.
set	A convenience function to set multiple settings at once.
setName	Set the visitor’s name.
setEmail	Set the visitor’s email address.
setPhone	Set the visitor’s phone number.
addTags	Add tag(s) to the current chat session.
sendVisitorPath	Programmatically update visitor’s webpath.
removeTags	Remove tag(s) from the current chat session.
setDisableSound	Configure whether sound notifications are played.
setLanguage	Set the widget language.
setGreetings	Set the greeting messages displayed on the chat button for each status on the desktop widget.
clearAll	Clear all visitor data and register as a new visitor.
hideAll	Hide the widget completely.
say	Make the visitor send a message.
setOnConnected	Register a callback to be fired when the widget successfully connects to the server.
setOnChatStart	Register a callback to be fired when a chat starts.
setOnChatEnd	Register a callback to be fired when a chat ends.
setOnStatus	Register a callback to be fired when the account status changes.
setOnUnreadMsgs	Register a callback to be fired when the number of unread messages changes.
endChat	End the current chat session.
setStatus	Set the widget account status.
setNotes	Set the visitor’s notes.
appendNotes	Append to the visitor’s notes.

Functions

getName

function getName()

Get the name of the visitor.

Example

<script>

  $zopim(function() {
    alert("Visitor's name: " + $zopim.livechat.getName());
  });

</script>

getEmail

function getEmail()

Get the email address of the visitor.

Example

<script>

  $zopim(function() {
    alert("Visitor's email: " + $zopim.livechat.getEmail());
  });

</script>

getPhone

function getPhone()

Get the phone number of the visitor.

Example

<script>

  $zopim(function() {
    alert("Visitor's phone: " + $zopim.livechat.getPhone());
  });

</script>

isChatting

function isChatting()

Check whether a chat session is in progress.

set

function set( settings )

A convenience function to set multiple settings at once. Accepts a settings object.

Parameters

settings object

An object of properties to be updated and their expected values (<settings_name> => <value> pairs)

Example

<script>

  $zopim(function() {
    $zopim.livechat.set({
      language: 'en',
      name: 'Visitor',
      email: 'visitor@site.com'
    });
  });

</script>

setName

function setName( name )

Set the visitor’s name.

Parameters

name	Visitor’s name

setEmail

function setEmail( email )

Set the visitor’s email address.

Parameters

Visitor’s email address

setPhone

function setPhone( phone )

Set the visitor’s phone number.

Parameters

phone

Visitor’s phone number

addTags

function addTags( /* tag1[, tag2[, tag3[, ...]]] * / )

Add tag(s) to the current chat session.

Note: all tags will automatically be converted to lowercase.

Parameters

tag1, tag2, ...

Tag(s) to be added

Example

<script>

  $zopim(function() {
    $zopim.livechat.addTags("zopim", "livechatAPI");
  });

</script>

sendVisitorPath

function sendVisitorPath( options )

Programmatically update visitor’s webpath.

Parameters

options object

Optional - If not specified, the current page’s location and title will be used; if specified, the updated page url and title will be taken from the options object.

Example

Update visitor’s path with specific page url and title:

<script>

  $zopim(function() {
    // update visitor's path with specific page url and title
    $zopim.livechat.sendVisitorPath({
      url: 'http://example.com',
      title: 'example'
    });
  });

</script>

Update visitor’s path with current page’s location and title:

<script>

  $zopim(function() {
    // update visitor's path with current page's location and title
    $zopim.livechat.sendVisitorPath();
  });

</script>

removeTags

function removeTags( /* tag1[, tag2[, tag3[, ...]]] * / )

Remove tag(s) from the current chat session.

Parameters

tag1, tag2, ...

Tag(s) to be removed

Example

<script>

  $zopim(function() {
    $zopim.livechat.removeTags("zopim", "livechatAPI");
  });

</script>

setDisableSound

function setDisableSound( bool )

Configure whether sound notifications are played.

Parameters

bool	true to disable sound notifications, false to enable sound notifications (boolean)

Example

Select:
<a href="javascript:void($zopim.livechat.setDisableSound(true))">Disable sound</a>
<a href="javascript:void($zopim.livechat.setDisableSound(false))">Enable sound</a>

setLanguage

function setLanguage( lang )

Set the widget language.

Parameters

lang	Language code (string). Visit https://zopimsupport.zendesk.com/hc/en-us/articles/218953857 for a list of supported languages.

Example

Pick a language:
<a href="javascript:void($zopim.livechat.setLanguage('en'))">English</a>
<a href="javascript:void($zopim.livechat.setLanguage('pt'))">Portuguese</a>
<a href="javascript:void($zopim.livechat.setLanguage('sv'))">Swedish</a>
<a href="javascript:void($zopim.livechat.setLanguage('zh_CN'))">Simplified Chinese</a>
<a href="javascript:void($zopim.livechat.setLanguage('zh_TW'))">Traditional Chinese</a>

setGreetings

function setGreetings( hash )

Set the greeting messages displayed on the chat button for each status on the desktop widget.

Status can be “online” or “offline”.

Parameters

hash	An object in the format { <status> : <greeting> }

Compatibility

For backward compatibility, the format { <status> : [ <greeting>, <greeting> ] } is also allowed but only the first greeting in the array will be used.

Example

<script>

  $zopim(function() {
    $zopim.livechat.setGreetings({
          'online': 'Chat with us',
          'offline': 'Leave us a message'
      });
  });

</script>

clearAll

function clearAll()

Clear all visitor data and register as a new visitor.

hideAll

function hideAll()

Hide the widget completely.

say

function say( msg )

Make the visitor send a message. Starts a chat session if one is not already in progress.

Parameters

msg	Message to be sent

Example

<a href="javascript:void($zopim.livechat.say('I would like an orange banana!'))">Order orange banana</a>

setOnConnected

function setOnConnected( callback )

Parameters

callback

Function to be registered

setOnChatStart

function setOnChatStart( callback )

Parameters

callback

Function to be registered

setOnChatEnd

function setOnChatEnd( callback )

A chat only ends when the visitor (and not the agent) ends the chat, or when the visitor has been idle for an extended period of time.

Parameters

callback

Function to be registered

setOnStatus

function setOnStatus( callback )

Register a callback to be fired when the account status changes. The callback will also be called once when this function is executed.

Note: The callback will also be called when an agent’s status changes.

Parameters

callback(status)

Function to be registered. The function will be passed the account status (one of “online”|”away”|”offline”).

setOnUnreadMsgs

function setOnUnreadMsgs( callback )

Register a callback to be fired when the number of unread messages changes. The callback will also be called once when this function is executed.

Parameters

callback(number)

Function to be registered. The function will be passed the number of unread messages.

endChat

function endChat()

End the current chat session.

setStatus

function setStatus( status )

Set the widget account status.

Parameters

status

Status string (allowed values: “online”, “offline”)

setNotes

function setNotes( notes )

Set the visitor’s notes. Visitor notes are visible only on the Dashboard.

Parameters

notes

Notes to be set (string)

appendNotes

function appendNotes( notes )

Append to the visitor’s notes. Visitor notes are visible only on the Dashboard.

Parameters

notes

Notes to be appended (string)

function getName()

Get the name of the visitor.

function getEmail()

Get the email address of the visitor.

function getPhone()

Get the phone number of the visitor.

function isChatting()

Check whether a chat session is in progress.

function set( settings )

A convenience function to set multiple settings at once.

function setName( name )

Set the visitor’s name.

function setEmail( email )

Set the visitor’s email address.

function setPhone( phone )

Set the visitor’s phone number.

function addTags( /* tag1[, tag2[, tag3[, ...]]] * / )

Add tag(s) to the current chat session.

function sendVisitorPath( options )

Programmatically update visitor’s webpath.

function removeTags( /* tag1[, tag2[, tag3[, ...]]] * / )

Remove tag(s) from the current chat session.

function setDisableSound( bool )

Configure whether sound notifications are played.

function setLanguage( lang )

Set the widget language.

function setGreetings( hash )

Set the greeting messages displayed on the chat button for each status on the desktop widget.

function clearAll()

Clear all visitor data and register as a new visitor.

function hideAll()

Hide the widget completely.

function say( msg )

Make the visitor send a message.

function setOnConnected( callback )

function setOnChatStart( callback )

function setOnChatEnd( callback )

function setOnStatus( callback )

function setOnUnreadMsgs( callback )

function endChat()

End the current chat session.

function setStatus( status )

Set the widget account status.

function setNotes( notes )

Set the visitor’s notes.

function appendNotes( notes )

Append to the visitor’s notes.