Webhooks API
Use Webhooks to receive notifications about various events associated with visitor's activity in JivoChat system. You can set an HTTP(S) URL to send requests when some event occurred in Admin panel.
POST request will be sent to the specified URL with the event information in the JSON object as a body.
Event type is specified in the event_name field of the 'event' structure. The other fields depending on the actual event. In response to the HTTP-request for some types of events you can send the data which will be displayed to the agent who accepted the chat.
call_event
Event will be sent when operators get a new call, or existing call status is changed.
Example:
{
"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
Event will be sent when the chat is accepted by the agent. All known data about visitor and some agent's info will be sent in the request parameters along with visitor's id if it was sent to the widget in setUserToken.
If response to chat_accepted contains contact_info, this data will be displayed to the agent as if a visitor introduced himself in the chat window. It also will be saved in the chat log.
{
"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": {}
}
Response parameters
Name | Type | Description |
---|---|---|
result | string | String processing result. If the value is not "OK", data will not be passed to the operator |
custom_data | array | Additional data fields, similar to setCustomData |
contact_info | object | Contact data fields, similar to setContactInfo |
enable_assign | boolean | Flag that determines whether the operator the operator to display the key binding visitor to the card in CRM. The button is displayed in front of all fields custom_data |
crm_link | string fields | Link to the client's card in CRM. Displayed to the agent by a separate button under all custom_data |
page | object | Information about the page, where visitor is |
custom_data
Name | Type | Description |
---|---|---|
title | string | Name of a custom field |
content | string | Content |
contact_info
Name | Type | Description |
---|---|---|
name | string | Visitor's name |
phone optional | string | Visitor's phone number |
email optional | string | Visitor's email |
page
Name | Type | Description |
---|---|---|
url | string | Current page URL |
title необязательный | string | Page title |
Example
{
"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
Event will be sent when a chat connects to CRM using the parameter "crm_link" from reply on chat_accepted. All known data about visitor and some agent's info will be sent in the request parameters. Also parameters including visitor's id if it was sent to the widget using setUserToken.
Example:
{
"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": {}
}
Response parameters
Expected response is JSON {"result": "ok"} or the error text.
Example
{
"result": "ok"
}
chat_updated
Event will be sent when a visitor's information has been updated - for example a visitor filled the contacts form in the chat. All known data about visitor and agent's info will be sent in the request parameters. Also parameters including visitor's id if it was sent to the widget using setUserToken.
Example
{
"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": {}
}
Response parameters
Name | Type | Description |
---|---|---|
result | string | String processing result. If the value is not "OK", data will not be passed to the operator |
custom_data | array | Additional data fields, similar to setCustomData |
contact_info | object | Contact data fields, similar to setContactInfo |
enable_assign | boolean | Flag that determines whether the operator the operator to display the key binding visitor to the card in CRM. The button is displayed in front of all fields custom_data |
crm_link | string fields | Link to the client's card in CRM. Displayed to the agent by a separate button under all custom_data |
page | object | Information about the page, where visitor is |
chat_finished
Event is sent when the chat is closed in jivo app. All known data about visitor, agent's info and the chat log will be sent in the request parameters. Also parameters contain visitor's id if it was sent to the widget using setUserToken.
Example
{
"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"
}
}
Response parameters
In response we expect JSON {"result": "ok"} or the error text.
Example
{
"result": "ok"
}
offline_message
Event will be sent when a visitor sends a message through the chat offline form. All known data about visitor and offline message will be sent in the request parameters. Also parameters including visitor's id if it was sent to the widget using [setUserToken](/widget#setusertoken.
Example:
{
"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": {}
}
Response parameters
Expected response is JSON {"result": "ok"} or the error text.
Example
{
"result": "ok"
}
Event parameters
event
Name | Type | Description |
---|---|---|
event_name | string | Event type |
chat_id | number | ID of the chat |
widget_id | string | Channel's widget ID, it can be found in the chat code |
visitor | object | Object with information about the visitor |
agent | object | Object with information about the operator |
department optional | object | Object with information about the department selected before the chat |
session | object | User sessions data |
page | object | Current page URL |
call | object | Call information |
analytics optional | object | Analytics |
visitor
Name | Type | Description |
---|---|---|
name optional | string | Visitor's name |
email optional | string | Visitor's email |
phone optional | string | Visitor's phone |
number | string | Visitor's number |
description | string | Additional information about the visitor |
social optional | object | Information about the visitor's social networks |
chats_count | number | The number of chats |
agent
Name | Type | Description |
---|---|---|
id | int | Operator ID |
name | string | Operator name |
string | operator's email | |
phone optional | string | user's phone Number |
department
Name | Type | Description |
---|---|---|
id | number | Department ID |
name | string | Department name |
session
Название | Тип | Описание |
---|---|---|
geoip | object | GeoIP data |
utm | string | UTM (deprecated, use utm_json instead) |
utm_json | object | Object with UTM data |
ip_addr | string | IP address of active session |
user_agent | string | User_agent description |
page
Name | Type | Description |
---|---|---|
url | string | Current page URL |
title optional | string | Current page title |
call
Name | Type | Description |
---|---|---|
type | string | Call type (callback, incoming, outgoing) |
phone | string | Customer's phone number |
status | string | Call status (start, end, agentconnected, clientconnected, error) |
reason optional | string | Error reason (defined if call status is error) |
record_url optional | string | Link to mp3 record of a call (defined if the call has ended) |
geoip
Name | Type | Description |
---|---|---|
region_code | string | Region code |
country | string | Country name |
country_code | string | ISO country code |
region | string | Region |
city | string | City |
latitude | string | Latitude |
longitude | string | Longitude |
organization | string | Organization name |
utm_json
Name | Type | Desription |
---|---|---|
source optional | string | Value of utm_source |
campaign optional | string | Value of utm_campaign |
content optional | string | Value of utm_content |
medium optional | string | Value of utm_medium |
term optional | string | Value of utm_term |