Chat API
This memo describes how to exchange events between servers through the Chat API channel when integrating with JivoChat. Chat API channel is asynchronous and bidirectional, a custom server is required capable of receiving and sending events.
Channel protocol#
Transport protocol for the event transmission is HTTPS (at the development stage it is allowed to use HTTP). An event is contained in a body of a POST-request in JSON format (note: text encoding in JSON format is UTF-8), requests must have an appropriate header Content-Type: application/json; charset=utf-8
. Event structure is described further. Response options are divided into 3 groups according to the HTTP-response code.
Code | Description | Action |
---|---|---|
2xx | Success. Event is accepted for processing | Inform the user about successfull delivery |
4xx | Request failed. Event rejected | There may be a description of the error (type of content Content-Type: text/plain; charset=utf-8) in the body of the response. This event should not be resubmitted. It is necessary to find and correct the error of the program or channel settings that led to the error. Inform the user about the event delivery failure |
Any other HTTP code or connection error | The request cannot be accepted at this time. Event is not accepted | In case of an HTTP code 5xx or if connection fails it is recommended to resend 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 API channel in JivoChat, use the JivoChat app. Once created, a URL, that you can use to send events to JivoChat, will be available to you in the settings of the channel, for example: https://wh.jivosite.com/foo/bar
. To receive messages from JivoChat, set up 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
at the end of the URL for sending events to JivoChat (for example, https://wh.jivosite.com/foo/bar/status
), then in the body of a response to a GET-request you will get a status of the channel, where 0
means the absence of online agents, and 1
or any other means the presence of agents online. This only works if it's a successful response with the code 2xx
.
Event structure#
Protocol is symmetric, and protocol structure is the same for events from JivoChat to a client server and back.
Field | Type | Description |
---|---|---|
sender | User | Message sender |
recipient | User | Message recipient |
message | Message | Message text |
User#
Field | Type | Description | Max size |
---|---|---|---|
id | string | Client identificator, required parameter when sending events to JivoChat sender.id and when receiving events from JivoChat recipient.id | 255 symbols |
name | string | Username | 255 symbols |
photo | string | User avatar URL, valid https or http schemes | 2048 symbols |
url | string | User page URL, valid https or http schemes | 2048 символов |
string | User email | 255 symbols | |
phone | string | User phone number | 2-15 symbols |
invite | string | Client invitation text | 1000 symbols |
group | string | Department a client applies to | 10 digits |
intent | string | Subject of a customer's request | 255 characters |
crm_link | string | Client URL in a CRM system | 2048 characters |
Message#
Field | Type | Description | Max size |
---|---|---|---|
id | string | Message identificator, 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 | Message 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
response. See example for details. Priority of fields for
display to the user is shown 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 JivoChat app | file |
location | Location | latitude longitude |
rate | [Chat rating](#Chat rating) | value |
that was read | id | |
keyboard | Keyboard with options, details in the example | keyboard |
typein | typing event, in the text field of this message you can send the typed text so that it is visible to the JivoChat app user. Send this event no more than once every 5 seconds from one client | - |
start | Start chat, it's intended to start a chat without sending a message by the client | - |
stop | End chat, a signal that events for this chat are no longer accepted | - |
Event Examples#
JivoChat Event Examples#
If at least one sender property is defined for the JivoChat 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 JivoChat app user to a client:
{ "recipient": { "id": "001" }, "message": { "type": "keyboard", "id": "0009", "title": "Questionnaire", "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 than one, if multiple = true
.
If client’s app does not support a keyboard with answer options, it is recommended to convert this type of message to a text list to 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 JivoChat.
Chat start#
Upon the first event from the client, it is recommended to fill the sender
structure. Then the sender.id
field will be enough, and the remaining fields of this structure can be filled only when they change.
{ "sender": { "id": "001", "name": "John Doe", "photo": "https://example.com/me.jpg", "url": "https://example.com/", "phone": "+1 234 568 890", "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 refuse 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, please report them to us in chat JivoChat or to email.