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 |