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

NameTypeDescription
resultstringString processing result. If the value is not "OK", data will not be passed to the operator
custom_dataarrayAdditional data fields, similar to setCustomData
contact_infoobjectContact data fields, similar to setContactInfo
enable_assignbooleanFlag 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_linkstring fieldsLink to the client's card in CRM. Displayed to the agent by a separate button under all custom_data
pageobjectInformation about the page, where visitor is

custom_data

NameTypeDescription
titlestringName of a custom field
contentstringContent

contact_info

NameTypeDescription
namestringVisitor's name
phone optionalstringVisitor's phone number
email optionalstringVisitor's email

page

NameTypeDescription
urlstringCurrent page URL
title необязательныйstringPage 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

NameTypeDescription
resultstringString processing result. If the value is not "OK", data will not be passed to the operator
custom_dataarrayAdditional data fields, similar to setCustomData
contact_infoobjectContact data fields, similar to setContactInfo
enable_assignbooleanFlag 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_linkstring fieldsLink to the client's card in CRM. Displayed to the agent by a separate button under all custom_data
pageobjectInformation 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

NameTypeDescription
event_namestringEvent type
chat_idnumberID of the chat
widget_idstringChannel's widget ID, it can be found in the chat code
visitorobjectObject with information about the visitor
agentobjectObject with information about the operator
department optionalobjectObject with information about the department selected before the chat
sessionobjectUser sessions data
pageobjectCurrent page URL
callobjectCall information
analytics optionalobjectAnalytics

visitor

NameTypeDescription
name optionalstringVisitor's name
email optionalstringVisitor's email
phone optionalstringVisitor's phone
numberstringVisitor's number
descriptionstringAdditional information about the visitor
social optionalobjectInformation about the visitor's social networks
chats_countnumberThe number of chats

agent

NameTypeDescription
idintOperator ID
namestringOperator name
emailstringoperator's email
phone optionalstringuser's phone Number

department

NameTypeDescription
idnumberDepartment ID
namestringDepartment name

session

НазваниеТипОписание
geoipobjectGeoIP data
utmstringUTM (deprecated, use utm_json instead)
utm_jsonobjectObject with UTM data
ip_addrstringIP address of active session
user_agentstringUser_agent description

page

NameTypeDescription
urlstringCurrent page URL
title optionalstringCurrent page title

call

NameTypeDescription
typestringCall type (callback, incoming, outgoing)
phonestringCustomer's phone number
statusstringCall status (start, end, agentconnected, clientconnected, error)
reason optionalstringError reason (defined if call status is error)
record_url optionalstringLink to mp3 record of a call (defined if the call has ended)

geoip

NameTypeDescription
region_codestringRegion code
countrystringCountry name
country_codestringISO country code
regionstringRegion
citystringCity
latitudestringLatitude
longitudestringLongitude
organizationstringOrganization name

utm_json

NameTypeDesription
source optional stringValue of utm_source
campaign optionalstringValue of utm_campaign
content optionalstringValue of utm_content
medium optionalstringValue of utm_medium
term optionalstringValue of utm_term

← Widget APIChat API →