Rox.Chat Realtime API

The Rox.Chat Realtime API allows for real-time interaction with the chat server from external systems.

Below is all the information you need to work with the API.

Base URL

The base URL includes the domain of your account (depending on your network configuration) and appears as follows:

https://{hostname}/api/v2/rt/{path}

{hostname} – the network node (host) name where the Rox.Chat Server is located (like {account}.spitch.chat for cloud clients and chat.mycompany.com for hosted clients)
{path} – the API command

Example of a ready request to the Rox.Chat Realtime API:

https://company.rox.chat/api/v2/rt/provide_visitor_fields

Authorization & API Access

The authorization process is the same as the one used in the Stored Data API.

Method provide_visitor_fields

API method: provide_visitor_fields
Final URL: https://{hostname}/api/v2/rt/provide_visitor_fields
Request type: POST
Query-string parameters: not required
Content-Type: application/json
Request body format: JSON

This request allows for full-fledged visitor authentication (registered login and logout in Rox.Chat) from an external system (relative to the Rox.Chat Server) using a tokenizer.

N.B.

The software and hardware part (backend) of the external system should be capable of generating combinations of tokens and provided visitor fields (provided visitor fields).
The user interface (frontend) of the external system should have (on its website pages or in its mobile app) the following JavaScript code:
```
window.roxchat_auth_token = <auth_token>;
```
The pages should not contain the roxchat_visitor object, which holds identifying data.

It's also worth mentioning that if the method is successful, the visitor will not have the option to enter contact information in the chat widget.
The frontend of the external system should also implement the following handler that processes the error event from the Rox.Chat Server named provided_auth_token_not_found:
```
window.roxchatHandlers.onProvidedTokenNotFoundError
```
For other Rox.Chat handlers, see here.
At the moment when a user logs out (ceases to be authorized in the customer's system), the organization's backend should send a POST request to the Rox.Chat server to the provide_visitor_fields method with and without visitor_fields token, and the token-field combination in the server's memory will be deleted and cannot be used after the logout. The frontend should stop exposing rochat_auth_token on pages.
Note: the functionality provided by this method is not available in user interfaces where the chat widget for visitors is located inside iframe! The functionality is available for mobile applications written with Rox.Chat Mobile SDK.

Request Examples

Request body example:

{
    "auth_token": "40bbba7cd1fec39dd1aXXXXXXXXXXX",
    "visitor_fields": {
        "id": "a1e29384df",
        "display_name": "John Bull",
        "email": "john@rox.chat",
        "phone": "+1 123 123 123"
    }
}

Request example:

curl --request POST \
 --url https://company.rox.chat/api/v2/rt/provide_visitor_fields \
 --header 'authorization: Basic dGVzdEB0ZXN0LnXXXXXXXXXXXXXX' \
 --header 'content-type: application/json' \
 --data '{
    "auth_token": "40bbba7cd1fec39dd1aXXXXXXXXXXX",
    "visitor_fields": {
      "id": "a1e29384df",
      "display_name": "John Bull",
      "email": "john@rox.chat",
      "phone": "+1 123 123 123"
      }
  }'

Fields and formats for query parameters:

Name	Type	Example	Description
`auth_token`	`str`	`40bbba7cd1fec39dd1aXXXXXXXXXXX`	A unique, pseudorandom identifier (token). It's a required field. The `auth_token` can be any string, for example, a `UUID`, but not limited to it.
`visitor_fields`	`Object`	{ "id": "a1e29384df", "display_name": "John Bull", "email": "john@rox.chat", "phone": "+1 123 123 123" }	A structure consisting of provided visitor fields. The names and values of all `visitor_fields` should be strings. It's an optional field. If present, it adds or replaces the "token-fields" combination in server memory. If absent, the combination of the specified token gets removed from memory.
`id`	`str`	`a1e29384df`	The identifier (`provided visitor id`) of the visitor in the organization's system (note: different from the user's visitor id in the Rox.Chat service). It's a required field if the `visitor_fields` object is present. It should be unique and not empty.
Others	`str`		Any personal visitor data that you need to send to the server. They will always be transmitted and stored in the Rox.Chat database for that visitor.

Return Values

Below are the potential return codes and their descriptions.

200 – the request was successful:

{
"result": "ok"
}

The 200 code can also indicate errors in processing the provided data:

{
"error": "<error-name>"
}

The following errors are possible:

Error Name	Error Description
`auth-token-is-not-string`	Incorrect data type in the token field – for instance, if it's provided as a number instead of a string
`request-body-is-not-object`	Incorrect source data format – for example, if a number is provided instead of a JSON object
`request-body-is-not-valid-json`	An invalid JSON object was provided
`mandatory-field-not-found`	Token is missing. The full return object format is: `{<br> "error": "mandatory-field-not-found",<br> "field": "auth_token"<br>}`
`id-field-required`	The mandatory `id` parameter is missing in the provided `visitor_fields`
`field-name-is-not-string`	In the provided `visitor_fields`, there's a key (or value) that isn't a string. The full return object format is: `{<br> "error": "field-name-is-not-string",<br> "field_name": "name of the first key (or value) specified not by a string"<br>}`

401 – authorization data is missing or failed verification (unauthorized):
```
{
"error": "unauthorized"
}
```
502 – the server isn't ready to process the request (Bad Gateway)

Method agent_status

API method: agent_status
Final URL: https://{hostname}/api/v2/rt/agent_status
Request type: POST
Query-string parameters: not required
Content-Type: application/json
Request body type: JSON

This method allows you to manage an agent's status from an external system (relative to the Rox.Chat Server).

N.B.

At the moment, due to technical peculiarities it is not possible to cahnge the agent status from the offline.