Skip to content

Available API Methods

This article contains a description of all the methods used by the Rox.Chat Stored Data API.

Retrieving a List of Agents

Path: /operators

Request type: GET

Query-string parameters: not required.

This request returns an array of all agents associated with the given Rox.Chat account.

Fields description in the response:

Parameter name Type Example Description
status String invisible Agent's status.
roles Array of strings admin List of agent roles.
created_at String 2023-04-20T15:05:42Z Agent's registration date in ISO 8601 format.
email String agent@rox.chat Agent's email address.
full_name String Agent Agent's full name.
id Integer 196458 Unique identifier for the agent.

Sample response (the response body has a standard appearance regardless of the agent's status):

[
  {
    "status": "online",
    "roles": [
      "admin"
    ],
    "created_at": "2023-04-08T14:10:32Z",
    "email": "agent@rox.chat",
    "full_name": "Mary",
    "id": 192162
  },
  {
    "status": "offline",
    "roles": [
      "operator"
    ],
    "created_at": "2023-07-10T13:17:49Z",
    "email": "agent2@rox.chat",
    "full_name": "John Smith",
    "id": 193903
  },
  {
    "status": "invisible",
    "roles": [
      "operator"
    ],
    "created_at": "2023-06-16T18:56:32Z",
    "email": "agent3@rox.chat",
    "full_name": "John Doe",
    "id": 196158
  },
  {
    "status": "pre-dinner",
    "roles": [
      "admin"
    ],
    "created_at": "2023-02-28T12:25:45Z",
    "email": "agent4@rox.chat",
    "full_name": "Jane Doe",
    "id": 194435
  },
]

Retrieving a List of Departments

Path: /departments

Request type: GET

Query-string parameters: not required.

This request returns an array of departments associated with the given Rox.Chat account.

Fields description in the response:

Parameter name Type Example Description
id Integer 12 Unique identifier for the department.
name String Отдел продаж Department name.
order Integer 800 Department sorting order.

Пример ответа:

[
   {
      "id": 1,
      "name": "First department",
      "order": 100
   },
   {
      "id": 2,
      "name": "Second department",
      "order": 200
   }
]

Retrieving Chats for a Period

Path: /chats

Request type: GET

Query-string parameters: since — see below (after the example).

This request returns an array of chats for a specified time period.

Description of the object fields in the response:

Parameter name Type Example Description
id Integer or String 2036 Unique chat identifier. Assigned upon recording in the database. This is the number (or GUID) displayed in the Agent Workplace and in the chat history.
created_at String 2023-11-18T09:29:09Z Chat creation date in ISO 8601 format.
category_ids Array [1, 4, 23] List of identifiers of the categories assigned to the chat, see Chat Classification. May be empty.
operator_id Integer 181250 Unique agent identifier.
operator_comment String Agent Anna P. added a comment: {comment text} Message about the agent adding a comment to the chat. Can take the value NULL. (Present if the relevant feature is enabled).
rates Array "rate": 3,"operator_id": 209920,"created_at": "2023-05-13T23:57:01Z" Array of ratings given to the agent.
messages Array Description and value examples can be viewed below. Array of user messages sent to the chat before it appears in the Agent Workspace (e.g., from communication channels).
state_history Array Description and value examples can be viewed below. Array of data describing the chat's state history. Can take the value NULL.
visitor String id: "d6123d01de9d4e61b1a5a4a82e451839" Visitor data. Cannot be empty. The id field must be present. The fields object inside visitor may also be empty, but in this case the visitor will be unauthorized. If identifying data identifying the visitor is provided, it should be passed exactly as per article on identification. If the user is unauthorized, the visitor-fields-id is not needed.
visit_session String Description and value examples can be viewed below. Data about the visitor's session.
start_page.url String https://rox.chat URL of the page from which the visitor came.
more_chats_available Boolean true Indicates whether more unloaded chats remain, as the response to the request cannot return more than 100 dialogs.
last_ts String 1551278071115810 Parameter taken as since for further chat retrieval requests.

Description of the messages object fields in the response:

Parameter name Type Example Description
id String 0052a4489cc742c7b4b867a3ed87991e Unique message identifier.
created_at String 2023-11-18T09:29:09Z Message send date.
kind String visitor Kind messages. These can be different kinds of system messages, agent or visitor messages, sent files, etc. Full description of message kinds can be found in article.
message String Hello! I need help with your plans. Message text.
operator_id Integer 245875 Identifier of the agent who sent the message.

If the message type is keyboard or keyboard_response, the following field descriptions apply:

Parameter name Type Example Description
id String 0052a4489cc742c7b4b867a3ed87991e Unique message identifier.
created_at String 2023-11-18T09:29:09Z Message send date.
kind String keyboard Message kind.
data String id: "2"buttonId: "3"messageId: "ee310f4073834962867d77bc84bbe9e7" Fields for the keyboard message type::
  • buttons - buttons for visitor selection. It has fields id and text.
  • response - the button selected by the visitor. It has fields buttonId and messageId. It can be NULL..
  • state - can have values completed, cancelled, pending.
Fields for the keyboard_response message type:
  • request - contains the field messageId.
  • button - the button selected by the visitor. It has fields id and text.

Description of the state_history object fields in the response:

Parameter name Type Example Description
state String chatting Name of the chat state. All states are displayed on the Chat Lifecycle Diagram.
operator_id Integer 181509 Unique agent identifier. Can be NULL.
at String 2023-11-18T09:31:09Z Date of the chat state change.
department_id Integer 6 Unique department identifier. Can be NULL.

Description of the visit_session object fields in the response:

Parameter name Type Example Description
ip String 31.193.122.170 IP address of the visitor's device. Can be NULL.
landing_page.url String https://telegram.org/ Page from which the visitor started the chat. Can be NULL.

Description of the rates object fields in the response:

Parameter name Type Example Description
rate Integer 5 Rating given to the agent (from 1 to 5).
operator_id Integer 245896 Identifier of the agent who received the rating.
created_at String 2023-05-13T23:57:01Z Date of rating submission in ISO 8601 format.

Example of response:

{
   "chats": [
      {
         "id": 453,
         "created_at": "2023-04-04T09:14:57Z",
         "category_ids": [23, 48, 1],
         "operator_id": 123,
         "operator_comment": null,
         "rates": [
           {
             "rate": 3,
             "operator_id": 209920,
             "created_at": "2023-05-13T23:57:01Z"
           }
         ],
         "messages": [
            {
               "created_at": "2023-04-04T09:14:57Z",
               "kind": "info",
               "message": "Please wait a moment, an agent will join you shortly..."
               "id": "f5eee59b508e47f999d8a373d0362c95"
            },
            {
               "created_at": "2023-04-04T09:14:57Z",
               "kind": "events",
               "message": "Agent George B has joined the conversation"
               "id": "324090d75f904a3eb04e54b2fc44094b"
            },
            {
               "created_at": "2023-04-04T09:14:57Z",
               "kind": "operator_busy",
               "message": "We apologize, the agent was away"
               "id": "b1f9c575fc4d4b45b2480a490443a802"
            },
            {
               "created_at": "2023-04-04T09:14:57Z",
               "kind": "file_operator",
               "data": {
                  "guid": "8cdb288",
                  "content_type": "text",
                  "filename": "v.txt"
               },
               "operator_id": 123
            },
            {
               "created_at": "2023-04-04T09:14:57Z",
               "kind": "file_visitor",
               "data": {
                  "guid": "81f0488",
                  "content_type": "text",
                  "filename": "v.txt"
               },
               "operator_id": 123
            },
            {
               "created_at": "2023-04-04T09:14:57Z",
               "kind": "operator",
               "message": "Hello! How can I help you?",
               "operator_id": 123
            },
            {
               "created_at": "2023-04-04T09:14:57Z",
               "kind": "contacts_request",
               "message": "Please enter the information.",
               "operator_id": 123
            },
            {
               "created_at": "2023-04-04T09:14:57Z",
               "kind": "contacts",
               "message": {
                  "name": "John",
                  "phone": "1",
                  "email": "v@rox.chat"
               }
            },
            {
               "created_at": "2023-04-04T09:14:57Z",
               "kind": "visitor",
               "message": "Not yet, thank you."
            }
         ],
         "state_history": [
            {
               "state": "queue",
               "operator_id": null,
               "at": "2023-06-10T17:06:22Z",
               "department_id": null
            },
            {
               "state": "queue",
               "operator_id": 3,
               "at": "2023-06-10T17:06:22Z",
               "department_id": null
            },
            {
               "state": "chatting",
               "operator_id": 3,
               "at": "2023-06-10T17:06:28Z",
               "department_id": null
            },
            {
               "state": "queue",
               "operator_id": null,
               "at": "2023-06-10T20:07:04Z",
               "department_id": 2
            }
         ],
         "visitor": {
            "fields": {
               "email": "support@rox.chat",
               "id": "asdf123",
               "icq": "123123123",
               "login": "somelogin",
               "name": "asdf123",
               "phone": "+1 (23) 385-53-37",
               "site": "https://rox.chat"
            },
            "id": "4d123f6d7143490d966432ccb24403a4"
         },
         "visit_session": {
            "ip": "192.168.1.123",
            "landing_page": {
               "url": "https://rox.chat"
            }
         },
         "start_page": {
            "url": "https://rox.chat/help/api"
         }
      },
      {
         "id": 454,
         "created_at": "2023-04-04T09:15:57Z"
      },
      {
         "id": 455,
         "created_at": "2023-04-04T09:16:57Z"
      }
      ...
   ],
   "more_chats_available": false,
   "last_ts": 1429054006896762
}

The since parameter must be specified in the query. In the first request since=0 is passed, in the response to each request there is a field last_ts, and in each next request the value of last_ts from the previous one must be passed as since. In the parameters since and last_ts the value is specified in microseconds!

In this way, each subsequent request receives in response only updates with respect to what was received on all previous requests.

The same chat can be retrieved multiple times if there have been any changes to it since the first time it was retrieved.

A maximum of 100 dialogs are returned at a time in response to a history request. If the more_chats_available field in the response is set to true, it means that there are new or changed dialogs on the server that do not "fit" into this limit, and another request should be made with a new since value to retrieve them (and repeat this until more_chats_available is set to false).

Retrieving Chats by ID

Path: /chat

Request type: GET

Query-string parameters: id — chat ID.

This returns the chat object based on its unique identifier.

Example request:

https://company.rox.chat/api/v{{version}}/chat?id=1465

Where chat?id={chat_id} is the API command format, and {chat_id} (in the example 1465) is the unique identifier of the chat you want to retrieve.

Description of the fields in the response:

Parameter name Type Example Description
id Integer or String 2036 Unique chat identifier. Assigned upon recording in the database. This is the number (or GUID) displayed in the Agent Workplace and in the chat history.
created_at String 2023-11-18T09:29:09Z Chat creation date in ISO 8601 format.
category_ids Array [1, 4, 23] List of identifiers of the categories assigned to the chat, see Chat Classification. May be empty.
operator_id Integer 181250 Unique agent identifier.
operator_comment String Agent Anna P. added a comment: {comment text} Message about the agent adding a comment to the chat. Can take the value NULL. (Present if the relevant feature is enabled).
rates Array "rate": 3,"operator_id": 209920,"created_at": "2023-05-13T23:57:01Z" Array of ratings given to the agent.
messages Array Description and value examples can be viewed below. Array of user messages sent to the chat before it appears in the Agent Workspace (e.g., from communication channels).
state_history Array Description and value examples can be viewed below. Array of data describing the chat's state history. Can take the value NULL.
visitor String id: "d6123d01de9d4e61b1a5a4a82e451839" Visitor data. Cannot be empty. The id field must be present. The fields object inside visitor may also be empty, but in this case the visitor will be unauthorized. If identifying data identifying the visitor is provided, it should be passed exactly as per article on identification. If the user is unauthorized, the visitor-fields-id is not needed.
visit_session String Description and value examples can be viewed below. Data about the visitor's session.
start_page.url String https://rox.chat URL of the page from which the visitor came.

Description of the messages object fields in the response:

Parameter name Type Example Description
id String 0052a4489cc742c7b4b867a3ed87991e Unique message identifier.
created_at String 2023-11-18T09:29:09Z Message send date.
kind String visitor Kind messages. These can be different kinds of system messages, agent or visitor messages, sent files, etc. Full description of message kinds can be found in article.
message String Hello! I need help with your plans. Message text.
operator_id Integer 245875 Identifier of the agent who sent the message.

If the message type is keyboard or keyboard_response, the following field descriptions apply:

Parameter name Type Example Description
id String 0052a4489cc742c7b4b867a3ed87991e Unique message identifier.
created_at String 2023-11-18T09:29:09Z Message send date.
kind String keyboard Message kind.
data String id: "2"buttonId: "3"messageId: "ee310f4073834962867d77bc84bbe9e7" Fields for the keyboard message type::
  • buttons - buttons for visitor selection. It has fields id and text.
  • response - the button selected by the visitor. It has fields buttonId and messageId. It can be NULL..
  • state - can have values completed, cancelled, pending.
Fields for the keyboard_response message type:
  • request - contains the field messageId.
  • button - the button selected by the visitor. It has fields id and text.

Description of the state_history object fields in the response:

Parameter name Type Example Description
state String chatting Name of the chat state. All states are displayed on the Chat Lifecycle Diagram.
operator_id Integer 181509 Unique agent identifier. Can be NULL.
at String 2023-11-18T09:31:09Z Date of the chat state change.
department_id Integer 6 Unique department identifier. Can be NULL.

Description of the visit_session object fields in the response:

Parameter name Type Example Description
ip String 31.193.122.170 IP address of the visitor's device. Can be NULL.
landing_page.url String https://telegram.org/ Page from which the visitor started the chat. Can be NULL.

Description of the rates object fields in the response:

Parameter name Type Example Description
rate Integer 5 Rating given to the agent (from 1 to 5).
operator_id Integer 245896 Identifier of the agent who received the rating.
created_at String 2023-05-13T23:57:01Z Date of rating submission in ISO 8601 format.

Example of response:

{
   "chat": {
      "operator_id": 181502,
      "start_page": {
         "url": "https://rox.chat"
      },
      "category_ids": [23, 48, 1],
      "visitor": {
         "fields": {
         },
         "id": "2c4a44b8948e4985951cb6df99279cdc"
      },
      "id": 1465,
      "operator_comment": null,
      "rates": [
        {
          "rate": 3,
          "operator_id": 209920,
          "created_at": "2020-05-13T23:57:01Z"
        }
      ],
      "visit_session": {
         "ip": "31.193.122.170",
         "landing_page": {
            "url": "https://company.rox.chat/sample-page.php?redirected=1"
         }
      },
      "created_at": "2023-07-19T14:39:08Z",
      "messages": [
         {
            "created_at": "2023-07-19T14:39:08Z",
            "message": "Please wait a moment, an agent will join you....",
            "kind": "info",
            "id": "24113c657f254698a3e660c64c4ed6b5"
         },
         {
            "created_at": "2023-07-19T14:39:11Z",
            "message": "Hi!",
            "kind": "visitor",
            "id": "f5eee59b508e47f999d8a373d0362c95"
         },
         {
            "created_at": "2023-07-19T14:39:13Z",
            "message": "Operator George B joined the chat",
            "kind": "info",
            "id": "324090d75f904a3eb04e54b2fc44094b"
         },
         {
            "created_at": "2023-07-19T14:39:15Z",
            "operator_id": 181502,
            "message": "Hello and goodbye!",
            "kind": "operator",
            "id": "b1f9c575fc4d4b45b2480a490443a802"
         },
         {
            "created_at": "2023-07-19T14:39:20Z",
            "message": "The agent closed the chat",
            "kind": "info",
            "id": "2970ed561d6a40c1b788001289096acb"
         }
      ],
      "state_history": [
         {
            "state": "queue",
            "operator_id": null,
            "at": "2023-07-19T14:39:08Z",
            "department_id": 5
         },
         {
            "state": "queue",
            "operator_id": 181502,
            "at": "2023-07-19T14:39:08Z",
            "department_id": 5
         },
         {
            "state": "chatting",
            "operator_id": 181502,
            "at": "2023-07-19T14:39:13Z",
            "department_id": 5
         },
         {
            "state": "closed",
            "operator_id": 181502,
            "at": "2023-07-19T14:39:20Z",
            "department_id": 5
         }
      ]
   }
}

Retrieving Tariffs

Path: /partner/tariffs

Request type: GET

Query-string parameters: not required.

The query returns an array of tariffs of the Rox.Chat service.

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

Parameter name Type Example Description
partner_prices.per_operator_price Float 232.0 Price per agent for partners.
partner_prices.base_price Float 365.0 Basic tariff price for partners.
name String Corporate Tariff Name.
discounts Object {"1": 0,"2": 0,"3": 10,} Discount amount in percent for the ordered period in months. Can be NULL.
public_prices.per_operator_price Float 290 Price per agent for regular users.
public_prices.base_price Float 360 The base price of the tariff for regular users.
key String corp Unique Tariff Key.
description String What you get: basic visitor service functionality +... Tariff description.

Example response:

{
  "tariffs": [
    {
      "partner_prices": {
        "per_operator_price": 232.0,
        "base_price": 392.0
      },
      "name": "Starter",
      "discounts": {},
      "public_prices": {
        "per_operator_price": 290,
        "base_price": 490
      },
      "key": "start",
      "description": "What you get:n+ basic functionality of visitor service;n+ storing history for one month;n+ showing up to 20 site visitors.nnWhat you don't get:n- working with departments;n- showing up to 50 site visitors;n- customizing dialog colors;n- agent work statistics;n- storing message history without time limits."
    },
    {
      "partner_prices": {
        "per_operator_price": 632.0,
        "base_price": 1112.0
      },
      "name": "Business",
      "discounts": {},
      "public_prices": {
        "per_operator_price": 790,
        "base_price": 1390
      },
      "key": "bus",
      "description": "What you get:n+ basic functionality of visitor service;n+ showing up to 50 visitors to the site;n+ working with departments;n+ customizing dialog colors;n+ statistics of agents' work;n+ storing the history of messages without time limits."
    },
    {
      "partner_prices": {
        "per_operator_price": 1992.0,
        "base_price": 1992.0
      },
      "name": "Corporate",
      "discounts": {},
      "public_prices": {
        "per_operator_price": 2490,
        "base_price": 2490
      },
      "key": "corp",
      "description": "What you get:n+ basic visitor service functionality;n+ showing up to 50 visitors to the site;n+ working with departments;n+ customizing dialog colors;n+ extended agent work statistics;n+ storing message history without time limits.n+ extended visitor information."
    }
  ]
}

Retrieving Statistics

Path: /stats

Request type: GET

Query-string parameters: date — the date for which statistics are requested; mode — usage (different types of inquiries) or operators (report by agents).

Example request:

https://company.rox.chat/api/v4/stats?date=2023-04-20&mode=usage

Where stats?date={date}&mode={mode} is the API command format, in which {date} is the date for which you want to display statistics, specified in the format yyyy-mm-dd, and {mode} is the request mode (usage or operators).

Statistics on System Usage

Example request:

{base_url}/api/v4/stats?date=2023-04-20&mode=usage

The request returns statistics of accesses of different types.

Description of object fields in the query response:

Parameter name Type Example Description
contacts Integer 6 Total number of requests for a specific date.
missed Integer 2 Number of requests awaiting a response.
chats Integer 2 Number of chats in the In dialog status.
offlines Integer 0 Number of offline requests.
avg_waiting_time Float 245.0 Average wait time.

Example response:

{
    "contacts": 10,
    "missed": 1,
    "chats": 7,
    "offlines": 2,
    "avg_waiting_time": 100.0
}

Statistics by Agents

Example request:

https://company.rox.chat/api/v4/stats?date=2023-04-20&mode=operators

The request returns a report for all agents for a specific date.

Description of object fields in the query response:

Parameter name Type Example Description
operator_id Integer 189650 The unique identifier of the agent.
online_time Integer 961 Agent time in Online status.
chatting_time Integer 562 Agent time in the In dialog status.
avg_chatting_time Float 236.0 Average agent time in a dialog.
busy_messages Integer 0 The number of agent busy messages that were displayed to visitors when they contacted this agent.
chats Integer 5 Number of requests processed.

Пример ответа:

[
    {
        "operator_id": 123,
        "online_time": 28800,
        "chatting_time": 18000,
        "avg_chatting_time": 150.0,
        "busy_messages": 5,
        "chats": 3
    },
    {
        "operator_id": 124,
        "online_time": 23800,
        "chatting_time": 1000,
        "avg_chatting_time": 150.0,
        "busy_messages": 1,
        "chats": 2
    }
]

Retrieving Categories

Path: /categories

Request type: GET

Query-string parameters: not required.

Request example:

https://company.rox.chat/api/v4/categories

The method returns the list of categories used in the system.

Description of object fields in the response to the request:

Parameter name Type Example Description
id Integer 1 Numeric category identifier.
title String New category Category Name.
children Array [{"id": 13,"title": "New subcategory"}] List of subcategories. Each array object contains id - subcategory identifier and title - subcategory name.

Пример ответа:

[
   {
      "id": 1,
      "title": "New category",
      "children": []
   },
   {
      "id": 2,
      "title": "Another new category",
      "children": [
         {
            "id": 13,
            "title": "New subcategory"
         }
      ]
   },
   {
      "id": 3,
      "title": "Chats",
      "children": [
         {
            "id": 11,
            "title": "Subcategory for chats"
         }
      ]
   },
   {
      "id": 5,
      "title": "Category",
      "children": [
         {
            "id": 8,
            "title": "Subcategory"
         }
      ]
   }
]