Pricing
Affiliate program
Blog
Help
Applications
Documentation

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

NameTypeDescription
resultstringString with the result of a request processing. If the value is not "OK", data will not be passed on to the agent
custom_dataarrayAdditional data fields, similar to setCustomData
contact_infoobjectContact details fields, similar to setContactInfo
enable_assignbooleanFlag that determines whether the agent sees the button to link a client to CRM. The button is displayed above all custom_data fields
crm_linkstring fieldsLink to the visitor's card in CRM. Displayed to the agent by a separate button below all custom_data
pageobjectInformation about the page, where visitor currently 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 optionalstringPage 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

NameTypeDescription
resultstringString with the result of a request processing. If the value is not "OK", data will not be passed on to the agent
custom_dataarrayAdditional data fields, similar to setCustomData
contact_infoobjectContact data fields, similar to setContactInfo
enable_assignbooleanFlag that determines whether the agent sees the button to link a visitor to CRM. The button is displayed above all custom_data fields
crm_linkstring fieldsLink to the visitor's card in CRM. Displayed to the agent by a separate button below all custom_data
pageobjectInformation 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

NameTypeDescription
event_namestringEvent type
widget_idstringChannel's widget ID
user_tokenstringAdditional ID of a user (can be set using setUserToken method)
visitorobjectObject with information about a visitor
organizationobjectObject with the information about an organization, client was assigned
statusobjectClient's category
assigned_agentobjectInformation about an agent assigned to the client
tagsobjectTags selected for the client
chat_idnumberID of a chat
department optionalobjectInformation about the department that visitor selected before the chat
sessionobjectVisitor's sessions data
pageobjectCurrent page URL
callobjectCall information
analytics optionalobjectAnalytics
agentobjectObject with information about an agent
chatobjectChat messages log

visitor

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

organization

NameTypeDescription
idnumberCompany ID
namestringCompany title

status

NameTypeDescription
idnumberClient category ID
titlestringCategory name

assigned_agent

NameTypeDescription
idnumberAssigned agent ID
emailstringAssigned agent email
namestringAssigned agent name

tags

NameTypeDescription
idnumberTag ID
titlestringTag name

department

NameTypeDescription
idnumberDepartment ID
namestringDepartment title

session

NameTypeDescription
geoipobjectGeoIP data of a client
utmstringUTM in the string format
utm_jsonobjectObject with UTM data
ip_addrstringIP-address of an active session
user_agentstringUser_agent data

page

NameTypeDescription
urlstringCurrent page URL
title optionalstringCurrent page title

agent

NameTypeDescription
idnumberAgent ID
namestringAgent name
emailstringAgent email
phone optionalstringAgent phone number

call

NameTypeDescription
typestringCall type (callback, incoming, outgoing)
phonestringCustomer's phone number
statusstringCall status (start, end, agent_connected, client_connected, error)
reason optionalstringError reason (avaiable if call status is an error)
record_url optionalstringLink to .mp3 recording of a call (available if the call has ended)

chat

NameTypeDescription
messagesobjectObject with chat messages log
blacklistedbooleanIndicates if the client was blocked by an agent in Jivo app
rate optionalstringQuality assessment of the chat
invitation optionalstringProactive invitation text

messages

NameTypeDescription
messagestringMessage text
timestampintTime tag
typestringUser type (client or agent)
agent_idnumberID of an agent who sent a message

geoip

NameTypeDescription
region_codestringRegion code
country_codestringISO country code
countrystringCountry name
regionstringRegion name
citystringCity name
latitudestringLatitude
longitudestringLongitude
organizationstringInternet service provider 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