Webhooks API · JivoSite 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",
    "chat_id": 7636,
    "widget_id": "3948",
    "visitor": {
        "name": "John Smith",
        "email": "email@example.com",
        "phone": "+14084987855",
        "number": "2198",
        "description": "Description text",
        "social": {},
        "chats_count": 1
    },
    "agent": {
        "id": "2016",
        "name": "Thomas Anderson",
        "email": "agent@jivosite.com",
        "phone": "+14083682346"
    },
    "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": {}
}

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

Название	Тип	Описание
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",
    "chat_id": 1207,
    "widget_id": "3948",
    "visitor": {
        "name": "John Smith",
        "email": "email@example.com",
        "phone": "+14084987855",
        "number": "2198",
        "description": "Description text",
        "social": {},
        "chats_count": 1
    },
    "agent": {
        "id": "2016",
        "name": "Thomas Anderson",
        "email": "agent@jivosite.com",
        "phone": "+14083682346"
    },
    "department": {
        "id": 281,
        "name": "Sales"
    },
    "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": "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": {}
}

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

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

Пример

{
    "result": "ok"
}

chat_updated

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

Пример

{
    "event_name": "chat_updated",
    "chat_id": 7507,
    "widget_id": "3948",
    "visitor": {
        "name": "John Smith",
        "email": "email@example.com",
        "phone": "+14084987855",
        "number": "2198",
        "description": "Description text",
        "social": {},
        "chats_count": 1
    },
    "agent": {
        "id": "2016",
        "name": "Thomas Anderson",
        "email": "agent@jivosite.com",
        "phone": "+14083682346"
    },
    "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": {}
}

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

Название	Тип	Описание
result	string	Строка результата обработки. Если значение не равно "ок", данные не будут переданы оператору
custom_data	array	Поля дополнительных данных, аналогично setCustomData
contact_info	object	Поля контактных данных, аналогично setContactInfo
enable_assign	boolean	Флаг, определяющий отображению оператору кнопки привязки посетителя к карточке в CRM. Кнопка отображается перед всеми полями custom_data
crm_link	string	Ссылка на карточку клиента в CRM. Отображается оператору отдельной кнопкой под всеми полями custom_data
page	object	Информация о странице

chat_finished

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

Пример

{
    "event_name": "chat_finished",
    "chat_id": 7607,
    "widget_id": "3948",
    "visitor": {
        "name": "John Smith",
        "email": "email@example.com",
        "phone": "+14084987855",
        "number": "2198",
        "description": "Description text",
        "social": {},
        "chats_count": 1
    },
    "agents": [
        {
            "id": "2016",
            "name": "Thomas Anderson",
            "email": "agent@jivosite.com",
            "phone": "+14083682346"
        }
    ],
    "department": {
        "id": 281,
        "name": "Sales"
    },
    "chat": {
        "messages": [
            {
                "timestamp": 1599806237,
                "message": "<Message text is not displayed here>",
                "type": "visitor"
            },
            {
                "timestamp": 1599806263,
                "message": "<Message text is not displayed here>",
                "agent_id": 1,
                "type": "agent"
            }
        ],
        "rate": null
    }
    "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"
    }
}

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

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

Пример

{
    "result": "ok"
}

offline_message

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

Пример:

{
    "event_name": "offline_message",
    "widget_id": "3948",
    "visitor": {
        "name": "John Smith",
        "email": "email@example.com",
        "phone": "+14084987855",
        "number": "2198",
        "description": "Description text",
        "social": {},
        "chats_count": 1
    },
    "offline_message_id": "2806",
    "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": "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": {}
}

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

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

Пример

{
    "result": "ok"
}

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

event

Название	Тип	Описание
event_name	string	Тип события
chat_id	number	Идентификатор чата
widget_id	string	Идентификатор канала связи
visitor	object	Объект с информацией о посетителе
agent	object	Объект с информацией об операторе
department `необязательный`	object	Объект с информацией об отделе, который посетитель выбрал перед началом чата
session	object	Данные о сессии пользователя
page	object	Информация о странице
call	object	Информация о звонке
analytics `необязательный`	object	Аналитика

visitor

Название	Тип	Описание
name `необязательный`	string	Имя посетителя
email `необязательный`	string	Email посетителя
phone `необязательный`	string	Телефон посетителя
number	string	Номер посетителя
description	string	Дополнительная информация по клиенту
social `необязательный`	object	Данные о социальных сетях пользователя
chats_count	number	Количество обращений

agent

Название	Тип	Описание
id	int	Идентификатор оператора
name	string	Имя оператора
email	string	Email оператора
phone `необязательный`	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	Заголовок страницы

call

Название	Тип	Описание
type	string	Tип звонка (callback, incoming, outgoing)
phone	string	Номер телефона клиента
status	string	Статус звонка (start, end, agentconnected, clientconnected, error)
reason `необязательный`	string	Причина ошибки (доступна, когда звонок завершился с ошибкой)
record_url `необязательный`	string	Ссылка на запись звонка в формате mp3 (доступна после завершения звонка)

geoip

	Название	Тип
region_code	string	Код региона
country	string	Название страны
country_code	string	ISO код страны
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