JivoSite 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.

JavaScript API

JivoChat calls 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 the client.

Callback functions

FieldTypeDescription
jivo_onLoadCallbackfunctionCalls when JivoChat widget initialization is over
jivo_onOpenfunctionCalls when chat window is open
jivo_onMessageSentfunctionCalls when visitor sent the first message
jivo_onAcceptfunctionCalls when operator pressed the Reply button in the notification of a new chat
jivo_onClosefunctionCalls when chat window is closed
jivo_onIntroductionfunctionCalls when a visitor introduced
jivo_onResizeCallbackfunctionCalls at any change in the size of the widget

JavaScript API - open

Using this method you can open chat window.

JavaScript API - chatMode

Using this method you can get the current status of agents.

JavaScript API - getContactInfo

Read 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 archive and can be used to associate JivoChat data with the CRM data.

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 in the beginning of chat.

Params

FieldTypeDescription
namestringClient name
emailstringClient email
phonestringClient phone number
descriptionstringAdditional 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 in the right information panel on 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 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 the sending phishing links 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.

Params

FieldTypeDescription
fieldsarrayList of additional data fields of the chat

field

FieldTypeDescription
contentstringContent of data field. Tags will be insulated
titlestringTitle shown above a data field
linkstringURL that opens when you click on a data field
keystringDescription of the data field, bold text before a colon
 jivo_api.setCustomData([
    {
        "title": "Actions",
        "content": "Add contact",
        "link": "..."
    },
    {
        "title": "Open customer profile",
        "link": "..."
    }
 ]); 

JavaScript API - setRules

Using this method you can replace the automatic actions by transferred object.

Params

FieldTypeDescription
rulesobjectDescription of the rules of active invitations in JSON
 jivo_api.setRules(rules); 

JavaScript API - setUserToken

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

FieldTypeDescription
tokenstringVisitor 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

FieldTypeDescription
invitation_textstringInvitation text
department_idnumberDepartment id
 jivo_api.showProactiveInvitation("How can I help you?"); 

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 - 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

FieldTypeDescription
event_namestringEvent Type Default: chat_accepted
chat_idnumberID chat
visitorobjectObject with information about the visitor
agentobjectObject with information about the operator
sessionobjectInformation on user sessions

visitor

FieldTypeDescription
namestringName
emailstringEmail
phonestringPhone
numberstringNumber of visitor
descriptionstringAdditional information about the client
socialobjectInformation about the user's social networks
chats_countnumberThe number of messages

agent

FieldTypeDescription
idstringOperator ID
namestringName of the operator
emailstringEmail operator
phonestringPhone visitor

session

FieldTypeDescription
geoipobjectData from geoip
utmstringutm
ip_addrstringIP addres of active sessions
user_agentstringDescription of user_agent

geoip

FieldTypeDescription
region_codestringArea code
countrystringCountry name
country_codestringISO country code
regionstringRegion
citystringCity
latitudestringLatitude
longitudestringLongitude
organizationstringCompany name

Response

FieldTypeDescription
resultstringString processing result. If the value is not "OK", the data will not be transmitted to the operator
custom_dataarrayAdditional data fields, similar setCustomData
contact_infoobjectFields of contact data, similar setContactInfo
enable_assignbooleanA 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_linkstringLink to the client card in CRM. Displays the operator a separate button under all fields custom_data.

custom_data

FieldTypeDescription
titlestringArbitrary name of a custom field
contentstringContent

contact_info

FieldTypeDescription
namestringCustomer name
phonestringCustomer phone
emailstringCustomer E-mail

The request contains a structure:

 {
    "event_name": "chat_accepted",
    "chat_id": 3061,
    "visitor": {
        "name": "John Smith",
        "email": "email@example.com",
        "phone": "+14084987855",
        "number": "...",
        "description": "Description text",
        "social": {},
        "chats_count": 8
    },
    "agent": {
        "id": "...",
        "name": "Thomas Anderson",
        "email": "agent@jivosite.com",
        "phone": "+14083682346"
    },
    "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": "...",
        "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"
    }
} 

The response contains JSON:

 {
    "result": "ok",
    "custom_data": [
        {
            "title": "Title",
            "content": "Content text"
        }
    ],
    "contact_info": {
        "name": "John Smith",
        "phone": "+14084987855",
        "email": "email@example.com"
    },
    "enable_assign": true,
    "crm_link": "http://mycrm.ru/user/1"
} 

Webhooks - chat_assigned

Params

FieldTypeDescription
event_namestringEvent type, default: chat_assigned
chat_idnumberID chat
visitorobjectObject with information about the visitor
agentobjectObject with information about the operator
assign_tostringWho was appointed chat
sessionobjectInformation on user sessions

visitor

FieldTypeDescription
namestringName
emailstringEmail
phonestringPhone
numberstringNumber of visitor
descriptionstringAdditional information about the client
socialobjectInformation about the user's social networks
chats_countnumberThe number of messages

agent

FieldTypeDescription
idstringOperator ID
namestringName of the operator
emailstringEmail operator
phonestringPhone visitor

session

FieldTypeDescription
geoipobjectData from geoip
utmstringutm
ip_addrstringIP addres of active sessions
user_agentstringDescription of user_agent

geoip

FieldTypeDescription
region_codestringArea code
countrystringCountry name
country_codestringISO country code
regionstringRegion
citystringCity
latitudestringLatitude
longitudestringLongitude
organizationstringCompany name

The request contains a structure:

 {
    "event_name": "chat_assigned",
    "chat_id": 2315,
    "visitor": {
        "name": "John Smith",
        "email": "email@example.com",
        "phone": "+14084987855",
        "number": "...",
        "description": "Description text",
        "social": {},
        "chats_count": 8
    },
    "agent": {
        "id": "...",
        "name": "Thomas Anderson",
        "email": "agent@jivosite.com",
        "phone": "+14083682346"
    },
    "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": "...",
        "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"
    }
} 

Webhooks - chat_finished

Params

FieldTypeDescription
event_namestringType of event, default: chat_finished
chat_idnumberID chat
visitorobjectObject with information about the visitor
agentobjectObject with information about the operator
chatobjectData on completed chatting
sessionobjectInformation on user sessions

visitor

FieldTypeDescription
namestringName
emailstringEmail
phonestringPhone
numberstringNumber of visitor
descriptionstringAdditional information about the client
socialobjectInformation about the user's social networks
chats_countnumberThe number of messages

agent

FieldTypeDescription
idstringOperator ID
namestringName of the operator
emailstringEmail operator
phonestringPhone visitor

chat

FieldTypeDescription
messagesarrayAn array of chat messages
ratestringUser chat rank (positive | negative | null)
blacklistedbooleanA sign that the user was added to the black list

session

FieldTypeDescription
geoipobjectData from geoip
utmstringutm
ip_addrstringIP addres of active sessions
user_agentstringDescription of user_agent

message

FieldTypeDescription
timestampnumberThe time of receipt message (timestamp)
typestringMessage Type (visitor - a message from a client, agent - a message from an agent)
agent_idnumberAgent ID, which responded to the message (exists only if type = agent)
blacklistedbooleanA sign that the user was added to the black list

geoip

FieldTypeDescription
region_codestringArea code
countrystringCountry name
country_codestringISO country code
regionstringRegion
citystringCity
latitudestringLatitude
longitudestringLongitude
organizationstringCompany name

The request contains a structure:

 {
    "event_name": "chat_finished",
    "chat_id": 9083,
    "visitor": {
        "name": "John Smith",
        "email": "email@example.com",
        "phone": "+14084987855",
        "number": "...",
        "description": "Description text",
        "social": {},
        "chats_count": 8
    },
    "agent": {
        "id": "...",
        "name": "Thomas Anderson",
        "email": "agent@jivosite.com",
        "phone": "+14083682346"
    },
    "chat": {
        "messages": [
            {
                "timestamp": 1431955090,
                "type": "agent",
                "agent_id": 6241,
                "blacklisted": false
            }
        ],
        "rate": "positive",
        "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": "...",
        "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"
    }
} 

Webhooks - chat_updated

Params

FieldTypeDescription
event_namestringEvent type, default: chat_updated
chat_idnumberID of a chat
visitorobjectObject with information about the visitor
agentobjectObject with information about the operator
sessionobjectInformation on user sessions

visitor

FieldTypeDescription
namestringName
emailstringEmail
phonestringPhone
numberstringNumber of visitor
descriptionstringAdditional information about the client
socialobjectInformation about the user's social networks
chats_countnumberThe number of messages

agent

FieldTypeDescription
idstringOperator ID
namestringName of the operator
emailstringEmail operator
phonestringPhone visitor

session

FieldTypeDescription
geoipobjectData from geoip
utmstringutm
ip_addrstringIP addres of active sessions
user_agentstringDescription of user_agent

geoip

FieldTypeDescription
region_codestringArea code
countrystringCountry name
country_codestringISO country code
regionstringRegion
citystringCity
latitudestringLatitude
longitudestringLongitude
organizationstringCompany name

The request contains a structure:

 {
    "event_name": "chat_updated",
    "chat_id": 6489,
    "visitor": {
        "name": "John Smith",
        "email": "email@example.com",
        "phone": "+14084987855",
        "number": "...",
        "description": "Description text",
        "social": {},
        "chats_count": 8
    },
    "agent": {
        "id": "...",
        "name": "Thomas Anderson",
        "email": "agent@jivosite.com",
        "phone": "+14083682346"
    },
    "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": "...",
        "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"
    }
} 

Webhooks - offline_message

Params

FieldTypeDescription
event_namestringEvent type, default: offline_messages
chat_idnumberID chat
visitorobjectObject with information about the visitor
offline_message_idstringID offline messages
messagestringMessage
sessionobjectInformation on user sessions

visitor

FieldTypeDescription
namestringName
emailstringEmail
phonestringPhone
numberstringNumber of visitor
descriptionstringAdditional information about the client
socialobjectInformation about the user's social networks
chats_countnumberThe number of messages

session

FieldTypeDescription
geoipobjectData from geoip
utmstringutm
ip_addrstringIP addres of active sessions
user_agentstringDescription of user_agent

geoip

FieldTypeDescription
region_codestringArea code
countrystringCountry name
country_codestringISO country code
regionstringRegion
citystringCity
latitudestringLatitude
longitudestringLongitude
organizationstringCompany name

The request contains a structure:

 {
    "event_name": "offline_message",
    "chat_id": 9843,
    "visitor": {
        "name": "John Smith",
        "email": "email@example.com",
        "phone": "+14084987855",
        "number": "...",
        "description": "Description text",
        "social": {},
        "chats_count": 8
    },
    "offline_message_id": "...",
    "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": "...",
        "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"
    }
}