External Bot API 2.0

Rox.Chat supports the connection of "external" or "smart" bots, which are hosted on an external server relative to the Rox.Chat server, using the External Bot API 2.0. The previous version of the External Bot API is also preserved and subsequent versions to support compatibility, meaning that both API versions are supported.

Description

Unlike the previous version, External Bot API 2.0 is asynchronous. The bot receives a question from the user and sends it to the external server. The server generates a response and sends it back to the Rox.Chat service, which displays it to the user. In this case, the Rox.Chat server does not wait for a response from the bot server: the bot sends its response whenever it is ready. Unlike the previous version of the External Bot API, it is not necessary to respond immediately; it is only required to return a 200 code upon successful request execution, and the response can be formulated later.

General Logic

All online chats that come to the department to which the External Bot API bot is added are automatically assigned to the bot. The bot's online status affects the overall online status of the system:

If the bot is Online, it will accept all chats from users, and the button on the website will display Online.
If the bot is Invisible and there are no online agents, it will accept all chats from users, but the button on the website will display Offline.
If the bot is Offline, it will not accept any chats (and will not affect the online status of the button).

Configuration

Instructions for configuring and connecting a smart bot are applicable to the current version of the Rox.Chat service.

To connect an external bot to the Rox.Chat service:

Create a new agent account using the Control Panel.
Go to the settings of your account and select the Bots section.
In the opened window, click the Create a New Bot button.
Fill in the information about your bot: assign it to a new agent, select Smart bot as the bot type, and choose version 2.
In the External API Link field, enter the URL address of the external server for the bot.
Save the changes.
After saving, an authorization token for requests will be automatically generated for you and displayed in the Token field.

Base URL

The URL structure on the Rox.Chat side is as follows:

https://{hostname}/api/bot/v2/{path} where {hostname} is the host name where the Rox.Chat server is located, such as {account}.rox.chat for cloud clients and chat.mycompany.com for hosted clients; {path} is the API command.

List of External Bot API 2.0 endpoints:

/api/bot/v2/send_message
/api/bot/v2/redirect_chat
/api/bot/v2/close_chat
/api/bot/v2/file/{guid}?hash={hash}

Example URL:

https://mycompany.rox.chat/api/bot/v2/redirect_chat

This request will transfer the chat to an agent.

N.B.

The URL from the bot side is set in the settings.

Rox.Chat Requests

Below are examples and descriptions of requests to the Rox.Chat Server. Requests are sent to the URL specified when creating the bot.

Authorization

Authorization is done through a header using a token. A new token is generated for each bot.

Format of the authorization token:

Authorization: Token {token}

Example authorization token:

Authorization: Token ac650a3c369a4b9599ad52ab71943712

Error Handling

Rox.Chat responds with an HTTP code of 200 in case of success.

Errors are returned in the format:

{
    "error": "error code"
}

If a request fails validation, it returns an HTTP code of 400.

In case of authorization error, it returns an HTTP code of 403.

If a robot with the specified token is not found, it returns an HTTP code of 403.

If a method not described below is used, it returns an error of 404 {'error': 'method-not-found'}.

In case of different internal server errors, an error with an HTTP code of 500 is returned.

If the token is missing, the server will return an error:

{
    "error": "unauthorized"
}

Other errors come with an HTTP code of 200 in the following format:

{
    "error": "error code",
    "desc": "error description"
}

Error fields description:

Field	Type	Example	Description	Mandatory
`error`	`String`	`incorrect-request`	Error code.	Yes
`desc`	`String`	The request is formed incorrectly. It is possible that mandatory parameters are missing.	Error description in English.	No

Response of the Chatbot to a Visitor's Question

Path: /send_message

Request Type: POST

Content-type: application/json

Query-string parameters: Not needed

Example URL for sending a message from the bot to the visitor:

POST https://mycompany.rox.chat/api/bot/v2/send_message

Example Request Body for sending a message from the bot:

{
    "message": Message,
    "chat_id": 3058
}

Description of fields in the response object when sending a message from the bot:

Field	Type	Description	Mandatory
`message`	`JSON`	`Message` object	Yes
`chat_id`	`Integer`	Chat identifier	Yes

The Message object may have different fields depending on the type of message.

Text Message

Example content of the Message object in a text message:

{
    "kind": "operator",
    "text": "Hello, how can I help you?"
}

Description of fields in the Message object in a text message:

Field	Type	Example	Description	Mandatory
`kind`	`String`	`operator`	Type of message. In this case, it is a text message with `kind = "operator"`. All message types you can find here	Yes
`text`	`String`	`Hello, I need your consultation on pricing plans`	Content of the text message.	Yes

Description of possible errors in a text message:

Error Code	Description
`message-not-created`	Failed to create the message. The request might have been formed incorrectly.
`incorrect-request`	Request formed incorrectly. Mandatory parameters might be missing.
`chat-not-found`	The chat with the specified id was either not found, not assigned to the bot, or the dialogue is inactive (closed, transferred to the general queue, etc.).

File Message

Warning!

**External Bot API does not provide the ability to upload a file to the chat server using this method. In case you have any questions regarding this method or uploading files to the chat server, please contact technical support or your account manager.

An example of the contents of a Message object for a file message:

{
    "kind": "file_operator",
    "data": {
        "url": "https://rox.chat/uploads/2019/04/diagram.png"
        "name": "diagram.png",
        "media_type": "image/png"
    }
}

Description of the Message object fields for a file message:

Field	Type	Example	Description	Mandatory
`kind`	`String`	`file_operator`	Type of message. In this case, it is a text message with `kind = "file_operator"`. In this case, these are agent messages containing the files sent. All message types you can find here	Yes
`data.url`	`String`	`https://somesite.com/img54-65-79.jpg`	URL of the file.	Yes
`data.name`	`String`	`beautifulpicture.jpg`	The name of the file. The name must contain an extension. The bot can send files with extensions specified by the `robot_allowed_upload_file_types` parameter of the account config settings.	Yes
`data.media_type`	`String`	`image/jpeg`	Internet Media Type. The bot can send files with media types specified by `robot_allowed_upload_file_content_types`. You can also impose restrictions on the size of files sent by the bot.	Yes

Description of possible errors in the file message:

Error Code	Description
`insecure-file-type`	File has not passed security checks.
`incorrect-image`	Incorrect image file.
`media-type-not-match`	The declared Media Type does not match the actual Media Type.
`max-file-size-exceeded`	The file size exceeds the allowed size.
`message-not-created`	Message could not be created. The request may have been generated incorrectly.
`chat-not-found`	A chat with the specified id was either not found, not assigned to a robot, or the dialog is inactive (because it was closed, moved to the general queue, etc.).
`incorrect-request`	The request was formed incorrectly. It is possible that mandatory parameters are missing.

Message with Buttons

An example of the Message object content for a message with buttons:

{
    "kind": "keyboard",
    "buttons": [
        {
            "text": "Transfer to tech support",
            "id": "fedc60c4dc0d4348b48b524d"
        },
        {
            "text": "Transfer to sales department",
            "id": "574f2caad88a41a7a2d6b667"
        }
    ]
}

Description of the fields of the Message object for a message with buttons:

Field	Type	Description	Mandatory
`kind`	`String`	Message type. Messages with buttons are of type `keyboard` or `keyboard_response`. All message types you can find here	Yes
`buttons`	`list`	A nested array containing data about buttons sent to the visitor. Allows grouping sets of buttons offered to the visitor into strings.	Yes

Each Button object contains the following parameters in the array:

Field	Type	Example	Description	Mandatory
`id`	`String`	`937bec4863154a2fb0889ff1`	The identifier of the button. Can contain only Latin letters, digits, hyphen and underscore characters and must be no more than 24 characters long. The button ID generated by the Rox.Chat server is in `UUID4` format, while the ID generated by third-party bots is only checked for compliance with the above criteria.	Yes
`text`	`String`	Ask a question to an agent	The text of the button.	Yes

Description of possible errors in the button message:

Error Code	Description
`incorrect-buttons`	File failed security check.
`message-not-created`	Message could not be created. The request may have been generated incorrectly.
`chat-not-found`	A chat with the specified id was either not found, not assigned to a robot, or the dialog is inactive (because it was closed, moved to the general queue, etc.).
`incorrect-request`	The request was formed incorrectly. It is possible that mandatory parameters are missing.

Chat Transfer

A chat can be transferred to a specific agent, department, or to the general queue. If no agent or department is specified for transfer, the chat will be redirected to the general queue. If both an agent and a department are specified, the request will not be executed correctly and the chat will not be redirected (it is necessary to specify one of them).

Path: /redirect_chat

Request type: POST

Content-type: application/json

Query-string parameters: not needed

Example of URL when translating a chat:

POST https://mycompany.rox.chat/api/bot/v2/redirect_chat

Transfer to Agent

Example of request body when translating chat to an agent:

{
    "operator_id": 486254,
    "chat_id": 195
}

Description of the object fields in the response to the request when transferring a chat to an agent:

Field	Type	Example	Description	Mandatory
`operator_id`	`Integer`	`168524`	Agent ID.	Yes
`chat_id`	`Integer`	`426`	The identifier of the chat.	Yes

Description of possible errors when transferring a chat to an agent:

Error Code	Description
`operator-not-found`	An agent with the specified ID was not found.
`target-is-offline`	Agent is offline.
`chat-not-found`	A chat with the specified ID was either not found, not assigned to a robot, or the dialog is inactive (because it was closed, moved to the general queue, etc.).
`incorrect-request`	The request was formed incorrectly. It is possible that mandatory parameters are missing.

Transfer to Department

An example of a request body when transferring a chat room to a department:

{
    "dep_key": "sales_department",
    "chat_id": 425,
    *"allow_redirect_to_offline_dep": false,
    *"allow_redirect_to_invisible_dep": true
}

Description of the object fields in the response to the request when the chatid is translated to a department:

Field	Type	Example	Description	Mandatory
`dep_key`	`String`	`sales_department`	The identifier (text key) of the department.	Yes
`chat_id`	`Integer`	`168`	Chat identifier.	Yes
`allow_redirect_to_offline_dep`	`Boolean`	`false`	Whether to redirect a chat to a department if all agents are offline. Correspondingly, the conversations are also transferred when agents in other statuses - Invisible and others. Default is `false`.	No
`allow_redirect_to_invisible_dep`	`Boolean`	`true`	Whether to transfer a chat to a department if there are no online agents in it - it is enough for an agent to be in the status Invisible or similar. If `allow_redirect_to_offline_dep` is enabled, then the `allow_redirect_to_invisible_dep` functionality is automatically enabled, as it is a stronger property. Thus, this parameter differs from the previous parameter in that when enabled, chats are not transferred only to departments where all agents are in Offline status. The default is `true`.	No

N.B.

Of the two parameters - allow_redirect_to_offline_dep and allow_redirect_to_invisible_dep - only one can be present in the request body; otherwise, the server will return an error in response to the request.

Description of possible errors when transferring chat to department:

Error Code	Description
`department-not-found`	The department with the specified ID was not found.
`target-is-offline`	Department is offline.
`chat-not-found`	A chat with the specified ID was either not found, not assigned to a robot, or the dialog is inactive (because it was closed, moved to the general queue, etc.).
`incorrect-request`	The request was formed incorrectly. It is possible that mandatory parameters are missing.

Transfer to General Queue

An example of a request body when transferring a chat to the general queue:

{
  "chat_id": 425
}

Description of the object fields in the request response when transferring a chat to an agent:

Field	Type	Example	Description	Mandatory
`chat_id`	`Integer`	`426`	Chat ID.	Yes

Closing Chat

Path: /close_chat

Request type: POST

Content-type: application/json

Query-string parameters: not needed

Example URL when closing a chat:

POST https://mycompany.rox.chat/api/bot/v2/close_chat

Example of request body when closing a chat:

{
    "chat_id": 462
}

Description of the object fields in the response to the request when closing a chat:

Field	Type	Example	Description	Mandatory
`chat_id`	`Integer`	`426`	Chat ID.	Yes

Description of possible errors when closing a chat:

Error Code	Description
`chat-not-found`	A chat with the specified ID was either not found, not assigned to a robot, or the dialog is inactive (because it was closed, moved to the general queue, etc.).
`incorrect-request`	The request was formed incorrectly. It is possible that mandatory parameters are missing.

File Download

With this request, the client can download a file sent by a visitor in a chat with the bot.

Path: /file/{guid}?hash={hash}

Request type: GET

Query-string parameters: hash - calculated hash

Example URL when downloading files:

GET https://mycompany.rox.chat/api/bot/v2/file/7d5d197ef3ee4b29be6b1a668977ccdc?hash=e96881ac8db26e8570cd9c032900cd3e0b08128132e61c844102633c64a69b2a

Where:

7d5d197ef3ee4b29be6b1a668977ccdc - GUID (unique identifier) of the file;
e96881ac8db26e8570cd9c032900cd3e0b08128132e61c844102633c64a69b2a - hash signature of the file, which helps to secure the file from unwanted downloading.

This URL will result in the client downloading the file sent by the visitor in chat.

The link to download the file comes inside a message that has kind = file_visitor.

If the file hash authorization fails, the server will return an error: 403 {'error': 'access-denied'}

If the file was not found or the non-file method was used, the server will return an error: 404 {'error': 'file-not-found'}

Requests from Rox.Chat to the Bot Server

Rox.Chat requests to the bot URL, which is set in the Control Panel settings when creating a bot.

Authorization is not required for these requests.

To improve security, a secret key can be added to the bot URL. It is inserted into the URL in the following way: address/secret_key instead of address, where secret_key is a sequence of characters.

In case the request from Rox.Chat fails to pass to the bot, the Rox.Chat server will try to send it four more times after the failure: first after 2 seconds after the failed attempt, then after 4, 8, and 16 seconds (counting from the last failed attempt).

HTTP requests from the Rox.Chat service to the server contain the following parameters in the header:

X-Bot-API-Dialect - the "dialect" of the API (in this case Rox.Chat Standard);
X-Bot-API-Version - API version (in this case 2.0);
X-RoxChat-Version - the full version of Rox.Chat (for example: 3.0.5).

Error Handling

On success, the bot should provide the following response:

200 OK

The body of the bot server's response to a Rox.Chat request should contain:

{
   "result": "ok"
}

If a different response is received, the chat will be moved to the general queue.

Assigning Chat to a Bot

Request type: POST

Content-type: application/json

Query-string parameters: not needed

Called when creating a chat or when transferring a chat to a robot.

Example of request body when assigning a chat to a bot:

{
    "event": "new_chat",
    "chat": {
        "id": 452
    },
    "visitor": {
        "id": "03e1c040d8214bfa8ccfbb053186a24a",
        "fields": {
            "email": "support@rox.chat"
            "id": "asdf123",
            "icq": "123123123",
            "login": "someelogin",
            "name": "asdf123",
            "phone": "+7 (812) 385-53-37",
            "profile_url": "https://t.me/roxchat",
            "site": "https://rox.chat"
        }
    },
    "messages": [
        Message,
        Message,
        ...
    ]
}

Description of the object fields in the response to the query:

Field	Type	Example	Description	Mandatory
`event`	`String`	`new_chat`	Event type.	Yes
`chat.id`	`Integer`	`247`	Chat ID.	Yes
`visitor.id`	`String`	`03e1c040d8214bfa8ccfbb053186a24a`	The pseudo-unique identifier of the visitor that Rox.Chat always assigns to him/her.	Yes
`visitor.fields`	`JSON`	`{"name": "John", "phone": "+18433754873", ...}`	Known information about the visitor in the form of key-value pairs. The visitor identifier inside visitor.fields is passed to Rox.Chat by the frontend, it can be of any kind and not be unique. If there is no `visitor.fields`, there is no identifier. If `visitor.fields` is present, the identifier is a mandatory field, all other fields are not.	No
`messages`	`Array of Messages`	Listed below in the description of the `new_message` event.	Messages sent by the visitor that have accumulated by the time the chat was assigned to the bot (messages from channels, from the widget, if the request for contact details before starting the chat is enabled).	No

New Message

Request type: POST

Content-type: application/json

Query-string parameters: not needed

Example of request body when sending a message to a bot:

{
    "event": "new_message",
    "message": Message,
    "chat_id": 245
}

Description of the object fields in the query response:

Field	Type	Example	Description	Mandatory
`event`	`String`	`new_message`	Event type.	Yes
`message`	`Message`	Listed below	`Message` object.	Yes
`chat_id`	`Integer`	`247`	Chat ID.	Yes

The Message object can contain different types of data and fields.

Text Message

An example of Message object contents in a text message:

{
    "id": "feb8e0f7fe08486db2494c2d5058fd33",
    "kind": "visitor",
    "text": "Hello"
}

Message object field description:

Field	Type	Example	Description	Mandatory
`id`	`String`	`feb8e0f7fe08486db2494c2d5058fd3`	The ID of the message on the Rox.Chat side.	Yes
`kind`	`String`	`operator`	Message type. All message types you can find here	Yes
`text`	`String`	`Can I help you?`	Text.	Yes

File Message

The bot should return a response {"result": "ok"} for messages where media_type = json.

As the file is uploaded, not one but several requests will be sent, the number of which depends on the size of the file: the larger it is, the longer the upload takes. While the file is being uploaded (with upload value in the state field), each new request will contain an updated value of the file upload percentage (progress field). The last request when sending the file will have the value ready in the state field, which means that the file has been sent.

An examples of the contents of the Message object in requests with a file message:

{
    "id": "c3e19d57f64e43c3afabdef2ef4e4054",
    {
        "kind": "file_visitor",
        "data": {
            "id": "81f0488",
            "state": "upload",
            "progress": 50,
            "size": 560
            "url": "https://yoursite.com/content/file.txt"
        }
    }
}

{
    "id":"c3e19d57f64e43c3afabdef2ef4e4054",
    {
        "kind": "file_visitor",
        "data": {
            "id": "81f0488",
            "state": "upload",
            "progress": 89,
            "size":560
            "url": "https://yoursite.com/content/file.txt"
        }
    }
}

{
    "id":"c3e19d57f64e43c3afabdef2ef4e4054",
    {
        "kind": "file_visitor",
        "data": {
            "id": "81f0488",
            "state": "ready",
            "name": "file.txt",
            "content_type": "text",
            "size":560
            "url": "https://yoursite.com/content/file.txt"
        }
    }
}

Message object field description:

Field	Type	Example	Description	Mandatory
`id`	`String`	`feb8e0f7fe08486db2494c2d5058fd3`	The ID of the message on the Rox.Chat side.	Yes
`kind`	`String`	`file_visitor`	The type of message, in this case the file sent by the visitor (`file_visitor`). All message types you can find here	Yes
`data.id`	`String`	`81f0488`	The identifier of the file.	Yes
`data.state`	`String`	`upload`	The state in which the sent file is (`upload` - if it is in the process of uploading, `ready` - if uploading is complete).	Yes
`data.name`	`String`	`somefile.pdf`	The name of the file. If `data.state = upload`, it can be omitted.	No
`data.media_type`	`String`	`application/pdf`	Internet Media Type. May not be present when `data.state = upload`.	No
`data.size`	`Integer`	`12350`	File size in bytes.	No
`data.progress`	`Integer`	`95`	Degree of file upload when `data.state = upload`. Specified as a percentage.	No
`data.url`	`String`	`https://yoursite.com/content/document.pdf`	URL of the uploaded file (when `data.state = ready`).	Yes

Click on Button

The request contains the button selected by the visitor.

An example of the contents of a Message object in a button clicked message:

{
    "id": "ddaa8401e1ef4910abb3657f3ea09683",
    "kind": "keyboard_response",
    "data": {
        "button": {
            "id": "937bec4863154a2fb0889ff1320d1e2f",
            "text": "Ask a question to the agent"
        },
        "request": {
            "messageId": "fede9187f3da41c9849976a01a40d899"
        }
    }
}

Message object field description:

Field	Type	Example	Description	Mandatory
`id`	`String`	`feb8e0f7fe08486db2494c2d5058fd3`	The ID of the message on the Rox.Chat side.	Yes
`kind`	`String`	`keyboard_response`	The type of message. All message types you can find here	Yes
`data.button`	`Button`	`Button` object	The button pressed by the visitor. In some communication channels (e.g. WhatsApp, Viber) buttons are displayed as a numbered list (text). In this format, the visitor selects a button by sending a message with the button number. In other words, the button is considered selected only if the button is in the list and the visitor sends the button number (e.g. `"2"`). If the visitor sends a non-existent button number (e.g. if the list of buttons from `1` to `8` sends the number `9`) or sends the button in any other form (button text, number together with text, etc.), the button will not be selected and the request will not be sent.	Yes
`data.request.messageId`	`String`	`fede9187f3da41c9849976a01a40d899`	Identifier of the message whose button was pressed.	Yes

Update Message

Request type: POST

Content-type: application/json

Query-string parameters: not needed

Example of request body when updating a message:

{
    "event": "message_updated",
    "message": Message,
    "chat_id": 8754
}

Description of the object fields in the query response:

Field	Type	Example	Description	Mandatory
`event`	`String`	`message_updated`	Event Type.	Yes
`message`	`Message`	`Message` object	The content of the Message object after the update.	Yes
`chat_id`	`Integer`	`2547`	Chat ID.	Yes