$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 help?  Ask our friendly customer support team, or visit https://zopim.zendesk.com/forums/22105716-JavaScript-APIs for more examples.

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

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

Parameters

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

Parameters

tag1, tag2, ...Tag(s) to be added

Example

<script>

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

</script>

removeTags

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

Remove tag(s from the current chat session.

Parameters

tag1, tag2, ...Tag(s) to be added

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.  Visit http://translate.zopim.com/ 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.

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.

Parameters

callbackFunction to be registered

setOnStatus

function setOnStatus(callback)

Register a callback to be fired when the account status changes.

Parameters

callbackFunction to be registered

setOnUnreadMsgs

function setOnUnreadMsgs(callback)

Register a callback to be fired when the number of unread messages changes.

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.

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 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 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.
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 setNotes(notes)
Set the visitor’s notes.
function appendNotes(notes)
Append to the visitor’s notes.