Commands V2

Commands V2.0 provides advanced device commands capabilities like queuing, support for offline devices, dynamic device set for commands and command history. Commands 2.0 is in active development and we will add support for all the commands soon

List command requests

API to get and filter command requests

Request
Security:
path Parameters
enterprise_id
required
string <uuid>

ID of the enterprise

query Parameters
command_type
string

Filter by type of command request i.e device, group etc

devices
string

Filter by device IDs. Accepts comma separated values.

device_type
string

Filter by device type i.e active, inactive etc

command
string

Filter by command name

issued_by
string

Filter by user. Accepts user id.

Responses
200

on successful request

get/v0/enterprise/{enterprise_id}/command/
Response samples
application/json
{
  • "count": 0,
  • "next": "string",
  • "previous": "string",
  • "results": [
    ]
}

Create a command request

API to create a command request for the device.

Request
Security:
path Parameters
enterprise_id
required
string <uuid>

ID of the enterprise

Request Body schema: */*

The request body to create a command for set of devices or groups

command_type
string

Identifies the type of command

* DEVICE: command request is meant for devices
* GROUP: command request is meant for groups
* DYNAMIC: command request is meant for dynamic set of devices
  i.e subset of devices from different groups or otherwise.
Enum: "DEVICE" "GROUP" "DYNAMIC"
devices
Array of strings <uuid> [ 0 .. 500 ] items

list of devices to run commands

groups
Array of strings <uuid> [ 0 .. 500 ] items

list of groups to run commands

device_type
string
Default: "active"

Type of devices to run commands on

* active: Run commands on currently online devices
* inactive: Run commands on currently offline devices
* all: Run commands on all the devices.
  Commands will be queued for offline devices until they come back online.
Enum: "active" "inactive" "all"
command
string (V0DeviceCommandEnum)

Following commands are supported

* ADD_TO_WHITELIST: Whitelist an installed sytem app. Requires `package_name` in command arguments where `package_name` is the app package uploaded on Esper 
* ADD_WIFI_AP : Add wifi access points for device. Requires `wifi_access_points` in command arguments where `wifi_access_points` is the data with access points
* CLEAR_APP_DATA : Clear data for an installed app. Requires `package_name` in command arguments where `package_name` is the app package uploaded on Esper 
* INSTALL: Install an app on a device. Requires `app_version` in command arguments where `app_version` is the version id of app uploaded on Esper
* LOCK: Lock device screen
* REBOOT: Reboot a device
* REMOVE_FROM_WHITELIST : Remove an installed system app from whitelist. Requires `package_name` in command arguments where `package_name` is the app package uploaded on Esper 
* REMOVE_WIFI_AP : Remove Wifi access points for device. Requires `wifi_access_points` in command arguments where `wifi_access_points` is the data with access points
* SET_APP_PERMISSION : Set permission for an installed app. Requires `package_name`, `grant_state`, `permission` in command arguments where `package_name` is the app package uploaded on Esper, `grant_state` should be "PERMISSION_GRANT_STATE_DEFAULT", "PERMISSION_GRANT_STATE_DENIED", "PERMISSION_GRANT_STATE_GRANTED" and `permission` is a valid permission
* SET_APP_STATE : Set the state of an app - SHOW/HIDE/DISABLE. Requries `app_state` and `package_name` in command arguments where `app_state` is the state of app and `package_name` is the app package uploaded on Esper
* SET_BLUETOOTH_STATE : Set bluetooth state (ON/OFF) for device. Requires `bluetooth_state` in command arguments where `bluetooth_state` is a boolean.
* SET_BRIGHTNESS_SCALE : Set brightness for device. Requires `brightness_value` in command arguments where `brightness_value` is an integer (1-100).
* SET_DEVICE_LOCKDOWN_STATE : Set lockdown state for a device. Requires `state` and `message` in command arguments where `state` is LOCKED/UNLOCKED and `message` is the message to be added with command
* SET_GPS_STATE :Set the GPS state for a device. Requires `gps_state` in command arguments where `gps_state` should be either 0, 1, 2, 3 or 4 (LOCATION_MODE_HIGH_ACCURACY = 0, LOCATION_MODE_SENSORS_ONLY = 1, LOCATION_MODE_BATTERY_SAVING = 2, LOCATION_MODE_OFF = 3, LOCATION_MODE_ON = 4)
* SET_KIOSK_APP : Command to set the Kiosk app for a device. Requires `package_name` in command arguments where `package_name` is the app package uploaded on Esper  
* SET_NEW_POLICY : Apply policy on device. Requires `policy_url` in command arguments where `policy_url` is the URL to the policy 
* SET_ROTATION_STATE : Set screen orientation. Requires `rotate_state` in command arguments where `rotate_state` should be either 0, 1 or 2 (0 = AUTO, 1 = PORTRAIT_ONLY, 2 = LANDSCAPE_ONLY)
* SET_SCREEN_OFF_TIMEOUT: Set screen off timeout for a device. Requires `screen_off_timeout` in command arguments where `screen_off_timeout` should be either -1 or between 5000 and 1800000
* SET_STREAM_VOLUME : Set strema volume for a device. Requires `stream` and `volume_level` in command arguments where `stream` should be either 0(Ring), 1(Notification), 2(Alarm) or 3(Music) and `volume_level` should be a value from 0 to 100
* SET_TIMEZONE : Set the timezone for a device. Requires `timezone_string` in command arguments where `timezone_string` is a valid string representing the timezone
* SET_WIFI_STATE : Set the wifi state (ON/OFF) for a device. Requires `wifi_state` in command arguments where `wifi_state` is a boolean. 
* UNINSTALL: Uninstall an app from device. Requires `package_name` in command arguments where `package_name` is the app package uploaded on Esper
* UPDATE_DEVICE_CONFIG: Push additional configurations to the Device
* UPDATE_HEARTBEAT: Ping a device
* UPDATE_LATEST_DPC : Prompt device to update the DPC app to the latest versions.
* WIPE : Wipes the device.
Enum: "ADD_TO_WHITELIST" "ADD_WIFI_AP" "CLEAR_APP_DATA" "INSTALL" "LOCK" "REBOOT" "REMOVE_FROM_WHITELIST" "REMOVE_WIFI_AP" "SET_APP_PERMISSION" "SET_APP_STATE" "SET_BLUETOOTH_STATE" "SET_BRIGHTNESS_SCALE" "SET_DEVICE_LOCKDOWN_STATE" "SET_GPS_STATE" "SET_KIOSK_APP" "SET_NEW_POLICY" "SET_ROTATION_STATE" "SET_SCREEN_OFF_TIMEOUT" "SET_STREAM_VOLUME" "SET_TIMEZONE" "SET_WIFI_STATE" "UNINSTALL" "UPDATE_DEVICE_CONFIG" "UPDATE_HEARTBEAT" "UPDATE_LATEST_DPC" "WIPE"
object (Command args)
schedule
string (V0CommandScheduleEnum)

Following Schedule types are supported

* IMMEDIATE: Schedule the command to execcute Immediately
* WINDOW: Schedule the command to execute within the given window
* RECURRING: Schedule the command to execute repeatedly, within given parameters
Enum: "IMMEDIATE" "WINDOW" "RECURRING"
object (Command Schedule Arguments)
Responses
201

command request successfully created

post/v0/enterprise/{enterprise_id}/command/
Response samples
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "enterprise": "796caaf9-a7de-4817-9ffa-39d04bf83de9",
  • "command_type": "DEVICE",
  • "devices": [
    ],
  • "groups": [
    ],
  • "device_type": "active",
  • "command": "ADD_TO_WHITELIST",
  • "command_args": {
    },
  • "schedule": "IMMEDIATE",
  • "schedule_args": {
    },
  • "issued_by": "string",
  • "created_on": "2019-08-24T14:15:22Z",
  • "status": [
    ]
}

get status list for command request

API to get and filter command request status

Request
Security:
path Parameters
enterprise_id
required
string <uuid>

ID of the enterprise

request_id
required
string <uuid>

ID for the command request

query Parameters
device
string

Filter status result by device id.

state
string

Filter by command state

Responses
200

on successful request

get/v0/enterprise/{enterprise_id}/command/{request_id}/status/
Response samples
application/json
{
  • "count": 0,
  • "next": "string",
  • "previous": "string",
  • "results": [
    ]
}

get command history for device

API to get and filter deivce command history

Request
Security:
path Parameters
enterprise_id
required
string <uuid>

Id of the enterprise

device_id
required
string <uuid>

Id for the command request

query Parameters
state
string

Filter by command state

Responses
200

on successful request

get/v0/enterprise/{enterprise_id}/device/{device_id}/command-history/
Response samples
application/json
{
  • "count": 0,
  • "next": "string",
  • "previous": "string",
  • "results": [
    ]
}