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

Webhooks API

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

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

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

call_event

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

Пример:

{ "event_name": "call_event", "chat_id": 4398, "widget_id": "2853", "visitor": { "name": "John Smith", "email": "email@example.com", "phone": "+14084987855", "number": "2746", "description": "Description text", "social": {}, "chats_count": 8 }, "agent": { "id": "3599", "name": "Thomas Anderson", "email": "agent@jivosite.com", "phone": "+14083682346" }, "department": { "id": 181, "name": "Sales" }, "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": "source=google|medium=cpc|content=banner|campaign=campaign_name", "utm_json": { "source": "google", "campaign": "campaign_name", "content": "banner", "medium": "cpc", "term": "..." }, "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" }, "page": { "url": "http://example.com/", "title": "Page title" }, "call": { "type": "callback", "phone": "+14084987855", "status": "end", "record_url": "http://example.com/record.mp3" }, "analytics": {} }

chat_accepted

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

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

Пример

{ "event_name": "chat_accepted", "widget_id": "3948", "user_token": null, "visitor": { "name": "John Smith", "email": "email@example.com", "phone": "+14084987855", "description": "Description text", "number": "2198", "social": {}, "chats_count": 1 }, "organization": { "id": "1", "name": "Company name" }, "status": { "id": "4", "title": "contact_later" }, "assigned_agent": { "id": 1, "email": "agent1@gmail.com", "name": "Agent" }, "tags": [ { "id": "17", "title": "Tag example" } ], "chat_id": 7636, "department": { "id": 281, "name": "Sales" }, "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": "source=google|medium=cpc|content=banner|campaign=campaign_name", "utm_json": { "source": "google", "campaign": "campaign_name", "content": "banner", "medium": "cpc", "term": "..." }, "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" }, "page": { "url": "http://example.com/", "title": "Page title" }, "analytics": {}, "agent": { "id": "2016", "name": "Thomas Anderson", "email": "agent@jivosite.com", "phone": "+14083682346" }, }

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

НазваниеТипОписание
resultstringСтрока результата обработки. Если значение не равно "ок", данные не будут переданы оператору
custom_dataarrayПоля дополнительных данных, аналогично setCustomData
contact_infoobjectПоля контактных данных, аналогично setContactInfo
enable_assignbooleanФлаг, определяющий отображению оператору кнопки привязки посетителя к карточке в CRM. Кнопка отображается перед всеми полями custom_data
crm_linkstringСсылка на карточку клиента в CRM. Отображается оператору отдельной кнопкой под всеми полями custom_data
pageobjectИнформация о странице

custom_data

НазваниеТипОписание
titlestringНазвание пользовательского поля
contentstringСодержимое

contact_info

НазваниеТипОписание
namestringИмя посетителя
phone необязательныйstringТелефон посетителя
email необязательныйstringE-mail посетителя

page

НазваниеТипОписание
urlstringURL текущей страницы
title необязательныйstringЗаголовок страницы

Пример

{ "result": "ok", "custom_data": [ { "title": "Title", "content": "Content text" } ], "contact_info": { "name": "John Smith", "phone": "+14084987855", "email": "email@example.com" }, "page": { "url": "http://example.com/", "title": "Page title" } }

chat_assigned

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

Пример:

{ "event_name": "chat_assigned", "widget_id": "3948", "user_token": null, "visitor": { "name": "John Smith", "email": "email@example.com", "phone": "+14084987855", "number": "2198", "description": "Description text", "social": {}, "chats_count": 1 }, "organization": { "id": "1", "name": "Company name" }, "status": { "id": "4", "title": "contact_later" }, "assigned_agent": { "id": 1, "email": "agent1@gmail.com", "name": "Agent" }, "tags": [], "chat_id": 1207, "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": "source=google|medium=cpc|content=banner|campaign=campaign_name", "utm_json": { "source": "google", "campaign": "campaign_name", "content": "banner", "medium": "cpc", "term": "..." }, "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" }, "page": { "url": "http://example.com/", "title": "Page title" }, "analytics": {}, "agent": { "id": "2016", "name": "Thomas Anderson", "email": "agent@jivosite.com", "phone": "+14083682346" }, "assign_to": "https://test-crm.com", }

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

В качестве ответа ожидается только JSON {"result": "ok"} или текст ошибки.

Пример

{ "result": "ok" }

chat_updated

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

Пример

{ "event_name": "chat_updated", "widget_id": "3948", "user_token": null, "visitor": { "name": "John Smith", "email": "email@example.com", "phone": "+14084987855", "description": "Description text", "number": "2198", "chats_count": 1 }, "organization": { "id": "2", "name": "Company name" }, "status": { "id": "4", "title": "contact_later" }, "assigned_agent": null, "tags": [ { "id": "7", "title": "Discount" } ], "chat_id": 7507, "department": { "id": 281, "name": "Sales" }, "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": "source=google|medium=cpc|content=banner|campaign=campaign_name", "utm_json": { "source": "google", "campaign": "campaign_name", "content": "banner", "medium": "cpc", "term": "..." }, "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" }, "page": { "url": "http://example.com/", "title": "Page title" }, "analytics": {}, "agent": { "id": "2016", "name": "Thomas Anderson", "email": "agent@jivosite.com", "phone": "+14083682346" }, }

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

НазваниеТипОписание
resultstringСтрока результата обработки. Если значение не равно "ок", данные не будут переданы оператору
custom_dataarrayПоля дополнительных данных, аналогично setCustomData
contact_infoobjectПоля контактных данных, аналогично setContactInfo
enable_assignbooleanФлаг, определяющий отображению оператору кнопки привязки посетителя к карточке в CRM. Кнопка отображается перед всеми полями custom_data
crm_linkstringСсылка на карточку клиента в CRM. Отображается оператору отдельной кнопкой под всеми полями custom_data
pageobjectИнформация о странице

client_updated

Отправку события инициирует обновление данных клиента. Например, в карточке клиента был обновлен ответственный сотрудник или организация, к которой относится клиент. Также событие будет отправлено, если были изменены контактные данные клиента вне принятого диалога с ним (в разделе "CRM" - "Клиенты").

Пример

{ "event_name": "client_updated", "widget_id": "12345678", "user_token": null, "visitor": { "name": "Thomas", "email": "thomas@gmail.com", "phone": "+458745457845", "description": "Description text", "number": 1217, "chats_count": 1 }, "organization": { "id": "1", "name": "Company name" }, "status": { "id": "4", "title": "contact_later" }, "assigned_agent": { "id": 3, "email": "agent3@gmail.com", "name": "Agent3" }, "tags": [ { "id": "17", "title": "Sales" } ], "client_id": "1217" }

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

В качестве ответа ожидается только JSON {"result": "ok"} или текст ошибки.

Пример

{ "result": "ok" }

chat_finished

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

Пример

{ "event_name": "chat_finished", "widget_id": "3948", "visitor": { "name": "John Smith", "email": "email@example.com", "phone": "+14084987855", "description": "Description text", "number": "2198", "chats_count": 2 }, "organization": null, "status": null, "assigned_agent": null, "tags": [], "chat_id": 7607, "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": "source=google|medium=cpc|content=banner|campaign=campaign_name", "utm_json": { "source": "google", "campaign": "campaign_name", "content": "banner", "medium": "cpc", "term": "..." }, "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" }, "page": { "url": "http://example.com/", "title": "Page title" }, "analytics": null, "agents": [ { "id": "2016", "name": "Thomas Anderson", "email": "agent@jivosite.com", "phone": "+14083682346" } ], "chat": { "messages": [ { "message": "<Message text is not displayed here>", "timestamp": 1665396476, "type": "visitor" }, { "message": "<Message text is not displayed here>", "timestamp": 1665396483, "type": "agent", "agent_id": 1 } ], "blacklisted": false, "rate": null }, "plain_messages": "", "html_messages": "" }

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

В качестве ответа ожидается только JSON {"result": "ok или текст ошибки"}

Пример

{ "result": "ok" }

offline_message

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

Пример

{ "event_name": "offline_message", "widget_id": "3948", "user_token": null, "visitor": { "name": "John Smith", "email": "email@example.com", "phone": "+14084987855", "description": "Description text", "number": "2198", "chats_count": 1 }, "organization": null, "status": null, "assigned_agent": null, "tags": [], "chat_id": 2026, "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": "source=google|medium=cpc|content=banner|campaign=campaign_name", "utm_json": { "source": "google", "campaign": "campaign_name", "content": "banner", "medium": "cpc", "term": "..." }, "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" }, "page": { "url": "http://example.com/", "title": "Page title" }, "analytics": {}, "message": "Message text", "offline_message_id": 1665399500726 }

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

В качестве ответа ожидается только JSON {"result": "ok} или текст ошибки.

Пример

{ "result": "ok" }

Параметры события

event

НазваниеТипОписание
event_namestringТип события
widget_idstringИдентификатор канала связи
user_tokenstringТокен пользователя
visitorobjectОбъект с информацией о посетителе
organizationobjectОбъект с информацией о компании, к которой принадлежит клиент
statusobjectКатегория клиента
assigned_agentobjectДанные об ответственном сотруднике
tagsobjectТеги, присвоенные клиенту
chat_idnumberИдентификатор чата
department необязательныйobjectОбъект с информацией об отделе, который посетитель выбрал перед началом чата
sessionobjectДанные о сессии пользователя
pageobjectИнформация о странице
callobjectИнформация о звонке
analytics необязательныйobjectАналитика
agentobjectОбъект с информацией об операторе
chatobjectСообщения чата

visitor

НазваниеТипОписание
name необязательныйstringИмя посетителя
email необязательныйstringEmail посетителя
phone необязательныйstringТелефон посетителя
descriptionstringДополнительная информация (описание) по клиенту
numberstringНомер посетителя
social необязательныйobjectДанные о социальных сетях пользователя
chats_countnumberКоличество обращений

organization

НазваниеТипОписание
idnumberИдентификатор компании
namestringНазвание компании

status

НазваниеТипОписание
idnumberИдентификатор категории клиента
titlestringНазвание категории

assigned_agent

НазваниеТипОписание
idnumberИдентификатор ответственного по клиенту сотрудника
emailstringEmail сотрудника
namestringИмя сотрудника

tags

НазваниеТипОписание
idnumberИдентификатор тега
titlestringНаименование тега

department

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

session

НазваниеТипОписание
geoipobjectДанные из geoip клиента
utmstringUTM-метки в строковом формате
utm_jsonobjectОбъект, содержащий UTM-метки
ip_addrstringIP-адрес активной сессии
user_agentstringОписание user_agent

page

НазваниеТипОписание
urlstringURL текущей страницы
title необязательныйstringЗаголовок страницы

agent

НазваниеТипОписание
idnumberИдентификатор оператора
emailstringEmail оператора
namestringИмя оператора
phone необязательныйstringТелефон оператора

call

НазваниеТипОписание
typestringTип звонка (callback, incoming, outgoing)
phonestringНомер телефона клиента
statusstringСтатус звонка (start, end, agent_connected, client_connected, error)
reason необязательныйstringПричина ошибки (доступна, когда звонок завершился с ошибкой)
record_url необязательныйstringСсылка на запись звонка в формате mp3 (доступна после завершения звонка)

chat

НазваниеТипОписание
messagesobjectОбъект с сообщениями чата
blacklistedbooleanИнформация о блокировке пользователя
rate необязательныйstringОценка состоявшегося чата
invitation необязательныйstringТекст активного приглашения

messages

НазваниеТипОписание
messagestringТекст сообщения
timestampintМетка времени
typestringТип пользователя (оператор или клиент)
agent_idnumberИдентификатор оператора, который отправил сообщение

geoip

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

utm_json

НазваниеТипОписание
source необязательныйstringЗначение utm_source
campaign необязательныйstringЗначение utm_campaign
content необязательныйstringЗначение utm_content
medium необязательныйstringЗначение utm_medium
term необязательныйstringЗначение utm_term