Documentation

Bot API

Using Bot API you can connect a chatbot to your account to process incoming chats. The events exchange works via the webhooks mechanism. The initiator of the exchange is Jivo.

All events from Jivo to the bot provider and back are sent as HTTPS requests using the POST method in application/json format. The request timeout is 3 seconds, with 2 retries until a regular successful response is received. If not, the chat is transferred to the agent. This gives bot-providers 9 seconds to update the software on the server which is enough in most cases.

Event types

Message typeDirectionDescription
CLIENT_MESSAGEJivo API → Bot-ProviderNew client message event, that requires response options
BOT_MESSAGEBot-Provider → Jivo APIBot's response to a client message
INVITE_AGENTBot-Provider → Jivo APIChat transfer from a bot to an agent
AGENT_UNAVAILABLEJivo API → Bot-ProviderEvent, informing that no agents are available to accept the chat at the moment
CHAT_CLOSEDJivo API → Bot-ProviderChat closing event
CLIENT_INFOBot-Provider → Jivo APIEvent with a client's contact information

CLIENT_MESSAGE

This event is intended to transfer a client's message to the bot provider. The request with the message is processed, and the bot's response is sent into the chat.

Example

{ "id": "9661ab9c-48b0-11ed-a3d6-859398ff9bd9", "site_id": "123456", "client_id": "1233", "chat_id": "2037", "agents_online": true, "sender": { "id": 1233, "name": "John Smith", "url": "https://test.com", "has_contacts": true }, "message": { "type": "TEXT", "text": "Can you help me?", "timestamp": 1665415879 }, "channel": { "id": "12345678", "type": "widget" }, "event": "CLIENT_MESSAGE" }

Event parameters

NameTypeDescription
idstringUnique event ID used for debugging
site_idstringJivo account ID, to which a request belongs
client_idstringID of a client, who writes to one of the JivoChat channels Unique within the account
chat_idstringID of a chat, where conversation takes place Unique within the account
agents_onlinebooleanAgent status identifier (if the value is true, agents are online; false - agents are offline)
senderobjectInformation about the client
messageobjectInformation about the message that was sent
channelobjectInformation about the channel where the message was sent
eventstringEvent type

sender

НаименованиеТипОписание
idintID of a client (similar to client_id)
user_token optionalstringClient's ID sent using API-method
name optionalstringClient's name
urlstringURL of a page, from which a client sent a message
has_contactsbooleanInforms, whether a client has contacts details or not

message

NameTypeDescription
typestringMessage type
textstringMessage text
timestampintTime logging parameter

channel

NameTypeDescription
idstringID of the channel where the message was sent
typestringChannel type

BOT_MESSAGE

This request type is used to transmit a bot response to a chat with a client. It is sent from bot provider to Jivo endpoint.

Example

{ "id": "093e9c6a-48b6-11ed-907d-7d426317dad5", "client_id": "1235", "chat_id": "2041", "message": { "type": "BUTTONS", "title": "Would you like to make an order?", "text": "Would you like to make an order? Yes / No", "timestamp": 1583910736, "force_reply": true, "buttons": [ { "text": "Yes", "id": 1 }, { "text": "No", "id": 2 } ] }, "event": "BOT_MESSAGE", }

Event parameters

NameTypeDescription
idstringUnique event ID used for debugging
client_idstringID of a client, who writes to one of the JivoChat channels Unique within the account
chat_idstringID of a chat where conversation takes place Unique within the account
messageobjectBot message

Bot messages types

1. TEXT

Simple text message

  • Example
{ "message": { "type": "TEXT", "text": "Hello! How can I help you?", "timestamp": 1653127681833 }, }
NameTypeDescription
textstringMessage text
timestampintTime logging parameter, unix time
2. MARKDOWN

Text message in Markdown format

  • Example
{ "message": { "type": "MARKDOWN", "content": "To disable **PUSH notifications** please follow the steps described in our [instructions](https://site.com/page_url)", "text": "To disable PUSH notifications please follow the steps described in our instructions https://site.com/page_url", "timestamp": 1583910736 }, }
NameTypeDescription
сontentstringMessage in Markdown format (the following styles are supported: link, bold, italic)
textstringText fallback for channels that don't support markdown format. If not specified, a message won't be sent to a client
timestampintTime logging parameter, unix time
3. BUTTONS
  • Example
"message": { "type": "BUTTONS", "title": "Would you like to make an order?", "text": "Would you like to make an order? Yes / No", "force_reply": true, "buttons": [ { "text": "Yes", "id": 1 }, { "text": "No", "id": 2 } ], "timestamp": 1583910736, }
NameTypeDescription
titlestringText title for buttons
textstringText fallback for channels that don't support markdown format. If not specified, a message won't be sent to a client
force_reply optionalbooleanIf there is true value, the message input field is blocked, so a client chooses one of the suggested buttons
buttonsarraySet of buttons with canned replies
buttons.textstringCanned reply text
button.idstringID of a button, sent in chat

INVITE_AGENT

The event is sent from bot-provider to Jivo if it is required to transfer a chat to an agent.

Example

{ "id": "123e4567-e89b-12d3-a456-426655440000", "client_id": "1234", "chat_id": "213123", "event": "INVITE_AGENT" }

Event parameters

NameTypeDescription
idstringUnique event ID used for debugging
client_idstringID of a client, who writes to one of the JivoChat channels Unique within the account
chat_idstringID of a chat where conversation takes place Unique within the client's account

AGENT_UNAVAILABLE

The following event is sent from Jivo to bot-provider in case if bot transfers a chat to agents and there are no agents online ready to accept a chat. After processing this request bot can continue communicating with a client, for example, it can request contacts from a user.

Example

{ "id": "f061d944-48bc-11ed-a11a-9b4e3e49df1b", "chat_id": "2043", "client_id": "1236", "event": "AGENT_UNAVAILABLE" }

Event parameters

NameTypeDescription
idstringUnique event ID used for debugging
client_idstringID of a client who writes to one of the channels Unique within the client's account
chat_idstringID of a chat where conversation takes place Unique within the account

CHAT_CLOSED

This type of request is sent when an agent accepts a chat, or it is automatically closed by timeout. If bot provider receives this event, the bot will no longer be able to send messages to this chat.

Example

{ "id": "f9e59d98-48bc-11ed-896a-47ed16cbbd46", "chat_id": "2043", "client_id": "1236", "event": "CHAT_CLOSED" }

Event parameters

NameTypeDescription
idstringUnique event ID used for debugging
client_idstringID of a client who writes to one of the channels Unique within the client's account
chat_idstringID of a chat where conversation takes place Unique within the account

CLIENT_INFO

This event is used for transferring client contact details from bot provider to Jivo in response to a client message. Contacts will be displayed in the agent application as if a client has filled in the contacts form in the chat.

Example

{ "id": "996344da-d8f4-11ec-9aaf-c5bde7170335", "client_id": "1237", "client": { "email": "jason@gmail.com", "phone": "+16568925593", "name": "Jason" }, "event": "CLIENT_INFO" }

Event parameters

NameTypeDescription
idstringUnique event ID used for debugging
client_idstringID of a client who writes to one of the channels Unique within the client's account
clientobjectObject containing client contact information (email, phone, name)

The integration workflow and description of possible errors can be found in our help base article. In case of any questions please feel free to contact us by email info@jivochat.com or in chat.