Test Environment. You are currently using the Webex for Developers test environment. Apps created here will not be available for use with Webex Teams. Please visit Webex for Developers to manage your apps.

The xAPI for devices running RoomOS

The xAPI allows an integrator to programmatically invoke commands and query the status of devices that run RoomOS software. These are devices in the SX Series, MX Series, DX Series, Room Series, and Boards.

anchorWhat is possible with the xAPI
anchor

The xAPI is a defined set of commands that allows you to interact with and extract information from devices that run RoomOS software. There are hundreds of possible commands or statuses which can be issued to devices via a REST interface. Developers can extract information about the active call, check if the device detects any physical presence in the room, and much more. Also, the interface allows for the ability to perform actions such as changing the audio volume or creating a notification that appears on the user interface.

The powerful part of this REST interface is the ability to perform these actions without having direct network access to the device. The communication channel between the REST interface and the RoomOS device is encrypted. Developers and administrators can perform actions on all the devices connected to their infrastructure regardless of the device location. As an example, this allows them to perform actions and resolve issues on devices in home offices without physically having to go there.

anchorCreating an application that can access the Webex REST API
anchor

In general, you can create either a Bot or an Integration. A bot cannot work across many different organizations, it only works on devices that belong to the same organization as the creator of the bot. In addition, a bot can only access devices that it has been specifically granted access to. Bots are useful for applications that will work only in one organization and possibly need to be restricted to only a subset of devices. An integration on the other hand can perform actions on behalf of a user. Developers who wish to build applications that will work for multiple organizations, should create an integration. Administrators from multiple organizations can authorize an integration to perform xAPI commands on their behalf, and the integration will be able to access all devices in the organization(s) that the administrator(s) belong to.

If you are new to creating Webex applications, check out this blog post to get started with REST API calls to the Webex platform.

Create an integration

Please see the integration documentation to learn how to make integrations.

In order to create an integration that can make xAPI calls, your integration needs to request one or more of the following scopes:

spark:xapi_commands

  • execute commands towards the devices

spark:xapi_statuses

  • query status on the devices

spark:devices_read

  • list devices that you have been granted access to

spark-admin:devices_read

  • as an admin, list out all the available devices in your organization
Create a bot
  1. Log in to https://developer.webex.com, select My Webex Teams Apps from the menu under your avatar at the top of this page.
  2. Click Create a New App, followed by Create a Bot to start the wizard. Fill in the registration form (Bot name, Bot Username, Icon, Description), and click Add Bot. You, as the logged in user, are the owner of the bot account, and the bot belongs to the same organization as you.
  3. Copy the Access Token that you receive for the new bot and keep it somewhere safe. You must always use this token to authenticate your bot with the Webex REST API. If you misplace it, you have to generate a new one: Select My Webex Teams Apps from the menu, select your bot, and click Regenerate Access Token.
anchorGiving a bot or user access to the xAPI of a RoomOS device
anchor

An integration operates on behalf of a user. If this user is not an administrator of the devices in the organization, they must be explicitly granted device authorizations to the xAPI just as with bots. Bots are only able to make xAPI calls to devices which are registered in the same organization as the user who created a bot.

Your system administrator sets up device authorizations through the Cisco Webex Control Hub (https://admin.webex.com). Authorization is given for a Place, not a Device. If there are multiple devices associated with a place, all these devices get the same authorization.

Inform your system administrator about the email address of your bot, so that they can set the authorizations right. They must repeat the following process for each place that has devices that your application is going to interact with.

  1. From the customer view in https://admin.webex.com, go to the Places page. Search for the place that contains the devices that you want to give the bot xAPI access to. Select this place.
  2. Click View/Edit Access to add or delete the xAPI access (Device APIs access) for devices in this place. As a result, a list of all bots and users with authorization to access the xAPI of the devices opens..
  3. Click the plus sign (+) to add a new authorization. Choose the user or bot account that you want to authorize for the Place and select the appropriate access level. Full Access means that you can invoke commands and query status. Read Only means that you can only query status.
anchorFinding the deviceID for a specific device
anchor

When you send a request to a device, you must always include the deviceId. The deviceId is generated when it is enrolled to the Cisco Webex cloud. It is a good practice to avoid hardcoding the identifier.

Use the GET List Devices method in the Devices API to list devices: GET https://api.ciscospark.com/v1/devices/

The command returns a list of devices that the authorized bot or user has entitlements to see. There is one object for each device.

{
    "items": [
        {
            "id": "...",
            ...
            "permissions": [
                "xapi"
            ],
            ...
        },
        ...
    ]
}

Pay special attention to the following object fields:

  • id: This is the deviceId that the bot or user must pass to any API call.
  • permissions: The value of this field is an array. The bot or user can make xAPI calls only to the devices where "xapi" is part of this array. Always check the value of this field, because the list of devices may also include devices that you are not permitted to make xAPI calls to.
anchorUsing the xAPI
anchor

Once you know the deviceId, your application can perform a GET /xapi/status to query the status, or POST /xapi/command to invoke a command on that RoomOS device.

For integrations that were authorized by an organization Administrator, the scopes that they authorized determine which types of commands the application may call. For bots, or integrations authorized by non administrators, the access level of the bot or user determines if you have access to both commands and status, or only to status.

Read Only:

Full Access:

The following sections explain the syntax to use when invoking a command or querying a status and how to translate from terminal mode to Webex REST API calls. You can find examples and try out the commands yourself in the xAPI Reference page.

General recipe to invoke a command

The xAPI commands and statuses are described in the Cisco Collaboration Endpoint Software API Reference Guide. The guide uses terminal mode notation. All commands and statuses are not available for all types of devices. The guide states clearly which devices a command or status applies to.

To invoke a command on a device, use the following endpoint: POST https://api.ciscospark.com/v1/xapi/command/{commandKey}

Command key

commandKey is the xCommand path.

  • The command key is not case sensitive.
  • The path segments are separated by dots (".").
Header

Include the following header fields:

Authorization: Bearer <access token for the bot or user>
Content-Type: application/json
Accept: application/json
Command body

The command body is a JSON object. The object contains both the deviceId and an object with the arguments of the command. A command takes zero, one or more arguments.

{
    "deviceId": "...",
    "arguments": {
        "argOne": "string",
        "argTwo": "literal",
        "argThree": integer value,
        "argFour": true or false,
        "argFive": [1, 2, 3]
    }
}
  • Add all the command arguments in the arguments object in the body of the HTTP request.
  • If the command doesn't have arguments, you can either omit the arguments object or insert an empty object.
  • If the command has more than one argument, separate they by comma (",")
  • If the command has multiple instances of the same argument, add the argument's value is an array (one array element for each instance).
  • If the value is a string or a literal, put the value in quotes ("value"). Don’t use quotes for integer and boolean values.
Command response

A command response is a complex JSON object. This object contains the deviceId, an object with the arguments of the command (as explained in the previous section), and an object with the results of the command.

{
    "deviceId": "...",
    "arguments": {
        ...
    }
    "result": {
        ...
    }
}
  • The result object may contain arrays
  • An array always consists of complex objects with a key named id. This key is used to detect gaps in sparse arrays
  • If the command doesn't return any value, an empty result object is returned
Example 1

This example shows how to translate a command from terminal mode notation to the format you use for the Webex API.

Command in terminal mode: xCommand Presentation Start Layout: Equal ConnectorId: 2 ConnectorId: 3 SendingMode: LocalRemote (For testing, use ConnectorId: 1 ConnectorId: 2 instead if you have a DX70, DX80, SX20, Room Kit, or Room Kit Mini. These products don’t have a connector number 3.)

Since this is a command the REST API action is a POST: https://api.ciscospark.com/v1/xapi/command/Presentation.Start

Header fields:

Authorization: Bearer <access token for the bot or user>
Content-Type: application/json
Accept: application/json

Request body:

{
    "deviceId": "...",
    "arguments": {
        "Layout": "Equal",
        "ConnectorId": [2, 3],
        "SendingMode": "LocalRemote"
    }
}

The expected return for this request is the HTTP response code 200, and the following response body:

{
    "deviceId": "...",
    "arguments": {
        "Layout": "Equal",
        "ConnectorId": [
            2,
            3
        ],
        "SendingMode": "LocalRemote"
    },
    "result": {
        "Instance": 1
    }
}
Example 2

In this example we convert xCommand Time DateTime Get to the Webex API format. This command takes no arguments.

Since this is a command the REST API action is a POST: https://api.ciscospark.com/v1/xapi/command/Time.DateTime.Get

Header fields:

Authorization: Bearer <access token for the bot or user>
Content-Type: application/json
Accept: application/json

Request body:

{
   "deviceId": "..."
}

The expected return for this request is the HTTP response code 200, and the following response body:

{
    "deviceId": "...",
    "arguments": {},
    "result": {
        "Year": 2019,
        "Month": 5,
        "Day": 4,
        "Hour": 13,
        "Minute": 37,
        "Second": 0
    }
}

We recommend you to use the xAPI Reference page to try more commands and see the response you receive.

General recipe to query a status

To query a status on a device, send an HTTP GET request to the following endpoint: https://api.ciscospark.com/v1/xapi/status/?name={statusKey}&deviceId={deviceId}

In contrast to commands, the deviceId is part of the URI of a status request, and a status request doesn't have a body.

Status key

statusKey is the xStatus path.

  • The status key is not case sensitive.
  • The path segments are separated by dots (".").
  • The status key may contain one or more wildcards. The wildcard will match all nodes that are deeper in the path hierarchy. The wildcard can represent any node, not only leaf nodes.
  • When referring to elements in an array, you can choose to use one specific index, a specified range of indexes, or a wildcard (all indexes).

Here are some more status key examples with wildcards and arrays:

statusKey = Audio.* - returns all the Audio status.

statusKey = *.Volume - returns all Volume status nodes, irrespective of parent node.

statusKey = Audio.Input.Connectors.HDMI[1].Mute - returns the mute status for one specific HDMI input connector.

statusKey = Audio.Input.Connectors.HDMI[2..3].Mute - returns the mute status for a range of HDMI input connectors.

statusKey = Audio.Input.Connectors.HDMI[*].Mute - returns the mute status for all HDMI input connectors.

statusKey = Audio.Input.Connectors.HDMI[*].* - returns all the mute for all HDMI input connectors.

Header

Include the following header fields:

Authorization: Bearer <access token for the bot or user>
Accept: application/json
Status response

A status response is a complex JSON object. The object contains the deviceId and an object with the results of the status query.

{
    "deviceId": "...",
    "result": {
        ...
    }
}
  • The result object may contain arrays.
  • An array always consists of complex objects with a key named id. This key is used to detect gaps in sparse arrays.
Example 1

This example shows how to translate a status from terminal mode notation to the format you use for the Webex API.

Status in terminal mode: xStatus Audio Microphones Mute

Since this is a status request the REST API action is a GET: https://api.ciscospark.com/v1/xapi/status/?name=Audio.Microphones.Mute&deviceId={deviceId}

You must replace {deviceId} with the real deviceId.

Header fields:

Authorization: Bearer <access token for the bot or user>
Accept: application/json

The expected return for this request is the HTTP response code 200, and the following response body:

{
    "deviceId": "..."
    "result": {
        "Audio": {
            "Microphone": {
            "Mute": Off
            }
        }
    }
}
Example 2

In this example we convert xStatus Audio Volume to the Webex API format.

Since this is a status request the REST API action is a GET: https://api.ciscospark.com/v1/xapi/status/?name=Audio.Volume&deviceId={deviceId}

You must replace {deviceId} with the real deviceId.

Header fields:

Authorization: Bearer <access token for the bot or user>
Accept: application/json

The expected return for this request is the HTTP response code 200, and the following response body:

{
    "deviceId": "..."
    "result": {
        "Audio": {
            "Volume": 90
        }
    }
}

We recommend you to use the xAPI Reference page to try more status queries and see the response you receive.

anchorxAPI Reference Guide
anchor

Descriptions of the xAPI commands and statuses are in the Cisco Collaboration Endpoint Software API Reference Guide – look for the newest version. The API Reference Guide uses the terminal mode notation for commands and statuses. As explained in the previous sections, its easy to translate from terminal mode to the JSON based Webex API format.

Terminal mode notation
xStatus <path>
xCommand <path> <key>: <value> <key>: <value>
  • Prefix: xStatus for statuses; xCommand for commands.
  • Path: Space-separated segments that form the full path of the status or command.
  • Arguments: Zero or more key-value pairs. The key and value are separated by colon (": "). Applies only to commands; statuses don't have arguments.

Examples:

xStatus Audio Volume
xCommand Audio Volume Increase Steps: 5