Skip to content

Create a command request
Legacy

Request

API to create a command request for the device.

Security
apiKey
Path
enterprise_idstring, (uuid)required

ID of the enterprise

Body*/*required

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

command_typestring

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"
devicesArray of strings, (uuid), [ 0 .. 1000 ] items

list of devices to run commands

groupsArray of strings, (uuid), [ 0 .. 500 ] items

list of groups to run commands

commandstring(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/LAUNCHABLE_BUT_HIDDEN. 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 stream 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.
* RESET_LOCKSCREEN_PASSWORD: Change the lockscreen password of the device. Requires `new_lockscreen_password` in command arguments where `new_lockscreen_password` is a valid string.
* CAPTURE_SCREENSHOT: Allows you to take a screenshot of the device's current screen. The "tag" is an optional param that can be set to corresponding screenshot.
* UPDATE_BLUEPRINT: Pushes or reapplies the most current Blueprint version to the device or group.
* NOTIFY_DEVICE: Allows you to  broadcast message to the device. Requires 'title', 'message' and 'url' (optional) as string in command arguments. For scheduled message command requires 'name', 'time_type' as string and 'start_datetime' and 'end_datetime' as date-time.
* SET_DEVICE_LANGUAGE: Set language for a device. Requires locale value in xx[_Zzzz]_yy where xx is language code, Zzzz is script (optional) and yy is country code.
* SET_ETHERNET_SETTINGS: Set ethernet settings on supported Device
* SET_STATIC_IP: Set static ip on the deivce. Requires interface, dhcp_dnabled, static_ip, primary_dns, subnet_mask, gateway, secondary_dns (optional)
* BEEP_DEVICE: Allows you to make the device beep for a specified duration
* SET_APP_NOTIFICATIONS: Enable/disable app notifications. Requries `app_notifications_state` and `package_name` in command arguments where `app_notifications_state` is a string that has the value `ENABLED` or `DISABLED` and `package_name` is the app package uploaded on Esper.
* USE_ONLY_SAVED_WIFI_AP: Allow/disallow device to connect to unregistered WiFi APs. Requires boolean `use_only_saved_ap`.
* CONVERGE: Allows you to converge the device to the latest version of its assigned blueprint.
* SYNC_CONTENT: Allows you to sync content to the device. Requires `content_id` in command arguments where `content_id` is the id of the content to be synced. ```
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"
command_argsobject(Command args)
schedulestring(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 during the scheduled time until it succeeds or expires. After executing successfully, it will not fire again.
Enum:"IMMEDIATE""WINDOW""RECURRING"
schedule_argsobject(Command Schedule Arguments)
cURL
curl -i -X POST \
  'https://develop-api.esper.io/_mock/openapi/v0/enterprise/{enterprise_id}/command/' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: */*' \
  -d '{
    "command_type": "DEVICE",
    "devices": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ],
    "groups": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ],
    "command": "ADD_TO_WHITELIST",
    "command_args": {
      "device_alias_name": "string",
      "custom_settings_config": {},
      "app_version": "string",
      "package_name": "string",
      "policy_url": "string",
      "wifi_access_points": {},
      "state": "string",
      "message": "string",
      "title": "string",
      "url": "string",
      "app_state": "string",
      "bluetooth_state": true,
      "brightness_value": 0,
      "gps_state": 0,
      "rotate_state": 0,
      "screen_off_timeout": 0,
      "stream": 0,
      "volume_level": 0,
      "timezone_string": 0,
      "wifi_state": true,
      "wifi_revert_timeout": 0,
      "locale": "string",
      "ethernet_auth_mode": "NONE",
      "ethernet_ca_cert_alias": "string",
      "ethernet_client_cert_alias": "string",
      "ethernet_eap_identity": "string",
      "interface": "string",
      "dhcp_enabled": "string",
      "static_ip": "string",
      "primary_dns": "string",
      "subnet_mask": "string",
      "secondary_dns": "string",
      "gateway": "string",
      "duration": "string",
      "tag": "string",
      "video_quality": "string",
      "enable_debug_mode": false,
      "converge_with_provision_option": false,
      "auto_update_mode": "autoUpdateDefault",
      "content_id": "string"
    },
    "schedule": "IMMEDIATE",
    "schedule_args": {
      "name": "string",
      "start_datetime": "2019-08-24T14:15:22Z",
      "end_datetime": "2019-08-24T14:15:22Z",
      "time_type": "console",
      "window_start_time": "string",
      "window_end_time": "string",
      "days": [
        "string"
      ]
    }
  }'

Responses

command request successfully created

Bodyapplication/json
idstring, (uuid)(Id)read-only

Unique command request identifier

enterprisestring, (uuid)(Enterperise ID)read-only

Esper account identifier

command_typestring

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"
devicesArray of strings, (uuid), [ 0 .. 1000 ] items

list of devices to run commands

groupsArray of strings, (uuid), [ 0 .. 500 ] items

list of groups to run commands

commandstring(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/LAUNCHABLE_BUT_HIDDEN. 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 stream 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.
* RESET_LOCKSCREEN_PASSWORD: Change the lockscreen password of the device. Requires `new_lockscreen_password` in command arguments where `new_lockscreen_password` is a valid string.
* CAPTURE_SCREENSHOT: Allows you to take a screenshot of the device's current screen. The "tag" is an optional param that can be set to corresponding screenshot.
* UPDATE_BLUEPRINT: Pushes or reapplies the most current Blueprint version to the device or group.
* NOTIFY_DEVICE: Allows you to  broadcast message to the device. Requires 'title', 'message' and 'url' (optional) as string in command arguments. For scheduled message command requires 'name', 'time_type' as string and 'start_datetime' and 'end_datetime' as date-time.
* SET_DEVICE_LANGUAGE: Set language for a device. Requires locale value in xx[_Zzzz]_yy where xx is language code, Zzzz is script (optional) and yy is country code.
* SET_ETHERNET_SETTINGS: Set ethernet settings on supported Device
* SET_STATIC_IP: Set static ip on the deivce. Requires interface, dhcp_dnabled, static_ip, primary_dns, subnet_mask, gateway, secondary_dns (optional)
* BEEP_DEVICE: Allows you to make the device beep for a specified duration
* SET_APP_NOTIFICATIONS: Enable/disable app notifications. Requries `app_notifications_state` and `package_name` in command arguments where `app_notifications_state` is a string that has the value `ENABLED` or `DISABLED` and `package_name` is the app package uploaded on Esper.
* USE_ONLY_SAVED_WIFI_AP: Allow/disallow device to connect to unregistered WiFi APs. Requires boolean `use_only_saved_ap`.
* CONVERGE: Allows you to converge the device to the latest version of its assigned blueprint.
* SYNC_CONTENT: Allows you to sync content to the device. Requires `content_id` in command arguments where `content_id` is the id of the content to be synced. ```
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"
command_argsobject(Command args)
schedulestring(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 during the scheduled time until it succeeds or expires. After executing successfully, it will not fire again.
Enum:"IMMEDIATE""WINDOW""RECURRING"
schedule_argsobject(Command Schedule Arguments)
issued_bystring, (url)read-only

command is issued by this user

created_onstring, (date-time)(Created on)read-only

Timestamp of command request

statusArray of objects(Current Status)read-only

Show current status of commands issued during this request

Response
{ "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "enterprise": "796caaf9-a7de-4817-9ffa-39d04bf83de9", "command_type": "DEVICE", "devices": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ], "groups": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ], "command": "ADD_TO_WHITELIST", "command_args": { "device_alias_name": "string", "custom_settings_config": {}, "app_version": "string", "package_name": "string", "policy_url": "string", "wifi_access_points": {}, "state": "string", "message": "string", "title": "string", "url": "string", "app_state": "string", "bluetooth_state": true, "brightness_value": 0, "gps_state": 0, "rotate_state": 0, "screen_off_timeout": 0, "stream": 0, "volume_level": 0, "timezone_string": 0, "wifi_state": true, "wifi_revert_timeout": 0, "locale": "string", "ethernet_auth_mode": "NONE", "ethernet_ca_cert_alias": "string", "ethernet_client_cert_alias": "string", "ethernet_eap_identity": "string", "interface": "string", "dhcp_enabled": "string", "static_ip": "string", "primary_dns": "string", "subnet_mask": "string", "secondary_dns": "string", "gateway": "string", "duration": "string", "tag": "string", "video_quality": "string", "enable_debug_mode": false, "converge_with_provision_option": false, "auto_update_mode": "autoUpdateDefault", "content_id": "string" }, "schedule": "IMMEDIATE", "schedule_args": { "name": "string", "start_datetime": "2019-08-24T14:15:22Z", "end_datetime": "2019-08-24T14:15:22Z", "time_type": "console", "window_start_time": "string", "window_end_time": "string", "days": [] }, "issued_by": "string", "created_on": "2019-08-24T14:15:22Z", "status": [ {} ] }