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.

Name	Type	Description
state	string	Current 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.

Name	Type	Description
result optional	object	The 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.

Name	Type	Description
start optional	string	call - 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.

Name	Type	Description
invitation_text	string	Invitation text
department_id optional	number	Department id

jivo_api.showProactiveInvitation("How can I help you?", 3);

setWidgetColor#

This method allows you to change the widget color.

Name	Type	Description
color	string	Hexadecimal color code
color2 optional	string	Hexadecimal 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.

Name	Type	Description
result	string	online - 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.

Name	Type	Description
phone	string	Phone 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.

Name	Type	Description
name	string	Client's name
email	string	Client's email
phone	string	Client's phone number
description	string	Additional information about the client
message	string	Offline 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.

Name	Type	Description
title	string	Ad ID
fromApi optional	string	Campaign name
url optional	string	Campaign 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.

Name	Type	Description
name	string	Client's name сайта
email	string	Client's email
phone	string	Client's phone number
description	string	Additional 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.

Name	Type	Description
fields	array	List of additional data fields of the chat
fields.content	string	Content of data field. Tags will be insulated
fileds.title	string	Title shown above a data field
fileds.link	string	URL that opens when the data field is clicked
fileds.key	string	Description 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.

Name	Type	Description
token	string	Visitor 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.

Name	Type	Description
rules	object	Description 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.

Name	Type	Description
client_name	string	Client's name
email	string	Client's email
phone	string	Client's phone number
description	string	Additional 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.

Name	Type	Description
err	string	String that contains the error
visitorNumber	integer	Visitor'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.

Name	Type	Description
content	string	Ad ID
campaign	string	The name of the campaign
source	string	Campaign source
medium	string	Traffic type
term	string	Keyword

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')
}