$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
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.
$zopim. | 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. |
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>
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>
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 |
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>
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. |
Get the name of the visitor.
function getName()
Get the email address of the visitor.
function getEmail()
Get the phone number of the visitor.
function getPhone()
Check whether a chat session is in progress.
function isChatting()
A convenience function to set multiple settings at once.
function set( settings )
Set the visitor’s name.
function setName( name )
Set the visitor’s email address.
function setEmail( )
Set the visitor’s phone number.
function setPhone( phone )
Add tag(s) to the current chat session.
function addTags( /* tag1[, tag2[, tag3[, ...]]] * / )
Programmatically update visitor’s webpath.
function sendVisitorPath( options )
Remove tag(s) from the current chat session.
function removeTags( /* tag1[, tag2[, tag3[, ...]]] * / )
Configure whether sound notifications are played.
function setDisableSound( bool )
Set the widget language.
function setLanguage( lang )
Set the greeting messages displayed on the chat button for each status on the desktop widget.
function setGreetings( hash )
Clear all visitor data and register as a new visitor.
function clearAll()
Hide the widget completely.
function hideAll()
Make the visitor send a message.
function say( msg )
Register a callback to be fired when the widget successfully connects to the server.
function setOnConnected( callback )
Register a callback to be fired when a chat starts.
function setOnChatStart( callback )
Register a callback to be fired when a chat ends.
function setOnChatEnd( callback )
Register a callback to be fired when the account status changes.
function setOnStatus( callback )
Register a callback to be fired when the number of unread messages changes.
function setOnUnreadMsgs( callback )
End the current chat session.
function endChat()
Set the widget account status.
function setStatus( status )
Set the visitor’s notes.
function setNotes( notes )
Append to the visitor’s notes.
function appendNotes( notes )