JivoChat Developers API
JivoChat provides developers two tool kits for integration:
Client-side — the widget JavaScript API which allows you to manage a widget which is displayed to the user. It can be used to manage the chat window, and also to send any information from the page on which the chat window is placed, to the JivoChat App (for example, it is possible to send additional information about a user and it will also be kept in the archive).
Server-side — Webhooks API, allows you to receive notifications about the beginning or end of a chat on your server-side, and also to send to JivoChat additional information to display it in the agent's application.
If you find any mistake in documentation please let us know in chat on jivochat.es
JavaScript API
JivoChat executes the functions listed below to report about an event on the page. You can declare any of these functions on the page and execute a logic of processing the event that occurred. For example, on jivo_onIntroduction event you can get contact details entered by a client.
Callback functions
Field | Type | Description |
---|---|---|
jivo_onLoadCallback | function | Executed when JivoChat widget initialization is over |
jivo_onOpen | function | Executed when chat window is opened |
jivo_onMessageSent | function | Executed when a visitor sends the first message |
jivo_onAccept | function | Executed when an agent presses the Reply button in the notification of a new chat |
jivo_onClose | function | Executed when chat window is closed |
jivo_onIntroduction | function | Executed when a visitor fills the contacts form |
jivo_onResizeCallback | function | Executed at any change in the size of the widget |
jivo_onCallStart | function | Executed when visitor makes phone call |
jivo_onCallEnd | function | Executed when a phone call ends |
jivo_onChangeState | function | Executed when chat window state is changed |
JavaScript API - jivo_onCallEnd
Executed when phone call ends
Params
Field | Type | Description |
---|---|---|
result optional | object | Result of callback |
function jivo_onCallEnd(res) {
if (res.result == 'ok') {
// call finished successfully
}
if (res.result == 'fail') {
// call finished with errors or can not started
console.log(res.reason); // reason for the unsuccessfull call
}
}
JavaScript API - jivo_onChangeState
Executed when chat window state is changed
Params
Field | Type | Description |
---|---|---|
state | string | Current state of the widget |
function jivo_onChangeState(state) {
if (state == 'chat') {
// widget is in the chat state
}
if (state == 'call' || state == 'chat/call') {
// callback form is opened
if (state == 'label' || state == 'chat/min'){
// widget is minimized
}
}
JavaScript API - open
Using this method you can open chat window.
jivo_api.open({start: 'call'}): opens form with a phone field for callback
JavaScript API - close
Using this method you can close the chat window.
JavaScript API - chatMode
Using this method you can get the current chat status- online/offline.
JavaScript API - getContactInfo
Reads visitor's contact info from the contacts form as a contact_info structure.
JavaScript API - getVisitorNumber
The asynchronous function to get a unique visitor number in JivoChat. Visitors are numbered sequentially: 1, 2, 3, etc. Visitor number is displayed in the agent's App and archives and can be used to associate JivoChat data to the CRM data.
jivo_api.getVisitorNumber(function(err, visitor_number){
console.log(visitor_number);
});
JavaScript API - setContactInfo
Sets the contact info of the visitor. The data is displayed to the agent is a same as if a visitor introduced in the chat window. It's a special function to set contact info because name, phone number and e-mail are very important in JivoChat - visitor can introduce himself at the beginning of chat.
Params
Field | Type | Description |
---|---|---|
name | string | Client's name |
string | Client's email | |
phone | string | Client's phone number |
description | string | Additional information about the client |
jivo_api.setContactInfo({
"name": "John Smith",
"email": "email@example.com",
"phone": "+14084987855",
"description": "Description text"
});
JavaScript API - setCustomData
Using this method you can send any additional info about the client to the agent's App. This info will be shown on the information panel, located on the right side of the agent's App. The method can be called as many times as you need. If chat is established, information in the agent's App will be updated in real time. Fields will be displayed in the same sequence as they are in the array 'fields'.
setCustomData method is the easiest way to send additional info about visitor to the agent's App. But you need to keep in mind that the data transmitted to agent thus cannot be trusted - using the browser debugging tools, an attacker can spoof them.
For organizing more secure transmission of information in case you need to guarantee the security, use setUserToken method and Webhooks.
To avoid the possibility of phishing links sent to agent, you need to set "Safe URL" in Admin panel - Settings - Integration Settings for Developers, and links to another domains will be blocked, agent won't see them.
Method returns {result: 'ok'} if the data has been set successfully or {result: 'fail', reason: 'Custom data must be array.'} if method returns error
Params
Field | Type | Description |
---|---|---|
fields | array | List of additional data fields of the chat |
field
Field | Type | Description |
---|---|---|
content | string | Content of data field. Tags will be insulated |
title | string | Title shown above a data field |
link | string | URL that opens when you click on a data field |
key | string | Description of the data field, bold text before a colon |
jivo_api.setCustomData([
{
"title": "Actions",
"content": "Add contact",
"link": "..."
},
{
"content": "Open customer profile",
"link": "..."
}
]);
JavaScript API - setRules
Using this method you can replace the triggers' rules by transferred object. You can get an example of such object in our admin panel in the Triggers section, just press JSON structure button there.
Params
Field | Type | Description |
---|---|---|
rules | object | Description of the rules of active invitations in JSON |
jivo_api.setRules(rules);
JavaScript API - setUserToken
Sets an ID number for the visitor. JivoChat does not display or handle this ID in any way but sends it in Webhook events. By using this method, you can identify your website visitors when processing Webhooks. We recommend using a hard-to-guess identifier to avoid spoofing.
A response with {result: ‘ok’, token: userToken} is sent if the token is successfully set. Otherwise, the following response is sent: {result: ‘fail’, token: userToken || false};
Params
Field | Type | Description |
---|---|---|
token | string | Visitor id |
JavaScript API - showProactiveInvitation
Use this method to open chat window with custom text at the moment you need. This may be useful if you want to show proactive invitation after the client added goods to cart of your online store. If you want to show invitation immediately when page is open, then you need to call showProactiveInvitation in jivo_onLoadCallback (to initialize that all in the right sequence).
Params
Field | Type | Description |
---|---|---|
invitation_text | string | Invitation text |
department_id | number | Department id |
jivo_api.showProactiveInvitation("How can I help you?");
JavaScript API - startCall
Method allows you to start a call to the desired number, if calls are available (Callback feature is configured and the balance of calls is positive).
Method returns {result: 'ok'} If the phone number is in the correct format and the request to start the call can be made.
Otherwise returns {result: 'fail', reason: 'Callback disabled'}, where reason - is about the unsuccessful method call.
Params
Field | Type | Description |
---|---|---|
phone | string | Phone number for the call |
jivo_api.startCall('+14084987855')
JavaScript API - isCallbackEnabled
Checks if calls are available.
Method returns:
{result: 'fail', reason: 'Callback disabled'} - calls are disabled in admin panel.
{result: 'fail', 'Callback unavaiable'} - сalls are not available for other reasons (not the day of the week, the time of the call, the call is already started).
{result: 'ok'} - calls are avaiable
Params
Field | Type | Description |
---|---|---|
callback | function | Function called to determine the availability of a callback from the site. |
jivo_api.isCallbackEnabled(function(res){
console.log('isCallbackEnabled', res);
if (res.result == 'ok') {
jivo_api.open({start: 'call'});
}
});
JavaScript API - sendOfflineMessage
Using this function you can send an offline message directly. Returns {result: 'ok'} if the passed parameters are correct
Returns {result: 'fail', error: errReason}, where errReason is the validation error of the passed fields, or the reason why you can not send an offline message.
Params
Field | Type | Description |
---|---|---|
name | string | Client's name |
string | Client's email | |
phone | string | Client's phone number |
description | string | Additional information about the client |
message | string | Offline message text |
jivo_api.sendOfflineMessage(({
"name": "John Smith",
"email": "email@example.com",
"phone": "+14084987855",
"description": "Description text",
"message": "Offline message"
});
Webhooks
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.
Webhooks - call_event
Event will be sent when operators get new call or existing call change status
Params
Field | Type | Description |
---|---|---|
event_name | string | Event Type, default: call_event |
chat_id | number | ID of a 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 a department, that a visitor chose for chat |
session | object | Information about user sessions |
page | object | Current page URL |
call | object | Information about a call |
analytics optional | object | Analytics |
visitor
Field | Type | Description |
---|---|---|
name optional | string | Name |
email optional | string | |
phone optional | string | Phone |
number | string | Number of visitor |
description | string | Additional information about the client |
social optional | object | Information about the user's social networks |
chats_count | number | the number of messages |
agent
Field | Type | Description |
---|---|---|
id | int | Operator ID |
name | string | Name of the operator |
string | Email operator | |
phone optional | string | Phone operator |
department
Field | Type | Description |
---|---|---|
id | number | Department ID |
name | string | Department name |
session
Field | Type | Description |
---|---|---|
geoip | object | Data from geoip |
utm | string | UTM (deprecated, use utm_json instead) |
utm_json | object | Object with UTM data |
ip_addr | string | IP address of active sessions |
user_agent | string | Description user_agent |
page
Field | Type | Description |
---|---|---|
url | string | URL of the page where the user is located |
title optional | string | Page Title |
call
Field | Type | Description |
---|---|---|
type | string | Type (callback, incoming, outgoing) |
phone | string | Client phone |
status | string | Call status (start, end, agent_connected, client_connected, error) |
reason optional | string | Error reason (defined if call status is error) |
record_url optional | string | Link to mp3 record of call (defined if the call is ended) |
geoip
Field | Type | Description |
---|---|---|
region_code | string | area code |
country | string | Country name |
country_code | string | ISO country code |
region | string | Region |
city | string | City |
region | string | Region |
latitude | string | Latitude |
longitude | string | Longitude |
organization | string | Company name |
utm_json
Field | Type | Description |
---|---|---|
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 |
The request contains a structure:
{
"event_name": "call_event",
"chat_id": 2302,
"widget_id": "3677",
"visitor": {
"name": "John Smith",
"email": "email@example.com",
"phone": "+14084987855",
"number": "2846",
"description": "Description text",
"social": {},
"chats_count": 9
},
"agent": {
"id": "2224",
"name": "Thomas Anderson",
"email": "agent@jivosite.com",
"phone": "+14083682346"
},
"department": {
"id": 161,
"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": {}
}
Webhooks - chat_accepted
Event will be sent when agent clicks 'Reply'. 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 jivo_api.setUserToken
If response to chat_accepted contains contat_info, this data will be displayed to the agent as if a visitor introduced in the chat window. It's also will be saved in the archive and email with the chat log.
Params
Field | Type | Description |
---|---|---|
event_name | string | Event Type Default: chat_accepted |
chat_id | number | ID of a chat |
widget_id | string | Channel 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 a department, that a visitor chose for chat |
session | object | Information on user sessions |
page | object | Information about a page on which the visitor |
analytics optional | object | Analytics |
visitor
Field | Type | Description |
---|---|---|
name optional | string | Name |
email optional | string | |
phone optional | string | Phone |
number | string | Number of visitor |
description | string | Additional information about the client |
social optional | object | Information about the user's social networks |
chats_count | number | the number of messages |
agent
Field | Type | Description |
---|---|---|
id | int | Operator ID |
name | string | Name of the operator |
string | Email operator | |
phone optional | string | Phone operator |
department
Field | Type | Description |
---|---|---|
id | number | Department ID |
name | string | Department name |
session
Field | Type | Description |
---|---|---|
geoip | object | Data from geoip |
utm | string | UTM (deprecated, use utm_json instead) |
utm_json | object | Object with UTM data |
ip_addr | string | IP address of active sessions |
user_agent | string | Description user_agent |
page
Field | Type | Description |
---|---|---|
url | string | URL of the page where the user is located |
title optional | string | Page Title |
geoip
Field | Type | Description |
---|---|---|
region_code | string | area code |
country | string | Country name |
country_code | string | ISO country code |
region | string | Region |
city | string | City |
region | string | Region |
latitude | string | Latitude |
longitude | string | Longitude |
organization | string | Company name |
utm_json
Field | Type | Description |
---|---|---|
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 |
Response
Field | Type | Description |
---|---|---|
result | string | string processing result. If the value is not "OK", the data will not be transmitted to the operator |
custom_data | array | additional data fields, similar setCustomData |
contact_info | object | Fields of contact data, similar setContactInfo |
enable_assign | boolean | A flag that determines the operator to display the binding key visitor to the card in CRM. The button is displayed in front of all fields custom_data. |
crm_link | string | Link to the client card in CRM. Displays the operator a separate button under all fields custom_data. |
page | object | Information about a page on which the visitor |
custom_data
Field | Type | Description |
---|---|---|
title | string | Arbitrary name of a custom field |
content | string | Content |
contact_info
Field | Type | Description |
---|---|---|
name | string | Customer name |
phone optional | string | Customer phone |
email optional | string | Customer E-mail |
page
Field | Type | Description |
---|---|---|
url | string | URL of the page where the user is located |
title optional | string | Page Title |
The request contains a structure:
{
"event_name": "chat_accepted",
"chat_id": 3537,
"widget_id": "3677",
"visitor": {
"name": "John Smith",
"email": "email@example.com",
"phone": "+14084987855",
"number": "2846",
"description": "Description text",
"social": {},
"chats_count": 9
},
"agent": {
"id": "2224",
"name": "Thomas Anderson",
"email": "agent@jivosite.com",
"phone": "+14083682346"
},
"department": {
"id": 161,
"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": {}
}
The response contains JSON:
{
"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"
}
}
Webhooks - 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 jivo_api.setUserToken
In response we expect only {"result": "ok or an error message"}
Params
Field | Type | Description |
---|---|---|
event_name | string | Event type, default: chat_assigned |
chat_id | number | ID of a chat |
widget_id | string | Channel 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 a department, that a visitor chose for chat |
assign_to | string | CRM link from the event Chat_accepted |
session | object | Information on user sessions |
page | object | Information about a page where a chat was started |
analytics optional | object | Analytics |
visitor
Field | Type | Description |
---|---|---|
name optional | string | Name |
email optional | string | |
phone optional | string | Phone |
number | string | Number of visitor |
description | string | Additional information about the client |
social optional | object | Information about the user's social networks |
chats_count | number | the number of messages |
agent
Field | Type | Description |
---|---|---|
id | int | Operator ID |
name | string | Name of the operator |
string | Email operator | |
phone optional | string | Phone operator |
department
Field | Type | Description |
---|---|---|
id | number | Department ID |
name | string | Department name |
session
Field | Type | Description |
---|---|---|
geoip | object | Data from geoip |
utm | string | UTM (deprecated, use utm_json instead) |
utm_json | object | Object with UTM data |
ip_addr | string | IP address of active sessions |
user_agent | string | Description user_agent |
page
Field | Type | Description |
---|---|---|
url | string | URL of the page where the user is located |
title optional | string | Page Title |
geoip
Field | Type | Description |
---|---|---|
region_code | string | area code |
country | string | Country name |
country_code | string | ISO country code |
region | string | Region |
city | string | City |
region | string | Region |
latitude | string | Latitude |
longitude | string | Longitude |
organization | string | Company name |
utm_json
Field | Type | Description |
---|---|---|
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 |
Response
Field | Type | Description |
---|---|---|
result | string | string processing result ("OK" or "FAILURE"). |
The request contains a structure:
{
"event_name": "chat_assigned",
"chat_id": 9998,
"widget_id": "3677",
"visitor": {
"name": "John Smith",
"email": "email@example.com",
"phone": "+14084987855",
"number": "2846",
"description": "Description text",
"social": {},
"chats_count": 9
},
"agent": {
"id": "2224",
"name": "Thomas Anderson",
"email": "agent@jivosite.com",
"phone": "+14083682346"
},
"department": {
"id": 161,
"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": {}
}
The response contains JSON:
{
"result": "ok"
}
Webhooks - chat_finished
Event will be sent when a chat is closed in the agent application. All known data about visitor, agent's info and the chat log will be sent in the request parameters. Also parameters including visitor's id if it was sent to the widget using jivo_api.setUserToken
In response we expect only {"result": "ok or an error message"}
Params
Field | Type | Description |
---|---|---|
event_name | string | type of event, default: chat_finished |
chat_id | number | id of a chat |
widget_id | string | Channel widget ID, it can be found in the chat code |
visitor | object | object with information about the visitor |
agents | array | An array with information about the operators |
department optional | object | object with information about a department, that a visitor chose for chat |
chat | object | Data on completed chatting |
session | object | Information on user sessions |
page | object | Information about a page where a chat was started |
analytics optional | object | Analytics |
visitor
Field | Type | Description |
---|---|---|
name optional | string | Name |
email optional | string | |
phone optional | string | Phone |
number | string | Number of visitor |
description | string | Additional information about the client |
social optional | object | Information about the user's social networks |
chats_count | number | the number of messages |
agent
Field | Type | Description |
---|---|---|
id | int | Operator ID |
name | string | Name of the operator |
string | Email operator | |
phone optional | string | Phone operator |
department
Field | Type | Description |
---|---|---|
id | number | Department ID |
name | string | Department name |
chat
Field | Type | Description |
---|---|---|
messages | array | An array of chat messages |
rate | string | user chat rank (positive | negative | null) |
blacklisted | boolean | A sign that the user was added to the black list |
session
Field | Type | Description |
---|---|---|
geoip | object | Data from geoip |
utm | string | UTM (deprecated, use utm_json instead) |
utm_json | object | Object with UTM data |
ip_addr | string | IP address of active sessions |
user_agent | string | Description user_agent |
page
Field | Type | Description |
---|---|---|
url | string | URL of the page where the user is located |
title optional | string | Page Title |
message
Field | Type | Description |
---|---|---|
timestamp | number | The time of receipt message (timestamp) |
type | string | Message Type (visitor - a message from a client, agent - a message from an agent) |
agent_id | number | Agent ID, which responded to the message (exists only if type = agent) |
blacklisted optional | boolean | A sign that the user was added to the black list |
geoip
Field | Type | Description |
---|---|---|
region_code | string | area code |
country | string | Country name |
country_code | string | ISO country code |
region | string | Region |
city | string | City |
region | string | Region |
latitude | string | Latitude |
longitude | string | Longitude |
organization | string | Company name |
utm_json
Field | Type | Description |
---|---|---|
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 |
Response
Field | Type | Description |
---|---|---|
result | string | string processing result ("OK" or "FAILURE"). |
The request contains a structure:
{
"event_name": "chat_finished",
"chat_id": 7676,
"widget_id": "3677",
"visitor": {
"name": "John Smith",
"email": "email@example.com",
"phone": "+14084987855",
"number": "2846",
"description": "Description text",
"social": {},
"chats_count": 9
},
"agents": [
{
"id": "2224",
"name": "Thomas Anderson",
"email": "agent@jivosite.com",
"phone": "+14083682346"
}
],
"department": {
"id": 161,
"name": "Sales"
},
"chat": {
"messages": [
{
"timestamp": 1431955090,
"type": "agent",
"agent_id": 6149,
"blacklisted": false
}
]
},
"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"
}
}
The response contains JSON:
{
"result": "ok"
}
Webhooks - 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 jivo_api.setUserToken
In response we expect only {"result": "ok or an error message"}
Params
Field | Type | Description |
---|---|---|
event_name | string | Event type, default: chat_updated |
chat_id | number | id of a chat |
widget_id | string | Channel 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 a department, that a visitor chose for chat |
session | object | Information on user sessions |
page | object | Information about a page on which the visitor |
analytics optional | object | Analytics |
visitor
Field | Type | Description |
---|---|---|
name optional | string | Name |
email optional | string | |
phone optional | string | Phone |
number | string | Number of visitor |
description | string | Additional information about the client |
social optional | object | Information about the user's social networks |
chats_count | number | the number of messages |
agent
Field | Type | Description |
---|---|---|
id | int | Operator ID |
name | string | Name of the operator |
string | Email operator | |
phone optional | string | Phone operator |
department
Field | Type | Description |
---|---|---|
id | number | Department ID |
name | string | Department name |
session
Field | Type | Description |
---|---|---|
geoip | object | Data from geoip |
utm | string | UTM (deprecated, use utm_json instead) |
utm_json | object | Object with UTM data |
ip_addr | string | IP address of active sessions |
user_agent | string | Description user_agent |
page
Field | Type | Description |
---|---|---|
url | string | URL of the page where the user is located |
title optional | string | Page Title |
geoip
Field | Type | Description |
---|---|---|
region_code | string | area code |
country | string | Country name |
country_code | string | ISO country code |
region | string | Region |
city | string | City |
region | string | Region |
latitude | string | Latitude |
longitude | string | Longitude |
organization | string | Company name |
utm_json
Field | Type | Description |
---|---|---|
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 |
Response
Field | Type | Description |
---|---|---|
result | string | string processing result ("OK" or "FAILURE"). |
The request contains a structure:
{
"event_name": "chat_updated",
"chat_id": 4043,
"widget_id": "3677",
"visitor": {
"name": "John Smith",
"email": "email@example.com",
"phone": "+14084987855",
"number": "2846",
"description": "Description text",
"social": {},
"chats_count": 9
},
"agent": {
"id": "2224",
"name": "Thomas Anderson",
"email": "agent@jivosite.com",
"phone": "+14083682346"
},
"department": {
"id": 161,
"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": {}
}
The response contains JSON:
{
"result": "ok"
}
Webhooks - offline_message
Event will be sent when a visitor sends an offline 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 jivo_api.setUserToken
In response we expect only {"result": "ok or an error message"}
Params
Field | Type | Description |
---|---|---|
event_name | string | Event type, default: offline_messages |
widget_id | string | Channel widget ID, it can be found in the chat code |
visitor | object | object with information about the visitor |
offline_message_id | string | ID offline messages |
message | string | Message |
session | object | Information on user sessions |
page | object | Information about a page on which the visitor |
analytics optional | object | Analytics |
visitor
Field | Type | Description |
---|---|---|
name optional | string | Name |
email optional | string | |
phone optional | string | Phone |
number | string | Number of visitor |
description | string | Additional information about the client |
social optional | object | Information about the user's social networks |
chats_count | number | the number of messages |
session
Field | Type | Description |
---|---|---|
geoip | object | Data from geoip |
utm | string | UTM (deprecated, use utm_json instead) |
utm_json | object | Object with UTM data |
ip_addr | string | IP address of active sessions |
user_agent | string | Description user_agent |
page
Field | Type | Description |
---|---|---|
url | string | URL of the page where the user is located |
title optional | string | Page Title |
geoip
Field | Type | Description |
---|---|---|
region_code | string | area code |
country | string | Country name |
country_code | string | ISO country code |
region | string | Region |
city | string | City |
region | string | Region |
latitude | string | Latitude |
longitude | string | Longitude |
organization | string | Company name |
utm_json
Field | Type | Description |
---|---|---|
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 |
Response
Field | Type | Description |
---|---|---|
result | string | string processing result ("OK" or "FAILURE"). |
The request contains a structure:
{
"event_name": "offline_message",
"widget_id": "3677",
"visitor": {
"name": "John Smith",
"email": "email@example.com",
"phone": "+14084987855",
"number": "2846",
"description": "Description text",
"social": {},
"chats_count": 9
},
"offline_message_id": "3999",
"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": {}
}
The response contains JSON:
{
"result": "ok"
}