Source: https://rox.chat/kb/dev/api/realtime-2.0.html > The Rox.Chat Realtime API allows for real-time interaction with the chat server from external systems. # 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}.rox.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](https://rox.chat/kb/dev/api/stored-data/overview.html). ## 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. !!! Note "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 = ; ``` 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](https://rox.chat/kb/dev/iframe.html). * 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](https://rox.chat/kb/dev/iframe.html)! 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.
| | `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": "" } ``` 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:
```{
"error": "mandatory-field-not-found",
"field": "auth_token"
}``` | | `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:
```{
"error": "field-name-is-not-string",
"field_name": "name of the first key (or value) specified not by a string"
}``` | * `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**). !!! Note "N.B." At the moment, due to technical peculiarities it is not possible to cahnge the agent status from the `offline`. ### Request Examples Request body example: ``` { "email": "test@test.com", "status": "online", "condition": { "initial_statuses": ["dinner", "invisible"] } } ``` Request example: ``` curl --request POST \ --url https://company.rox.chat/api/v2/rt/agent_status \ --header 'authorization: Basic dGVzdEB0ZXN0LnXXXXXXXXXXXXXX' \ --header 'content-type: application/json' \ --data '{ "email": "test@test.com", "status": "online", "condition": { "initial_statuses": ["dinner", "invisible"] } }' ``` Fields and request parameter formats: | Name | Type | Example | Description | | ----------- | ------ | --------------------------------------------- | ---------------------------------------------------------------------------------- | | `email` | `str` | `some@bo.dy` | Agent's email | | `status` | `str` | `online` | The status you want to set for the agent | | `force` | `bool` | `true` | Optional. Whether to forcibly set the agent's status, ignoring system restrictions | | `condition` | `dict` | `"initial_statuses": ["dinner", "invisible"]` | Optional. The statuses in which the agent should currently be | ### Return Values * `200` – the request was successful: ``` { "result": "ok" } ``` The `200` code can also indicate errors in processing the provided data: ``` { "error": "" } ``` The following errors are possible: | Error Name | Error Description | | -------------------------------- | --------------------------------------------------------------------------------------------------------------- | | `request-body-is-not-valid-json` | An invalid JSON object was provided | | `request-body-is-not-object` | Incorrect source data format - for example, if a number is provided instead of a JSON object | | `missing-argument` | A mandatory argument is missing:
```{
"error": "missing-argument",
"argument": "email"
}``` | | `unknown` | An unknown error. Currently, due to system peculiarities, this error is returned if the request type isn't POST | | `condition-not-satisfied` | The provided conditions for transitioning the agent to a new status weren't met | | `agent-status-not-allowed` | The specified status is not available on this tariff | | `invalid-agent-email` | The provided agent email isn't correct, and no agent with that email exists in the system | | `not-in-allowed-online-time` | The online time for agents is restricted (based on the `allowed_online_time` setting) | * `401` - authorization data is missing or failed verification (unauthorized): ``` { "error": "unauthorized" } ``` * `502` – the server isn't ready to process the request (Bad Gateway)