Zopim is now called Zendesk Chat. All API functionality will continue to work as normal and the namespace will not change in the immediate future.

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.livechatThe Javascript API lets you customize various aspects of the Zopim Live Chat Widget.
Functions
getNameGet the name of the visitor.
getEmailGet the email address of the visitor.
getPhoneGet the phone number of the visitor.
isChattingCheck whether a chat session is in progress.
setA convenience function to set multiple settings at once.
setNameSet the visitor’s name.
setEmailSet the visitor’s email address.
setPhoneSet the visitor’s phone number.
addTagsAdd tag(s) to the current chat session.
sendVisitorPathProgrammatically update visitor’s webpath.
removeTagsRemove tag(s) from the current chat session.
setDisableSoundConfigure whether sound notifications are played.
setLanguageSet the widget language.
setGreetingsSet the greeting messages displayed on the chat button for each status on the desktop widget.
clearAllClear all visitor data and register as a new visitor.
hideAllHide the widget completely.
sayMake the visitor send a message.
setOnConnectedRegister a callback to be fired when the widget successfully connects to the server.
setOnChatStartRegister a callback to be fired when a chat starts.
setOnChatEndRegister a callback to be fired when a chat ends.
setOnStatusRegister a callback to be fired when the account status changes.
setOnUnreadMsgsRegister a callback to be fired when the number of unread messages changes.
endChatEnd the current chat session.
setStatusSet the widget account status.
setNotesSet the visitor’s notes.
appendNotesAppend 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 objectAn 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

nameVisitor’s name

setEmail

function setEmail(email)

Set the visitor’s email address.

Parameters

emailVisitor’s email address

setPhone

function setPhone(phone)

Set the visitor’s phone number.

Parameters

phoneVisitor’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 objectOptional - 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

booltrue 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

langLanguage 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

hashAn 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

msgMessage 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)

Register a callback to be fired when the widget successfully connects to the server.

Parameters

callbackFunction to be registered

setOnChatStart

function setOnChatStart(callback)

Register a callback to be fired when a chat starts.

Parameters

callbackFunction to be registered

setOnChatEnd

function setOnChatEnd(callback)

Register a callback to be fired when a chat ends.

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

callbackFunction 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.

Parameters

callback(status)Function to be registered.  The function will be passed 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

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

setNotes

function setNotes(notes)

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

Parameters

notesNotes to be set (string)

appendNotes

function appendNotes(notes)

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

Parameters

notesNotes 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)
Register a callback to be fired when the widget successfully connects to the server.
function setOnChatStart(callback)
Register a callback to be fired when a chat starts.
function setOnChatEnd(callback)
Register a callback to be fired when a chat ends.
function setOnStatus(callback)
Register a callback to be fired when the account status changes.
function setOnUnreadMsgs(callback)
Register a callback to be fired when the number of unread messages changes.
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.