Документация

Widget API

Callback-функции

Jivo вызывает перечисленные ниже функции на странице, чтобы сообщить о возникновении события. Вы можете объявить на странице любую из этих функций и выполнять в ней логику обработки возникшего события. Например, по событию jivo_onIntroduction вы можете получить введенные клиентом контактные данные.

onLoadCallback

Вызывается при завершении инициализации виджета Jivo.

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

onOpen

Вызывается при открытии окна диалога Jivo: как при автоматическом открытии, так и если виджет был открыт вручную.

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

onClose

Вызывается при сворачивании окна диалога Jivo.

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

onChangeState

Вызывается при переключении виджета из одного состояния в другое.

НазваниеТипОписание
statestringСостояние виджета
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

Посетитель отправил первое сообщение в виджет, срабатывает только один раз, когда история сообщений пуста.

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

onClientStartChat

Пользователь инициировал диалог, отправив сообщение в чат. Сработает в случае, если ранее в чате не появлялось активное приглашение от лица оператора.

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

onIntroduction

Посетитель отправил контактные данные в чате. Эту функцию можно использовать для отслеживания отправки контактов со стороны клиента для последующей передачи этих данных в другие формы на сайте.

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

jivo_onAccept

Оператор принял входящий чат или инициировал диалог с посетителем из раздела "Посетители"/"Все диалоги".

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

jivo_onMessageReceived

От оператора поступило новое сообщение в чат. Можно использовать как при работе со стандартным ярлыком чата, так и для кастомизации своей иконки виджета. Пример: можно отображать счётчик непрочитанных сообщений от оператора пользователю, используя эту функцию.

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

jivo_onCallStart

Вызывается при начале звонка на клиентский номер. Звонок может заказать клиент через форму обратного звонка, также звонок можно инициировать программно при помощи метода jivo_api.startCall().

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

jivo_onCallEnd

Пример вызова функции с возвращаемым параметром. Вызывается при окончании звонка с результатом звонка:

НазваниеТипОписание
result необязательныйobjectРезультат вызова
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

Функция срабатывает при изменении размеров виджета: его открытии, закрытии или перемещении по странице пользователем. Может использоваться для динамического добавления или скрытия других элементов на сайте.

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

jivo_onWidgetDestroy

Вызывается при полном удалении виджета со страницы. Срабатывает при вызове метода jivo_destroy().

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

Методы

С помощью методов API можно кастомизировать виджет, получить или установить дополнительную информацию по клиентам. Вызов методов необходимо производить из коллбека jivo_onLoadCallback, чтобы все проинициализировалось в правильном порядке.

open

Метод позволяет открыть окно чата в различных состояниях.

НазваниеТипОписание
start необязательныйstringcall - окно с формой обратного звонка <br> menu - мобильное меню с выбором канала связи <br> chat - Значение по умолчанию
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

Метод позволяет закрыть или свернуть окно диалога.

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

showProactiveInvitation

С помощью этого метода вы можете вызвать окно активного приглашения в нужный момент. Это может быть полезно, например, если вы хотите показывать активное приглашение после того, как клиент добавил товар в корзину Интернет-магазина.

НазваниеТипОписание
invitation_textstringТекст приглашения
department_id необязательныйnumberИдентификатор отдела
jivo_api.showProactiveInvitation("How can I help you?", 3);

setWidgetColor

Данный метод позволяет изменить цвет виджета.

НазваниеТипОписание
colorstringШестнадцатеричный код цвета
color2 необязательныйstringШестнадцатеричный код цвета, используется для создания градиента
jivo_api.setWidgetColor('#ffffff', '#000000');

chatMode

С помощью этого метода можно получить текущий статус чата: онлайн/оффлайн.

НазваниеТипОписание
resultstringonline - минимум один оператор в сети <br>offline - операторов нет в сети
function jivo_onLoadCallback() { let chatMode = jivo_api.chatMode(); if (chatMode === 'offline') { console.log("Widget is offline"); } else { console.log('Widget is online') } }

startCall

Метод позволяет начать звонок на определенный номер, если звонки доступны (Обратный звонок настроен и баланс звонков положителен).

НазваниеТипОписание
phonestringТелефон
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

Данный метод позволяет отправить сообщение и предзаполнить форму контактов в офлайн-режиме чата (для отправки сообщения посетителю сайта необходимо вручную отправить форму контактов).

НазваниеТипОписание
namestringИмя клиента
emailstringEmail клиента
phonestringТелефон клиента
descriptionstringДополнительная информация о клиенте
messagestringТекст оффлайн-сообщения
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

Обновляет в программе оператора заголовок и url страницы, на которой находится клиент, полезно для SPA-приложений.

НазваниеТипОписание
titlestringИдентификатор объявления
fromApi необязательныйstringНазвание кампании
url необязательныйstringИсточник кампании
let title = 'This is custom page title'; let url = 'https://site.com/url_to_page?q=params'; jivo_api.sendPageTitle(title, true, url);

setContactInfo

Устанавливает контактные данные посетителя. Данные отображаются оператору, как будто их ввел посетитель в форме контактов.

НазваниеТипОписание
namestringИмя посетителя сайта
emailstringEmail посетителя сайта
phonestringНомер телефона посетителя сайта
descriptionstringДополнительная информация по клиенту (отобразится в поле "Описание" - раздел "О клиенте")
jivo_api.setContactInfo({ name: "John Smith", email: "email@example.com", phone: "+14084987855", description: "Description text" });

setCustomData

С помощью этой функции можно передать произвольную дополнительную информацию о клиенте оператору. Информация отображается в информационной панели справа в приложении оператора. Метод может быть вызван любое число раз - если диалог с оператором уже установлен, то данные в приложении оператора будут обновлены в реальном времени. Поля выводятся в порядке их следования в массиве fields.

НазваниеТипОписание
fieldsarrayСписок полей диалога
fields.contentstringСодержимое поля данных. Теги экранируются
fields.titlestringЗаголовок, добавляемый сверху поля данных
fields.linkstringURL, открываемый при клике на поле данных
fields.keystringОписание поля данных, добавляемое жирным шрифтом перед содержимым поля через двоеточие
jivo_api.setCustomData([ { "content": "User balance: $56", }, { "content": "Open customer profile", "link": "..." }, { "title": "Actions", "content": "Add contact", "link": "..." } ]);

setUserToken

Устанавливает идентификатор посетителя. Jivo никак не обрабатывает этот идентификатор и не отображает его в приложении оператора, но передаёт его в каждом событии Webhooks. Таким образом можно идентифицировать посетителя сайта при обработке Webhooks. Рекомендуем использовать сложно-угадываемый идентификатор для исключения возможности спуфинга.

НазваниеТипОписание
tokenstringИдентификатор посетителя
jivo_api.setUserToken(token);

setRules

С помощью этого метода можно заменить автоматические действия на переданный объект. Пример объекта можно сформировать в панели управления Jivo, открыв раздел Автоматические действия и нажав кнопку JSON структура.

НазваниеТипОписание
rulesobjectОписание правил активных приглашений на языке JSON
jivo_api.setRules(rules);

getContactInfo

Возвращает данные посетителя, которые посетитель ввел в форме представления. Если посетитель не заполнил какие-либо поля, их значении будут равны null.

НазваниеТипОписание
client_namestringИмя посетителя сайта
emailstringEmail посетителя сайта
phonestringНомер телефона посетителя сайта
descriptionstringДополнительная информация по клиенту, установленная в 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

Асинхронная функция для получения уникального номера посетителя в Jivo. Посетители нумеруются последовательно, начиная с 1, число постоянно растет. Номер посетителя отображается в программе оператора и в журнала и может использоваться для связи данных Jivo с данными CRM.

НазваниеТипОписание
errstringСтрока с ошибкой
visitorNumberintegerНомер посетителя
jivo_api.getVisitorNumber(function(error, visitorNumber) { if (error) { console.log('Error: ', error); return; } console.log('Visitor number: ', visitorNumber); });

getUnreadMessagesCount

Данный метод позволяет получить количество непрочитанных сообщений от оператора.

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

getUtm

Данный метод позволяет получить utm-метки, если они были при первом переходе клиента на сайт.

НазваниеТипОписание
contentstringИдентификатор объявления
campaignstringНазвание кампании
sourcestringИсточник кампании
mediumstringТип трафика
termstringКлючевое слово
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

Данный метод проверяет, доступны ли звонки.

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

Метод jivo_api.clearHistory() позволяет удалить историю чата и данные пользователя из локального хранилища браузера пользователя. Применимо в случае, если необходимо очищать данные сессии при деавторизации из кабинета на сайте.

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

jivo_init, jivo_destroy

Указанные методы можно использовать для отображения виджета Jivo (jivo_init) или его удаления со страницы (jivo_destroy). Например, в SPA-приложениях, если необходимо динамически скрывать или отображать чат на странице.

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