Chat API · JivoSite API

This memo describes how to exchange events between servers through the Chat channel when integrating with Jivo. The chat channel is asynchronous bidirectional, a custom server capable of receiving and sending events is required for full implementation.

Channel protocol

The transport protocol for the event transmission is HTTPS (at the development stage it is allowed to use HTTP). The event is contained in the body POST-request in the format JSON (note, text encoding in format UTF-8), the request must have an appropriate header Content-Type: application/json; charset=utf-8. The event structure is described next. Response options are divided into 3 groups according to the HTTP-response code.

Code	Description	Action
2xx	Success. Event accepted for processing	Inform the user about the success of the delivery
4xx	The request failed. Event rejected	In the body of the response with this code, there may be a text describing the error (type of content Content-Type: text/plain; charset=utf-8). This event should not be resubmitted. It is necessary to analyze and correct the error of the program or channel settings. Inform user about event delivery failure
Any other HTTP code or connection error	The request cannot be accepted at this time. Event not accepted	In case of HTTP code 5xx or if the connection fails, it is recommended to repeat the request up to 3 times with an interval of 3-60 seconds. Inform the user that the event is temporarily undeliverable. Contact server support

Creation of a channel

To create a Chat channel in Jivo, use app. Once created, URL will be available to send events to Jivo, for example: https://wh.jivosite.com/foo/bar. To receive messages from Jivo, implement a custom server and add the URL to receive events in the channel settings in the app.

Channel status

If you add a segment /status to the URL for sending events to Jivo at the end of the path, for example https://wh.jivosite.com/foo/bar/status, then in the body of the response (in case of a successful response with the code 2xx) to GET-the request to the received URL will be the status of the channel, meaning the absence of interlocutors on the channel when the answer is 0, or the presence of interlocutors when the answer is 1 or any other.

Event structure

The protocol is symmetrical, the structure is the same for events from Jivo to the user server and back.

Field	Type	Description
sender	User	Message sender
recipient	User	Message recipient
message	Message	Message

User

Field	Type	Description	Max size
id	string	Client identifier, required parameter when sending events to Jivo sender.id and when receiving events from Jivo recipient.id	255 symbols
name	string	Username	255 symbols
photo	string	User avatar URL, valid https or http schemes	2048 symbols
url	string	URL страницы пользователя, допустимые схемы https или http	2048 символов
email	string	User email	255 symbols
phone	string	User phone number	2-15 symbols
invite	string	Client invitation text	1000 symbols
group	string	The department the client applies to	10 digits
intent	string	Subject of the customer's request	255 characters
crm_link	string	Client URL in CRM system	2048 characters

Message

Field	Type	Description	Max size
type	string	Message type, required parameter	Limited to allowable values, see the options in the table
id	string	Message identifier, required if you want to change the status of a message after it has been sent	500 characters
date	number	Message creation/sending time, integer	Limited to reasonable UNIX time
file	string	Media URL	2048 characters, valid scheme https or http
thumb	string	Media preview image URL	2048 characters, valid https or http scheme
file_size	number	Size of media data in octets (bytes)	Positive integer, limited by client applications
width	number	Image or video width in pixels	Positive integer, limited by client applications
height	number	Image or video height in pixels	Positive integer, limited by client applications
file_name	string	Media data file name	255 characters, may not be compatible with legacy file systems!
mime_type	string	MIME type of media data	Limited to the list of allowed values
text	string	Message text	It is recommended to limit the length to 1000 characters, if it is exceeded, the rest of the text will be sent in separate text messages
title	string	Post title	255 characters
latitude	number	Location latitude, real number	from -90.0000 to +90.0000
longitude	number	Location longitude, real number	-180.0000 to +180.0000
value	number	Number, usually used in the chat evaluation	any number
keyboard	[]Key	Array of Key structures	7 keys
multiple	boolean	Allows multiple selection on the keyboard, boolean	true or false

Key

It is mandatory for a key to have one structure field, both in the keyboard request and in the response. See example for details.The priority of fields for display to the user is recorded in the table in descending order.

Field	Type	Description	Max size
text	string	Key text	100 characters
image	string	Image URL (https or http scheme)	2048 characters
title	string	Title or tooltip key	100 characters
id	string	Key ID	500 characters

Message types

Type	Description	Required fields
text	Text message	text
photo	Image	file
sticker	Sticker	file
video	[Video message](#video message)	file
audio	Audio message	file
document	Document or file, in a message of this type, you can send any files that are allowed to be transferred to Jivo.	file
location	Location	latitude longitude
rate	[Chat rating](#Chat rating)	value
seen	Message read event, in the id field, you must specify the ID of the message you read	id
keyboard	Keyboard with options, details in the example	keyboard
typein	typing event, in the text field of this message, you can write the typed text so that it is visible to the Jivo user. Send this event no more than once every 5 seconds from one client	-
start	Start chat, intended to start a chat without sending a message by the client	-
stop	End chat, a signal that events for this client are no longer accepted	-

Event Examples

Jivo Event Examples

If at least one sender property is defined for the Jivo user, a sender field with this information is added to the event. The recipient of the message is identified by the recipient.id field.

{
    "sender": {
        "id": "XXX",
        "name": "Consultant",
        "photo": "https://example.com/avatar.png",
        "email": "info@jivosite.com"
    },
    "recipient": {
        "id": "001"
    },
    "message": {
        "type": "text",
        "id": "0000",
        "date": 946684800,
        "text": "Hello!"
    }
}

Keyboard with answer options

The keyboard can only be sent from a Jivo user to a client:

{
    "recipient": {
        "id": "001"
    },
    "message": {
        "type": "keyboard",
        "id": "0009",
        "title": "Опрос",
        "text": "To be or not to be?",
        "multiple": false,
        "keyboard": [
            {
                "id": "1",
                "text": "yes"
            },
            {
                "id": "2",
                "text": "no"
            },
            {
                "id": "X",
                "text": "need to think..."
            }
        ]
    }
}

It is expected that the client's response to such a message will be one element from the keyboard array, if multiple != true:

{
    "sender": {
        "id": "001"
    },
    "message": {
        "type": "keyboard",
        "id": "0009",
        "multiple": false,
        "keyboard": [
            {
                "id": "X",
                "text": "need to think..."
            }
        ]
    }
}

or more, if multiple = true.

If the client’s app does not support a keyboard with answer options, it is recommended to convert this type of message to a text list for display to the client, for example:

 Survey

 To be or not to be?
   1) yes
   2) no
   X) need to think...

The response to the keyboard message can be a text message, for example:

{
    "sender": {
        "id": "001"
    },
    "message": {
        "type": "text",
        "text": "need to think..."
    }
}

The following are examples of events to send to Jivo..

Chat start

On the first event from the client, it is recommended to fill in the sender structure. Further, the sender.id field is enough, and the remaining fields of this structure can be filled only when they change.

{
    "sender": {
        "id": "001",
        "name": "Ivan Ivanovich",
        "photo": "https://example.com/me.jpg",
        "url": "https://example.com/",
        "phone": "+7(958)100-32-91",
        "email": "me@example.com",
        "invite": "Hello! May I help you?"
    },
    "message": {
        "type": "start"
    }
}

Text message

{
    "sender": {
        "id": "001"
    },
    "message": {
        "type": "text",
        "id": "0001",
        "date": 946684800,
        "text": "Hello!"
    }
}

Image

{
    "sender": {
        "id": "001"
    },
    "message": {
        "type": "photo",
        "id": "0002",
        "date": 946684800,
        "file": "https://example.com/image.png",
        "mime_type": "image/png",
        "file_name": "image.png",
        "file_size": 1024,
        "thumb": "https://example.com/image_thumb.png",
        "width": 800,
        "height": 600,
        "title": "Title",
        "text": "Image comment."
    }
}

Sticker

{
    "sender": {
        "id": "001"
    },
    "message": {
        "type": "sticker",
        "id": "0003",
        "date": 946684800,
        "file": "https://example.com/sticker.gif",
        "mime_type": "image/gif",
        "file_name": "sticker.gif",
        "file_size": 1024,
        "width": 256,
        "height": 256
    }
}

Video message

{
    "sender": {
        "id": "001"
    },
    "message": {
        "type": "video",
        "id": "0004",
        "date": 946684800,
        "file": "https://example.com/video.mp4",
        "mime_type": "video/mp4",
        "file_name": "video.mp4",
        "file_size": 1048576,
        "thumb": "https://example.com/video_thumb.png",
        "width": 640,
        "height": 480,
        "title": "Title",
        "text": "Video comment."
    }
}

Audio message

{
    "sender": {
        "id": "001"
    },
    "message": {
        "type": "audio",
        "id": "0005",
        "date": 946684800,
        "file": "https://example.com/audio.mp3",
        "mime_type": "audio/mpeg",
        "file_name": "audio.mp3",
        "file_size": 2048,
        "title": "Title",
        "text": "Audio message comment."
    }
}

Document or file

{
    "sender": {
        "id": "001"
    },
    "message": {
        "type": "document",
        "id": "0006",
        "date": 946684800,
        "file": "https://example.com/document.pdf",
        "mime_type": "application/pdf",
        "file_name": "document.pdf",
        "file_size": 512,
        "title": "Title",
        "text": "Document comment."
    }
}

Location

{
    "sender": {
        "id": "001"
    },
    "message": {
        "type": "location",
        "id": "0007",
        "date": 946684800,
        "text": "It's here.",
        "latitude": 53.3416484,
        "longitude": -6.2868531
    }
}

Chat rating

At the moment, 3 options for the value field are used: 0 is interpreted as a refusal to rate, a positive number - a positive rating, a negative number - a negative chat rating.

{
    "sender": {
        "id": "001"
    },
    "message": {
        "type": "rate",
        "id": "0008",
        "value": 1
    }
}

Typing event

{
    "sender": {
        "id": "001"
    },
    "message": {
        "type": "typein",
        "text": "Wait a minute"
    }
}

Message read event

{
    "sender": {
        "id": "001"
    },
    "message": {
        "type": "seen",
        "id": "0001"
    }
}

Chat end

{
    "sender": {
        "id": "001"
    },
    "message": {
        "type": "stop"
    }
}

Problem solving

If you find inaccuracies in this memo, or if it does not correspond to reality, please report it to the support chat [Jivo] (https://www.jivo.ru/) or to [email] (mailto:info@jivosite.com?subject=Chat %20API).