JivoChat Chat API
Chat API allows you to organize the processing of customer requests from any sources, both from mobile and desktop applications, or a fully customized widget on a website. Agents receive calls to the JivoChat application in a completely similar manner to other channels.
The Webhooks mechanism is used for this integration. JivoChat provides an endpoint for receiving channel statuses and for transmitting clients messages, and on the side of an integrated system, there must be an endpoint for transmitting the agent’s response to the client.
The JivoChat endpoint contains a random string to protect against brute force, as well as the channel identifier JIVO_PUBLIC_ID.
To generate your unique JivoChat endpoint, login to your JivoChat web app or one of our Desktop apps, then go to Manage -> Add Channels -> Chat API.
Click to Connect chat API.
Insert a channel name, your webhook server URL, activate or not the chunked encoding option, choose which agents will be assigned to receive chats from the channel you're creating and click to Add channel once you're finished.
Now your unique JivoChat endpoint URL is ready to be used.
That's it! Now all you have to do is check the rest of our instructions below to understand how to work with the generated endpoint.
General principle of work
Main workflow of the integration
title JivoSite-Webhooks Channel
Customer API->JivoSite: Channel Status HTTP GET
JivoSite->Customer API: Online (1)
Customer API->User: Show custom chat window
User->Customer API: Type User Message
Customer API->JivoSite: User Message HTTP POST
JivoSite->Agent: User Message
Agent->JivoSite: Agent Message
JivoSite->Customer API: Agent Message HTTP POST
Customer API->User: Draw Agent Message
Protocol description
Customer API->JivoSite: Chat Status
GET https://wh.jivosite.com/<some random string>/JIVO_PUBLIC_ID/status
The standard answer is 200 OK, with the body as an integer:
0 - chat is not available. Agents are offline or the chat is removed from the website
1 - chat is available. Agents are online
If there is no channel in JivoSite with JIVO_PUBLIC_ID, the server will return an HTTP with status 404.
If the answer is irregular, it is advisable to notify us immediately.
Customer API->JivoSite: User Message
POST https://wh.jivosite.com/<some random string>/JIVO_PUBLIC_ID
{
"sender" :
{
"id" : "12345",
"name" : "John Doe",
"photo" : "https://example.com/photo.jpg",
"url" : "https://ya.ru/simple/page.html",
"phone" : "12345678901",
"email" : "john@doe.сom",
"invite" : "Hello! Can I help you?"
},
"message" :
{
"type" : "text",
"id" : "customer_message_id",
"text" : "User Message Text"
}
}
sender.id - (required string or integer) customer identifier in the Customer API. If this field is empty/absent, the message will not be transmitted.
sender.name, phone, email - optional fields (string). If JivoSite receives them, it will display the information received to the agent. If not, the client’s info in chat will be shown as Anonymous. These values can be updated during a chat.
sender.photo - optional link to the client’s avatar image. The link should begin with "http: //" or "https: //". The recommended image size is 128 * 128 px png | jpg | gif. The application will try to display those images, but the correctness of the display is not guaranteed.
sender.invite - optional invitation text. It works similarly to the function "invitation on behalf of an agent" (trigger action) in the widget. The logic of displaying the invitation is implemented in the chat on the Customer API side, while the invitation text can be sent to the sender.invite field and agents will be able to see it and understand the context in which the client has addressed them.
message.id - message identifier in the Customer API. It will not be visible anywhere except in logs. It will be used in the next version for the delivery / read notification.
message.type - (required) - "text" constant. Other types of messages are not yet supported, but will be supported in the future.
message.text - (required for type == text) - client message string with up to 1000 characters. If there are more than 1000 characters, we will cut the message.
The standard answer is 200 OK. If the response code is different from 200, it is advisable to notify us immediately.
If there is no channel in JivoSite with JIVO_PUBLIC_ID, the server will return an HTTP with status 404.
JivoSite->Customer API: Agent Message
POST <Customer API HTTPS-endpoint URL>/JIVO_PUBLIC_ID
{
"sender" : {
"name" : "Agent Name",
"photo" : "Agent Photo URL"
},
"recipient" : {
"id" : "12345"
},
"message" : {
"type" : "text",
"id" : "jivo_message_id",
"text" : "Agent Message Text"
}
}
sender.name - name of the agent who wrote the message.
sender.photo - image link - agent avatar.
recipient.id - customer identifier in the Customer API. We will receive it from the incoming message and transmit it back unchanged.
message.id - message identifier in JivoSite. It will be used in the future for delivery / read notifications.
The standard answer is 200 OK.
Body response in JSON format:
{
"result" : "ok"
}
or
{
"error" :
{
"code" : <error code>,
"message" : "<human-readable error message>"
}
}
An error message will be displayed to the agent in the JivoSite conversation. It may not be displayed depending on the error code.
Message Record Notification
For the notification of a message set, a message with the type indication is used:
type: "typein" - the beginning of a message set.
type: "typeout" - the end of a message set.
Other fields in the message with this type are ignored.
It works identically in both directions, from JivoSite in the Customer API and from the Customer API in JivoSite.
Multimedia messaging
Multimedia messages are transmitted in the same way as text messages, but they have a special type and additional fields. The composition of the required fields and the value of the type field for each supported media type are listed below.
| Type field value | Required additional fields | Type |
|---|---|---|
| video | file, file_name, file_size | video |
| audio | file, file_name, file_size | audio |
| voice | file, file_name, file_size | voice message |
| photo | file, file_name, file_size | image |
| sticker | file, file_name, file_size | sticker |
| document | file, file_name, file_size | file (link to file) |
| location | latitude, longitude | geo-location |
Optional multimedia message fields are listed below:
| Multimedia message field | Description |
|---|---|
| string file | http(s) file url |
| string thumb | http(s) url for thumb image(w320px) |
| string emoji | possible replacement of media with a unicode character |
| number file_size | file size in bytes, integer positive |
| string file_name | user-defined file name |
| number duration | flow duration in seconds, integer positive |
| number width | width in pixels, integer positive |
| number height | height in pixels, integer positive |
| string text | text message or comment |
| string performer | author (composer, performer, etc.) |
| string title | title |
| number latitude | real latitude |
| number longitude | real longitude |
Re-send messages
Events, in the form of http (s) requests, are sent to the Customer API server 3 times every 3 seconds, until a valid positive response is received. This gives 6 seconds to update the software on the server, which is enough in most cases. If the server is unavailable, an error event will return after 9 seconds. These default settings allow you to quickly receive a response from the sender. In case of a timeout or Customer API error, the agent will see an error message in chat.
Chunked-request
JivoSite can send requests to the Customer API both with the Content-Length field and in the Chunked encoding.
