Chat 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 символов |
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).