Категории

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

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	Идентификатор ответственного по клиенту сотрудника
email	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	Идентификатор оператора
email	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