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, on jivo_onIntroduction event you can get contact details entered by a client.

onLoadCallback

Is executed when Jivo widget initialization is over

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

onOpen

Using this method you can open chat window.

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

onClose

Is executed when chat window is closed

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

onChangeState

Is executed when chat window state is 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

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

onClientStartChat

The chat was started on behalf of the visitor.

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

onIntroduction

Executed when a visitor fills the contacts form

function jivo_onIntroduction() {
    console.log('Client entered contact details');
}

jivo_onAccept

Is executed when an agent presses the Reply button in the notification of a new chat

jivo_onMessageReceived

A new message from the agent is received. Works only with customLabel

jivo_onCallStart

Is executed, when the phone 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

Executed at any change in the size of the widget

jivo_onWidgetDestroy

Called when the widget is completely removed from the page. Triggered when calling jivo_api.jivoInit and jivo_api.jivoDestroy

Methods

API methods allow you to customise chat widget on your website. It 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 right 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 <br/>menu - mobile menu мобильное меню with the selection of communication channel <br/>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 close 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

Use this method to open chat window with custom text at the moment you need. This may be useful if you want to show proactive invitation after the client added goods to cart of your online store. If you want to show invitation immediately when page is open, then you need to call showProactiveInvitation in jivo_onLoadCallback (to initialize that all in the right sequence).

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 used to create gradient

jivo_api.setWidgetColor('#ffffff', '#000000');

chatMode

Using this method you can get the current chat status- online/offline.

NameTypeDescription
resultstringonline - at least on agent is online <br/>offline - no agents are online

let apiResult = jivo_api.chatMode();

if (apiResult.result === 'online') {
    console.log('The widget is online');
} else {
    console.log('Widget offline');
}

startCall

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

Method returns {result: 'ok'} If the phone number is in the correct format and the request to start the call can be made. Otherwise returns {result: 'fail', reason: 'Callback disabled'}, where reason - is about the unsuccessful method call.

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

Using this function you can send an offline message directly. Returns {result: 'ok'} if the passed parameters are correct

Returns {result: 'fail', error: errReason}, where errReason is the validation error of the passed fields, 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 where the client is located 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 of the visitor. The data is displayed to the agent is a same as if a visitor introduced in the chat window. It's a special function to set contact info because name, phone number and e-mail are very important in JivoChat - visitor can introduce himself at the beginning of chat.

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

Using this method you can send any additional info about the client to Jivo app. This info will be shown on the information panel, located on the right side of the app. The method can be called as many times as needed. If chat is established, information in Jivo app will be updated in real time. Fields are shown in the same order 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. By 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

Using this method you can replace the triggers' rules by transferred 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 rules of active invitations 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 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 to 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 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 clears all chat and client data in the browser.

jivo_api.clearHistory();
console.log('All client data deleted');
← OverviewWebhooks API →