Webhooks API
You can use Webhooks to receive notifications about various events associated with visitor's activity in JivoChat system.
You can set up an HTTP(S) URL where the request will be sent to, when an event occurrs in Jivo app. POST request will be sent to the specified URL with the event data in JSON object format.
Event type is specified in the event_name field of the 'event' structure.
Other fields depend on the actual event.
For some types of events you can send the data as a response to the HTTP-request to be displayed to the agents in Jivo app.
call_event
This event occurs when agents get a new call or an existing call status changes.
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
This event is sent when a chat is accepted by the agent. All known data about visitor and some agent's info are to be sent in the request parameters along with visitor's ID, if it was sent to the widget in setUserToken method.
If a response to chat_accepted contains contact_info, this data will be displayed to the agent as if a visitor introduced himself in the chat form. It will be saved in the chat log as well.
{ "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" }, }
Response parameters
Name | Type | Description |
---|---|---|
result | string | String with the result of a request processing. If the value is not "OK", data will not be passed on to the agent |
custom_data | array | Additional data fields, similar to setCustomData |
contact_info | object | Contact details fields, similar to setContactInfo |
enable_assign | boolean | Flag that determines whether the agent sees the button to link a client to CRM. The button is displayed above all custom_data fields |
crm_link | string fields | Link to the visitor's card in CRM. Displayed to the agent by a separate button below all custom_data |
page | object | Information about the page, where visitor currently 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 optional | 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
The event is sent when a chat is linked to CRM using the parameter "crm_link" from the response to chat_accepted event. All known data about visitor and some agent's info are sent in the request parameters. Also parameters include visitor's ID if it was sent to the widget using setUserToken method.
Example:
{ "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", }
Response parameters
The expected response is JSON {"result": "ok"} or the error text.
Example
{ "result": "ok" }
chat_updated
The event is sent when a visitor's information has been updated - for example, a visitor has filled the contacts form in the chat. All known data about visitor is sent in the request parameters along with the information about the agent who accepted the chat. Also there may be visitor's ID if it was sent to the widget using setUserToken method.
Example
{ "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" }, }
Response parameters
Name | Type | Description |
---|---|---|
result | string | String with the result of a request processing. If the value is not "OK", data will not be passed on to the agent |
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 agent sees the button to link a visitor to CRM. The button is displayed above all custom_data fields |
crm_link | string fields | Link to the visitor's card in CRM. Displayed to the agent by a separate button below all custom_data |
page | object | Information about the page where visitor currently is |
client_updated
The event is triggered by a client's data update. For example, an agent was assigned to the client or client's category was changed. This event is also sent when client's contact details are updated out of an active chat (in the CRM section - Clients).
Example
{ "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" }
Response parameters
The expected response is JSON {"result": "ok"} or the error text.
Example
{ "result": "ok" }
chat_finished
This event is sent when the chat is closed in JivoChat app. All known data about visitor, agent information and the chat log are sent in the request parameters. Also there may be visitor's ID if it is sent to the widget using setUserToken method.
Example
{ "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": "" }
Response parameters
The response is expected to be JSON {"result": "ok"} or the error text.
Example
{ "result": "ok" }
offline_message
The event is sent when a visitor sends a message via the chat offline form. All known data about visitor and the offline message are sent in the request parameters. Also the request may include visitor's ID if it has been sent to the widget using setUserToken method.
Example
{ "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 }
Response parameters
The expected response is JSON {"result": "ok"} or the error text.
Example
{ "result": "ok" }
Event parameters
event
Name | Type | Description |
---|---|---|
event_name | string | Event type |
widget_id | string | Channel's widget ID |
user_token | string | Additional ID of a user (can be set using setUserToken method) |
visitor | object | Object with information about a visitor |
organization | object | Object with the information about an organization, client was assigned |
status | object | Client's category |
assigned_agent | object | Information about an agent assigned to the client |
tags | object | Tags selected for the client |
chat_id | number | ID of a chat |
department optional | object | Information about the department that visitor selected before the chat |
session | object | Visitor's sessions data |
page | object | Current page URL |
call | object | Call information |
analytics optional | object | Analytics |
agent | object | Object with information about an agent |
chat | object | Chat messages log |
visitor
Name | Type | Description |
---|---|---|
name optional | string | Visitor's name |
email optional | string | Visitor's email |
phone optional | string | Visitor's phone |
description | string | Additional information about the visitor |
number | string | Visitor's number |
social optional | object | Information about the visitor's social networks |
chats_count | number | The number of visitor's requests |
organization
Name | Type | Description |
---|---|---|
id | number | Company ID |
name | string | Company title |
status
Name | Type | Description |
---|---|---|
id | number | Client category ID |
title | string | Category name |
assigned_agent
Name | Type | Description |
---|---|---|
id | number | Assigned agent ID |
string | Assigned agent email | |
name | string | Assigned agent name |
tags
Name | Type | Description |
---|---|---|
id | number | Tag ID |
title | string | Tag name |
department
Name | Type | Description |
---|---|---|
id | number | Department ID |
name | string | Department title |
session
Name | Type | Description |
---|---|---|
geoip | object | GeoIP data of a client |
utm | string | UTM in the string format |
utm_json | object | Object with UTM data |
ip_addr | string | IP-address of an active session |
user_agent | string | User_agent data |
page
Name | Type | Description |
---|---|---|
url | string | Current page URL |
title optional | string | Current page title |
agent
Name | Type | Description |
---|---|---|
id | number | Agent ID |
name | string | Agent name |
string | Agent email | |
phone optional | string | Agent phone number |
call
Name | Type | Description |
---|---|---|
type | string | Call type (callback, incoming, outgoing) |
phone | string | Customer's phone number |
status | string | Call status (start, end, agent_connected, client_connected, error) |
reason optional | string | Error reason (avaiable if call status is an error) |
record_url optional | string | Link to .mp3 recording of a call (available if the call has ended) |
chat
Name | Type | Description |
---|---|---|
messages | object | Object with chat messages log |
blacklisted | boolean | Indicates if the client was blocked by an agent in Jivo app |
rate optional | string | Quality assessment of the chat |
invitation optional | string | Proactive invitation text |
messages
Name | Type | Description |
---|---|---|
message | string | Message text |
timestamp | int | Time tag |
type | string | User type (client or agent) |
agent_id | number | ID of an agent who sent a message |
geoip
Name | Type | Description |
---|---|---|
region_code | string | Region code |
country_code | string | ISO country code |
country | string | Country name |
region | string | Region name |
city | string | City name |
latitude | string | Latitude |
longitude | string | Longitude |
organization | string | Internet service provider 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 |