Documentation

Widget API

Callback functions#

JivoChat executes the functions listed below to report about an event on the page. You can declare any of these functions on the page and execute a logic of processing the event that occurred. For example, using jivo_onIntroduction event you can get contact details entered by a client.

onLoadCallback#

Is executed when JivoChat widget initialization is over.

function jivo_onLoadCallback() { console.log('Widget fully loaded'); jivo_api.showProactiveInvitation("How can I help you?"); }

onOpen#

Is executed when the chat window is open both automatically (via proactive invitation) and manually by a client

function jivo_onOpen() { console.log('Widget opened'); }

onClose#

Is executed when chat window is minimized.

function jivo_onClose() { console.log('Widget closed'); }

onChangeState#

Is executed when chat window state has changed.

NameTypeDescription
statestringCurrent widget state
function jivo_onChangeState(state) { if (state == 'chat') { // widget is in the chat state } if (state == 'call' || state == 'chat/call') { // callback form is opened } if (state == 'label' || state == 'chat/min') { // widget is minimized } }

onMessageSent#

Executed when a visitor sends the first message. It will be performed only if there is no chat history.

function jivo_onMessageSent() { console.log('Client sent the first message'); }

onClientStartChat#

This callback will be executed if the chat was initiated by a client, and there was no proactive invitation shown.

function jivo_onClientStartChat() { console.log('Client started a new chat'); }

onIntroduction#

Is executed when a visitor fills the contacts form. This function can be used to track whether a client submitted contact details in order to pass them in other forms on the website.

function jivo_onIntroduction() { console.log('Client entered contact details'); let userContacts = jivo_api.getContactInfo(); console.log(userContacts) }

jivo_onAccept#

Is executed when an agent accepts the incoming chat or starts the dialog from the Visitors/All chats sections of the JivoChat app.

function jivo_onAccept() { console.log('Agent joined the chat') }

jivo_onMessageReceived#

A new message from the agent is received. The function can be used for the default chat label as well as for the custom icon. For example, with onMessageReceived you can display the unread messages counter for website visitors.

let i = 1; function jivo_onMessageReceived() { console.log(`Check agents messages: ${i++}`) }

jivo_onCallStart#

Is executed when the phone call is started. A client can order a call through the callback form, also the call can be initiated via API method jivo_api.startCall().

function jivo_onCallStart() { console.log('Call is started') }

jivo_onCallEnd#

Is executed when a return call ends.

NameTypeDescription
result optionalobjectThe result of a callback
function jivo_onCallEnd(res) { if (res.result == 'ok') { // call finished successfully } if (res.result == 'fail') { // call finished with errors or can not started console.log(res.reason); // reason for the unsuccessfull call } }

jivo_onResizeCallback#

Is executed at any change in the size of the widget: when the chat is open, closed or dragged by a user. This function can be used for dynamic displaying or hiding other elements on the website.

function jivo_onResizeCallback() { console.log("Widget is resized") }

jivo_onWidgetDestroy#

Is executed when the widget is completely removed from the page. It is triggered when calling jivo_destroy() method.

function jivo_onWidgetDestroy() { console.log('Widget is deleted') }

Methods#

API methods allow you to customise chat widget on your website. They can be used to manage the chat window behavior, and also to send any information from the page on which the chat window is placed to the JivoChat app. Methods should be initiated in the proper order, so they must be called from within a callback function jivo_onLoadCallback.

open#

Method allows to open chat window in different states.

NameTypeDescription
start optionalstringcall - window with callback request form\
menu - mobile menu with the selection of communication channel\
chat - default value with chat window
let params = {start: 'call'}; let apiResult = jivo_api.open(params); if (apiResult.result === 'fail') { console.log('Widget failed to open'); } else { console.log('Widget open successfully'); }

close#

Using this method you can minimize the chat window.

let apiResult = jivo_api.close(); if (apiResult.result === 'fail') { console.log('Failed to close widget'); } else { console.log('Widget successfully close'); }

showProactiveInvitation#

This method is used to open chat window with a custom text at specific moment. For example, it may be used if you want to show proactive invitation after the client added goods to the cart in your online store.
And if you want to show invitation immediately after the page was open, you need to call showProactiveInvitation in jivo_onLoadCallback.

NameTypeDescription
invitation_textstringInvitation text
department_id optionalnumberDepartment id
jivo_api.showProactiveInvitation("How can I help you?", 3);

setWidgetColor#

This method allows you to change the widget color.

NameTypeDescription
colorstringHexadecimal color code
color2 optionalstringHexadecimal colour code is used to create gradient
jivo_api.setWidgetColor('#ffffff', '#000000');

chatMode#

With this method you can get the current chat status: online/offline.

NameTypeDescription
resultstringonline - at least one agent is online
offline - no agents are online
function jivo_onLoadCallback() { let chatMode = jivo_api.chatMode(); if (chatMode === 'offline') { console.log("Widget is offline"); } else { console.log('Widget is online') } }

startCall#

Method allows you to start a return call to the specified number, if the calls are available (Callback feature is configured and the telephony balance is sufficient).

Method returns {result: 'ok'} if the phone number is in the correct format and the request to start the call can be made. Otherwise it returns {result: 'fail', reason: 'Callback disabled'} with the call failure reason details.

NameTypeDescription
phonestringPhone number
let phone = '+14084987855'; let apiResult = jivo_api.startCall(phone); if (apiResult.result === 'ok') { console.log('Call started, phone: ', phone); } else { console.log('Failed to start the call, reason: ', apiResult.reason); }

sendOfflineMessage#

With this method you can send a message in the offline chat mode.

It returns {result: 'ok'} if the passed parameters are correct. And it returns {result: 'fail', error: errReason}, where errReason is the validation error of the passed parameters, or the reason why you can not send an offline message.

NameTypeDescription
namestringClient's name
emailstringClient's email
phonestringClient's phone number
descriptionstringAdditional information about the client
messagestringOffline message text
let apiResult = jivo_api.sendOfflineMessage({ "name": "John Smith", "email": "email@example.com", "phone": "+14084987855", "description": "Description text", "message": "Offline message" }); if (apiResult.result === 'ok') { console.log('Message sent successfully'); } else { console.log('Error sending message, reason: ', apiResult.error); }

sendPageTitle#

Updates the title of the page the client is currently viewing and the page URL in the JivoChat app, which may be useful for SPA applications.

NameTypeDescription
titlestringAd ID
fromApi optionalstringCampaign name
url optionalstringCampaign source
let title = 'This is custom page title'; let url = 'https://site.com/url_to_page?q=params'; jivo_api.sendPageTitle(title, true, url);

setContactInfo#

Sets the contact info for the visitor. The data is displayed to the agent similarly as if the visitors introduced themselves in the chat window.

NameTypeDescription
namestringClient's name сайта
emailstringClient's email
phonestringClient's phone number
descriptionstringAdditional information about the client
jivo_api.setContactInfo({ name: "John Smith", email: "email@example.com", phone: "+14084987855", description: "Description text" });

setCustomData#

With this method you can send any additional info about the client to the JivoChat app. This info will be shown in the client's information panel (in the right side of the JivoChat app). The method can be called as many times as needed. If chat is established, information in JivoChat app will be updated in the real time. Fields are shown in the same order as they appear in the fields array.

NameTypeDescription
fieldsarrayList of additional data fields of the chat
fields.contentstringContent of data field. Tags will be insulated
fileds.titlestringTitle shown above a data field
fileds.linkstringURL that opens when the data field is clicked
fileds.keystringDescription of the data field, added in bold before the field content, separated by a colon
jivo_api.setCustomData([ { "content": "User balance: $56", }, { "content": "Open customer profile", "link": "..." }, { "title": "Actions", "content": "Add contact", "link": "..." } ]);

setUserToken#

Sets an ID number for the visitor. JivoChat does not display or handle this ID in any way but sends it in Webhook events. Using this method you can identify your website visitors when processing Webhooks. We recommend using a hard-to-guess identifier to avoid spoofing.

NameTypeDescription
tokenstringVisitor ID
jivo_api.setUserToken(token);

setRules#

This method allows you to replace the triggers' rules with the transmitted object. You can get an example of such object in our admin panel in the Triggers section, just press "JSON structure" button there.

NameTypeDescription
rulesobjectDescription of the active invitations rules in JSON
jivo_api.setRules(rules);

getContactInfo#

Returns visitor's contact info from the contacts form as a contact_info structure. If visitor didn't fill in some fields, the values there will be null.

NameTypeDescription
client_namestringClient's name
emailstringClient's email
phonestringClient's phone number
descriptionstringAdditional information about the client that was set with setContactInfo
let apiResult = jivo_api.getContactInfo(); console.log('Name: ', apiResult.client_name); console.log('Email: ', apiResult.email); console.log('Phone: ', apiResult.phone); console.log('Description: ', apiResult.description);

getVisitorNumber#

The asynchronous function to get a unique visitor number in JivoChat. Visitors are numbered sequentially: 1, 2, 3, etc. Visitor number is displayed in the agent's App and archives and can be used to associate JivoChat data with the CRM data.

NameTypeDescription
errstringString that contains the error
visitorNumberintegerVisitor's number
jivo_api.getVisitorNumber(function(error, visitorNumber) { if (error) { console.log('Error: ', error); return; } console.log('Visitor number: ', visitorNumber); });

getUnreadMessagesCount#

This method allows you to get the number of unread messages from the agent.

let count = jivo_api.getUnreadMessagesCount(); console.log('Unread messages count:', count);

getUtm#

This method allows you to get utm tags, if the website url contained them at the time of the visitor's first site visit.

NameTypeDescription
contentstringAd ID
campaignstringThe name of the campaign
sourcestringCampaign source
mediumstringTraffic type
termstringKeyword
let utm = jivo_api.getUtm(); console.log('Utm content: ', utm.content); console.log('Utm campaign: ', utm.campaign); console.log('Utm source: ', utm.source); console.log('Utm medium: ', utm.medium); console.log('Utm term: ', utm.term);

isCallbackEnabled#

This method checks if return calls are available.

jivo_api.isCallbackEnabled(function(apiResult) { if (apiResult.result === 'ok') { jivo_api.open({start: 'call'}); } else { console.log('Callback is not available, reason: ', apiResult.reason); } });

clearHistory#

This method allows to clear THE chat history and all JivoChat data from LocalStorage in the visitor's browser. For example you can use it to delete the chat session data after visitor logs out of his website account.

function jivo_onLoadCallback() { let clearHistory = () => { jivo_api.clearHistory(); console.log('Client data is deleted') }; clearHistory(); };

jivo_init, jivo_destroy#

These methods can be used to display the chat window on the page (jivo_init) or to delete it (jivo_destroy). For example, it can be used in SPA apps if you need to dynamically hide and show the chat widget.

function jivo_onLoadCallback() { jivo_destroy(); console.log('Widget is deleted') }