Skip to content

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:

  1. Create a new agent account using the Control Panel.

  2. Go to the settings of your account and select the Bots section.

  3. In the opened window, click the Create a New Bot button.

  4. Fill in the information about your bot: assign it to a new agent, select Smart bot as the bot type, and choose version 2.

  5. In the External API Link field, enter the URL address of the external server for the bot.

  6. Save the changes.

  7. 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