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

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

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.

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.

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

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

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

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.

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

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

visitor

Field

Type

Description

name optional

string

Name

email optional

string

Email

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

string

Operator ID

name

string

Name of the operator

email

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.

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

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

visitor

Field

Type

Description

name optional

string

Name

email optional

string

Email

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

string

Operator ID

name

string

Name of the operator

email

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)

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

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