JivoSite API для разработчиков

JivoSite предоставляет разработчикам два набора инструментов для интеграции:

Клиентская часть - Javascript API виджета, позволяющее управлять виджетом, который отображается пользователю. С помощью него можно управлять окном чата, а так же передавать произвольную информацию со страницы, на которой размещено окно чата, в приложение оператора (например, можно передать дополнительную информацию о пользователе, которая так же будет сохранена в журнале диалогов).

Серверная часть - Webhooks API, позволяющее получать уведомления о начале или завершении чата на стороне вашего сервера, а так же передавать в JivoSite дополнительную информацию для отображения в приложени оператора в ответе на HTTP-запросы.

JavaScript API

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

Callback-функции

НазваниеТипОписание
jivo_onLoadCallbackfunctionВызывается при завершении инициализации виджета JivoSite
jivo_onOpenfunctionВызывается при открытии окна диалога JivoSite
jivo_onMessageSentfunctionПосетитель отправил первое сообщение в чат
jivo_onAcceptfunctionОператор нажал кнопку Ответить в уведомлении о новом чате
jivo_onClosefunctionСворачивание окна диалога JivoSite
jivo_onIntroductionfunctionПосетитель ввёл контактные данные
jivo_onResizeCallbackfunctionКоллбек, срабатывающий при любом изменении размеров виджета
jivo_onAcceptfunctionОператор нажал кнопку Ответить в уведомлении о новом чате

JavaScript API - open

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

JavaScript API - chatMode

С помощью этого метогода можно получить текущее состояние операторов.

JavaScript API - getContactInfo

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

JavaScript API - getVisitorNumber

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

JavaScript API - setContactInfo

Устанавливает контактные данные посетителя. Данные отображаются оператору, как будто их ввел посетитель в форме представления. Для записи контактных данные представляется отдельная функция, т.к. имя, телефон и e-mail клиента играют особенную роль в JivoSite - эти данные может указать клиент сам при начале диалога.

Параметры

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

JavaScript API - setCustomData

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

Вызов метода setCustomData является наиболее простым способом передать оператору дополнительную информацию о посетителе. Но нужно иметь ввиду, что данные, передаваемые оператору таким образом, не могут считаться доверенными - используя отладочные инструменты браузера, злоумышленник может их подделать. Для организации более надежной передачи информации в случае, если нужна гарантия безопасности, советуем использовать метод setUserToken и Webhooks.

Для исключения возможности направления оператора на посторонние сайты в Web-кабинете администратора необходимо настроить URL с которого могут начинаться ссылки в дополнительных полях (раздел Настройки - Настройка интеграции для разработчиков - Безопасный URL). Все другие ссылки будут заблокированы, оператор их не увидит.

Параметры

НазваниеТипОписание
fieldsarrayСписок полей диалога

field

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

JavaScript API - setRules

С помощью этого метогода можно заменить автоматические действия на переданный объект.

Параметры

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

JavaScript API - setUserToken

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

Параметры

НазваниеТипОписание
tokenstringИдентификатор посетителя

JavaScript API - showProactiveInvitation

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

Параметры

НазваниеТипОписание
invitation_textstringТекст приглашения
department_idnumberИдентификатор отдела
 jivo_api.showProactiveInvitation("Can I help you?"); 

Webhooks

Используйте Webhooks для того, что бы получать уведомления при возникновении различных событий, связанных с обращениями посетителей сайта через виджет JivoSite.

В Web-кабинете администратора может быть настроен HTTP(S) URL, на который будет отправляться запрос при возникновении того или иного события. Событие передается по указанному URL POST-запросом. Тело запроса представляет собой JSON-объект с информацией о событии.

Тип события определяется строковым полем event_name, который всегда присутствует в структуре event. Остальные поля зависят от конкретного события. В ответ на HTTP-запрос для некоторых типов событий вы можете вернуть данные, которые будут отображены оператору, принявшему диалог.

Webhooks - chat_accepted

Событие возникает в момент приема запроса диалога оператором. В параметрах запроса передаются все известные данные о посетителе, а так данные оператора, принявшего диалог. Кроме того, в параметрах присутствует идентификатор пользователя, если он был передан в виджет путем вызова jivo_api.setUserToken.

При возврате в ответе на chat_accepted объекта contact_info, все поля из него будут показаны оператору так, как будто их ввёл посетитель. Они же сохранятся в журнале диалога и письме.

Параметры

НазваниеТипОписание
event_namestringТип события. По умолчанию: chat_accepted
chat_idnumberИдентификатор чата
visitorobjectОбъект с информацией о посетителе
agentobjectОбъект с информацией об операторе
sessionobjectДанные о сессий пользователя

visitor

НазваниеТипОписание
namestringИмя посетителя
emailstringEmail посетителя
phonestringТелефон посетителя
numberstringНомер посетителя
descriptionstringДополнительная информтация по клиенту
socialobjectДанные о социальных сетях пользователя
chats_countnumberКоличество обращений

agent

НазваниеТипОписание
idstringИдентификатор оператора
namestringИмя оператора
emailstringEmail оператора
phonestringТелефон посетителя
numberstringНомер посетителя

session

НазваниеТипОписание
geoipobjectДанные из geoip
utmstringUTM
ip_addrstringIP аддрес активной сессий
user_agentstringОписание user_agent

geoip

НазваниеТипОписание
region_codestringКод региона
countrystringНазвание страны
country_codestringISO код страны
regionstringРегион
citystringГород
regionstringРегион
latitudestringШирота
longitudestringДолгота
organizationstringНазвание организации

Параметры ответа

НазваниеТипОписание
resultstringСтрока результата обработки. Если значение не равно “ок”, данные не будут переданы оператору
custom_dataarrayПоля дополнительных данных, аналогично setCustomData
contact_infocontact_infoПоля контактных данных, аналогично setContactInfo
enable_assignbooleanФлаг, определяющий отображению оператору кнопки привязки посетителя к карточке в CRM. Кнопка отображается перед всеми полями custom_data.
crm_linkstringСсылка на карточку клиента в CRM. Отображается оператору отдельной кнопкой под всеми полями custom_data.
 event = {
    "event_name": "chat_accepted",
    "chat_id": 1443,
    "visitor": {
        "name": "John Smith",
        "email": "email@example.com",
        "phone": "+14084987855",
        "number": "...",
        "description": "Description text",
        "social": {},
        "chats_count": 7
    },
    "agent": {
        "id": "...",
        "name": "Thomas Anderson",
        "email": "agent@jivosite.com",
        "phone": "+14083682346",
        "number": "..."
    },
    "session": {
        "geoip": {
            "region_code": "CA",
            "country": "United States",
            "country_code": "US",
            "region": "California",
            "city": "San Francisco",
            "latitude": "37.7898",
            "longitude": "-122.3942",
            "organization": "Wikimedia Foundation"
        },
        "utm": "...",
        "ip_addr": "208.80.152.201",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.71 Safari/537.36"
    }
} 

В ответ ожидается строка, содержащая JSON:

 {
    "result": "ok",
    "custom_data": [
        {
            "title": "Title",
            "content": "Content text"
        }
    ],
    "contact_info": {
        "name": "John Smith",
        "phone": "+14084987855"
    },
    "enable_assign": true,
    "crm_link": "http://mycrm.ru/user/1"
} 

Webhooks - chat_assigned

Параметры

НазваниеТипОписание
event_namestringТип события. По умолчанию: chat_assigned
chat_idnumberИдентификатор чата
visitorobjectОбъект с информацией о посетителе
agentobjectОбъект с информацией об операторе
assign_tostringКому назначен был чат
sessionobjectДанные о сессий пользователя

visitor

НазваниеТипОписание
namestringИмя посетителя
emailstringEmail посетителя
phonestringТелефон посетителя
numberstringНомер посетителя
descriptionstringДополнительная информтация по клиенту
socialobjectДанные о социальных сетях пользователя
chats_countnumberКоличество обращений

agent

НазваниеТипОписание
idstringИдентификатор оператора
namestringИмя оператора
emailstringEmail оператора
phonestringТелефон посетителя
numberstringНомер посетителя

session

НазваниеТипОписание
geoipobjectДанные из geoip
utmstringUTM
ip_addrstringIP аддрес активной сессий
user_agentstringОписание user_agent

geoip

НазваниеТипОписание
region_codestringКод региона
countrystringНазвание страны
country_codestringISO код страны
regionstringРегион
citystringГород
regionstringРегион
latitudestringШирота
longitudestringДолгота
organizationstringНазвание организации
 event = {
    "event_name": "chat_assigned",
    "chat_id": 5981,
    "visitor": {
        "name": "John Smith",
        "email": "email@example.com",
        "phone": "+14084987855",
        "number": "...",
        "description": "Description text",
        "social": {},
        "chats_count": 7
    },
    "agent": {
        "id": "...",
        "name": "Thomas Anderson",
        "email": "agent@jivosite.com",
        "phone": "+14083682346",
        "number": "..."
    },
    "assign_to": "...",
    "session": {
        "geoip": {
            "region_code": "CA",
            "country": "United States",
            "country_code": "US",
            "region": "California",
            "city": "San Francisco",
            "latitude": "37.7898",
            "longitude": "-122.3942",
            "organization": "Wikimedia Foundation"
        },
        "utm": "...",
        "ip_addr": "208.80.152.201",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.71 Safari/537.36"
    }
} 

Webhooks - chat_finished

Параметры

НазваниеТипОписание
event_namestringТип события. По умолчанию: chat_finished
chat_idnumberИдентификатор чата
visitorobjectОбъект с информацией о посетителе
agentobjectОбъект с информацией об операторе
chatobjectДанные о завершенном чате
sessionobjectДанные о сессий пользователя

visitor

НазваниеТипОписание
namestringИмя посетителя
emailstringEmail посетителя
phonestringТелефон посетителя
numberstringНомер посетителя
descriptionstringДополнительная информтация по клиенту
socialobjectДанные о социальных сетях пользователя
chats_countnumberКоличество обращений

agent

НазваниеТипОписание
idstringИдентификатор оператора
namestringИмя оператора
emailstringEmail оператора
phonestringТелефон посетителя
numberstringНомер посетителя

chat

НазваниеТипОписание
messagesarrayМассив сообщений чата
ratestringПользовательская оценка чата (positive|negative|null)
blacklistedbooleanПризнак того, что пользователь был добавлен в черный список

session

НазваниеТипОписание
geoipobjectДанные из geoip
utmstringUTM
ip_addrstringIP аддрес активной сессий
user_agentstringОписание user_agent

message

НазваниеТипОписание
timestampnumberВремя получения сообщение (timestamp)
typestringТип сообщения (visitor - сообщение от клиента, agent - сообщение от агента)
agent_idnumberИдентификатор агента, который ответил сообщение (существует, только если type=agent)
messagestringТекст сообщения

geoip

НазваниеТипОписание
region_codestringКод региона
countrystringНазвание страны
country_codestringISO код страны
regionstringРегион
citystringГород
regionstringРегион
latitudestringШирота
longitudestringДолгота
organizationstringНазвание организации
 event = {
    "event_name": "chat_finished",
    "chat_id": 2879,
    "visitor": {
        "name": "John Smith",
        "email": "email@example.com",
        "phone": "+14084987855",
        "number": "...",
        "description": "Description text",
        "social": {},
        "chats_count": 7
    },
    "agent": {
        "id": "...",
        "name": "Thomas Anderson",
        "email": "agent@jivosite.com",
        "phone": "+14083682346",
        "number": "..."
    },
    "chat": {
        "messages": [
            {
                "timestamp": 1431955090,
                "type": "agent",
                "agent_id": 5504,
                "message": "Message text"
            }
        ],
        "rate": "positive",
        "blacklisted": false
    },
    "session": {
        "geoip": {
            "region_code": "CA",
            "country": "United States",
            "country_code": "US",
            "region": "California",
            "city": "San Francisco",
            "latitude": "37.7898",
            "longitude": "-122.3942",
            "organization": "Wikimedia Foundation"
        },
        "utm": "...",
        "ip_addr": "208.80.152.201",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.71 Safari/537.36"
    }
} 

Webhooks - chat_updated

Параметры

НазваниеТипОписание
event_namestringТип события. По умолчанию: chat_updated
chat_idnumberИдентификатор чата
visitorobjectОбъект с информацией о посетителе
agentobjectОбъект с информацией об операторе
sessionobjectДанные о сессий пользователя

visitor

НазваниеТипОписание
namestringИмя посетителя
emailstringEmail посетителя
phonestringТелефон посетителя
numberstringНомер посетителя
descriptionstringДополнительная информтация по клиенту
socialobjectДанные о социальных сетях пользователя
chats_countnumberКоличество обращений

agent

НазваниеТипОписание
idstringИдентификатор оператора
namestringИмя оператора
emailstringEmail оператора
phonestringТелефон посетителя
numberstringНомер посетителя

session

НазваниеТипОписание
geoipobjectДанные из geoip
utmstringUTM
ip_addrstringIP аддрес активной сессий
user_agentstringОписание user_agent

geoip

НазваниеТипОписание
region_codestringКод региона
countrystringНазвание страны
country_codestringISO код страны
regionstringРегион
citystringГород
regionstringРегион
latitudestringШирота
longitudestringДолгота
organizationstringНазвание организации
 event = {
    "event_name": "chat_updated",
    "chat_id": 4387,
    "visitor": {
        "name": "John Smith",
        "email": "email@example.com",
        "phone": "+14084987855",
        "number": "...",
        "description": "Description text",
        "social": {},
        "chats_count": 7
    },
    "agent": {
        "id": "...",
        "name": "Thomas Anderson",
        "email": "agent@jivosite.com",
        "phone": "+14083682346",
        "number": "..."
    },
    "session": {
        "geoip": {
            "region_code": "CA",
            "country": "United States",
            "country_code": "US",
            "region": "California",
            "city": "San Francisco",
            "latitude": "37.7898",
            "longitude": "-122.3942",
            "organization": "Wikimedia Foundation"
        },
        "utm": "...",
        "ip_addr": "208.80.152.201",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.71 Safari/537.36"
    }
} 

Webhooks - offline_message

Параметры

НазваниеТипОписание
event_namestringТип события. По умолчанию: offline_messages
chat_idnumberИдентификатор чата
visitorobjectОбъект с информацией о посетителе
offline_message_idstringИдентификатор offline сообщения
messagestringСообщение
sessionobjectДанные о сессий пользователя

visitor

НазваниеТипОписание
namestringИмя посетителя
emailstringEmail посетителя
phonestringТелефон посетителя
numberstringНомер посетителя
descriptionstringДополнительная информтация по клиенту
socialobjectДанные о социальных сетях пользователя
chats_countnumberКоличество обращений

session

НазваниеТипОписание
geoipobjectДанные из geoip
utmstringUTM
ip_addrstringIP аддрес активной сессий
user_agentstringОписание user_agent

geoip

НазваниеТипОписание
region_codestringКод региона
countrystringНазвание страны
country_codestringISO код страны
regionstringРегион
citystringГород
regionstringРегион
latitudestringШирота
longitudestringДолгота
organizationstringНазвание организации
 event = {
    "event_name": "offline_message",
    "chat_id": 8008,
    "visitor": {
        "name": "John Smith",
        "email": "email@example.com",
        "phone": "+14084987855",
        "number": "...",
        "description": "Description text",
        "social": {},
        "chats_count": 7
    },
    "offline_message_id": "...",
    "message": "Message text",
    "session": {
        "geoip": {
            "region_code": "CA",
            "country": "United States",
            "country_code": "US",
            "region": "California",
            "city": "San Francisco",
            "latitude": "37.7898",
            "longitude": "-122.3942",
            "organization": "Wikimedia Foundation"
        },
        "utm": "...",
        "ip_addr": "208.80.152.201",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.71 Safari/537.36"
    }
}