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" }, }
Параметры ответа
Название | Тип | Описание |
---|---|---|
result | string | Строка результата обработки. Если значение не равно "ок", данные не будут переданы оператору |
custom_data | array | Поля дополнительных данных, аналогично setCustomData |
contact_info | object | Поля контактных данных, аналогично setContactInfo |
enable_assign | boolean | Флаг, определяющий отображению оператору кнопки привязки посетителя к карточке в CRM. Кнопка отображается перед всеми полями custom_data |
crm_link | string | Ссылка на карточку клиента в CRM. Отображается оператору отдельной кнопкой под всеми полями custom_data |
page | object | Информация о странице |
custom_data
Название | Тип | Описание |
---|---|---|
title | string | Название пользовательского поля |
content | string | Содержимое |
contact_info
Название | Тип | Описание |
---|---|---|
name | string | Имя посетителя |
phone необязательный | string | Телефон посетителя |
email необязательный | string | E-mail посетителя |
page
Название | Тип | Описание |
---|---|---|
url | string | URL текущей страницы |
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" }, }
Параметры ответа
Название | Тип | Описание |
---|---|---|
result | string | Строка результата обработки. Если значение не равно "ок", данные не будут переданы оператору |
custom_data | array | Поля дополнительных данных, аналогично setCustomData |
contact_info | object | Поля контактных данных, аналогично setContactInfo |
enable_assign | boolean | Флаг, определяющий отображению оператору кнопки привязки посетителя к карточке в CRM. Кнопка отображается перед всеми полями custom_data |
crm_link | string | Ссылка на карточку клиента в CRM. Отображается оператору отдельной кнопкой под всеми полями custom_data |
page | object | Информация о странице |
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_name | string | Тип события |
widget_id | string | Идентификатор канала связи |
user_token | string | Токен пользователя |
visitor | object | Объект с информацией о посетителе |
organization | object | Объект с информацией о компании, к которой принадлежит клиент |
status | object | Категория клиента |
assigned_agent | object | Данные об ответственном сотруднике |
tags | object | Теги, присвоенные клиенту |
chat_id | number | Идентификатор чата |
department необязательный | object | Объект с информацией об отделе, который посетитель выбрал перед началом чата |
session | object | Данные о сессии пользователя |
page | object | Информация о странице |
call | object | Информация о звонке |
analytics необязательный | object | Аналитика |
agent | object | Объект с информацией об операторе |
chat | object | Сообщения чата |
visitor
Название | Тип | Описание |
---|---|---|
name необязательный | string | Имя посетителя |
email необязательный | string | Email посетителя |
phone необязательный | string | Телефон посетителя |
description | string | Дополнительная информация (описание) по клиенту |
number | string | Номер посетителя |
social необязательный | object | Данные о социальных сетях пользователя |
chats_count | number | Количество обращений |
organization
Название | Тип | Описание |
---|---|---|
id | number | Идентификатор компании |
name | string | Название компании |
status
Название | Тип | Описание |
---|---|---|
id | number | Идентификатор категории клиента |
title | string | Название категории |
assigned_agent
Название | Тип | Описание |
---|---|---|
id | number | Идентификатор ответственного по клиенту сотрудника |
string | Email сотрудника | |
name | string | Имя сотрудника |
tags
Название | Тип | Описание |
---|---|---|
id | number | Идентификатор тега |
title | string | Наименование тега |
department
Название | Тип | Описание |
---|---|---|
id | number | Идентификатор отдела |
name | string | Название отдела |
session
Название | Тип | Описание |
---|---|---|
geoip | object | Данные из geoip клиента |
utm | string | UTM-метки в строковом формате |
utm_json | object | Объект, содержащий UTM-метки |
ip_addr | string | IP-адрес активной сессии |
user_agent | string | Описание user_agent |
page
Название | Тип | Описание |
---|---|---|
url | string | URL текущей страницы |
title необязательный | string | Заголовок страницы |
agent
Название | Тип | Описание |
---|---|---|
id | number | Идентификатор оператора |
string | Email оператора | |
name | string | Имя оператора |
phone необязательный | string | Телефон оператора |
call
Название | Тип | Описание |
---|---|---|
type | string | Tип звонка (callback, incoming, outgoing) |
phone | string | Номер телефона клиента |
status | string | Статус звонка (start, end, agent_connected, client_connected, error) |
reason необязательный | string | Причина ошибки (доступна, когда звонок завершился с ошибкой) |
record_url необязательный | string | Ссылка на запись звонка в формате mp3 (доступна после завершения звонка) |
chat
Название | Тип | Описание |
---|---|---|
messages | object | Объект с сообщениями чата |
blacklisted | boolean | Информация о блокировке пользователя |
rate необязательный | string | Оценка состоявшегося чата |
invitation необязательный | string | Текст активного приглашения |
messages
Название | Тип | Описание |
---|---|---|
message | string | Текст сообщения |
timestamp | int | Метка времени |
type | string | Тип пользователя (оператор или клиент) |
agent_id | number | Идентификатор оператора, который отправил сообщение |
geoip
Название | Тип | Описание |
---|---|---|
region_code | string | Код региона |
country_code | string | ISO код страны |
country | string | Название страны |
region | string | Регион |
city | string | Город |
latitude | string | Широта |
longitude | string | Долгота |
organization | string | Название Интернет-провайдера |
utm_json
Название | Тип | Описание |
---|---|---|
source необязательный | string | Значение utm_source |
campaign необязательный | string | Значение utm_campaign |
content необязательный | string | Значение utm_content |
medium необязательный | string | Значение utm_medium |
term необязательный | string | Значение utm_term |