JivoChat Chat API

Included for free in plans
VIP

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 valueRequired additional fieldsType
videofile, file_name, file_sizevideo
audiofile, file_name, file_sizeaudio
voicefile, file_name, file_sizevoice message
photofile, file_name, file_sizeimage
stickerfile, file_name, file_sizesticker
documentfile, file_name, file_sizefile (link to file)
locationlatitude, longitudegeo-location

Optional multimedia message fields are listed below:

Multimedia message fieldDescription
string filehttp(s) file url
string thumbhttp(s) url for thumb image(w320px)
string emojipossible replacement of media with a unicode character
number file_sizefile size in bytes, integer positive
string file_nameuser-defined file name
number durationflow duration in seconds, integer positive
number widthwidth in pixels, integer positive
number heightheight in pixels, integer positive
string texttext message or comment
string performerauthor (composer, performer, etc.)
string titletitle
number latitudereal latitude
number longitudereal 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.

Related articles
Have questions?
Ask in the live chat, we are ready to help around the clock