JivoSite Chat API

Choose another article

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 Jivo application in a completely similar manner to other channels.

The Webhooks mechanism is used for this integration. Jivo 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 Jivo endpoint contains a random string to protect against brute force, as well as the channel identifier JIVO_PUBLIC_ID.

To generate your unique Jivo endpoint, login to your Jivo 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 Jivo 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.

Do you still have any questions? Our support team will be more than happy to help you 24x7 in the chat on our site.