Command API Examples

Whenever you reboot, install an app, or perform any other action on a device from the console, you send a command. Commands are singular actions that affect a device. This article provides additional documentation for our Commands APIs. 

In this article: 

• Getting Started
• Constructing a Command
• Command Examples
  • Install certificate 
  • Uninstall certificate

Getting Started

How do I know which commands API to use?

• The Commands V2 API supports Android devices. That is, the endpoint https://{tenant-name}-api.esper.cloud/api/v0/enterprise/{enterprise_id}/command/.
• The Commands Request API supports mixed fleet (Android, iOS, etc.). That is, the endpoint https://{tenant-name}-api.esper.cloud/api/commands/v0/commands/. 

Devices will only receive commands if supported. For example, Android devices will not receive the INSTALL_PROFILE command as this is supported by iOS devices. 

Not sure where to start? 

See our Getting Started with APIs article to learn how to create API keys and send requests.

Constructing a Command

Command body 

The command body (also known as the request body or payload) contains information to process the request.

{
  "command_type": "DEVICE",
  "devices": [
    "device_id"
  ],
  "device_type": "all",
  "command": "command",
  "command_args": {
    "key":"value"
  }
}

Command Keys and Values 

Use the following keys and values to target certain devices or groups. 

Command Type (required)

The command type parameter is used to specify 

• Device: A command used for devices 
  • "command_type": "DEVICE"
• Group: A command used for groups 
  • "command_type": "GROUP"
• Dynamic: A command used for a dynamic set of devices, such as a subset of devices from different groups. 
  • "command_type": "DYNAMIC"

Level (required) 

• Device Level: A command sent to a single device. Use with command_type: Device. 

"devices": [
   "497f6eca-6276-4993-bfeb-53cbbbba6f08"
]

• Group Level: A command sent to a group of devices. Use with command_type: Group. 

"groups": [
   "01922b24-adae-787f-a08a-778067704f57"
]

Device Type (required)

Specify which types of devices will receive the command. 

• Active: Fires the command to active devices only. 
  • "device_type": "active"
• Inactive: Fires the command to inactive devices only. Note: If the device remains inactive (powered off for example, or not connected to a network) during the scheduled window, the device will not receive the command even if the device type is set to all or active.
  • "device_type": "inactive"
• All: Fires the command to all devices. 
  • "device_type": "all"

Command (required)

The command. See a list of commands in the commands APIs (Command V2 or Command Request). 

Command Arguments (required)

An object containing the specific key-value pairs for the command. 

Scheduled Commands (optional)

You can also schedule commands. Learn more about scheduling commands. 

Command Examples

Install certificate 

Install a certificate on an Android version 9+ device. 

• Currently, certificates cannot be used for Wi-Fi authentication (such as EAP-TLS). 
• Include the entire certificate chain (up to Root CA certificate) in a pkcs12 file. 
• The Install Certificate command expires after 30 days. Devices that do not receive the command within 30 days (for example, devices turned off or without a network connection for 30 days) will not receive the command. A “certificate not found error” will be displayed in the Event Feed. 
• Commands are available for all command types: device, dynamic, and group. Sending this command to multiple devices or groups will install (or uninstall) the same certificate on all devices. 
• Alias names are case-sensitive. 
• Keep a record of the alias name. The alias name is the only identifier used for deletion. 

Request

  POST https://{tenant-name}-api.esper.cloud/api/commands/v0/commands/

Body 

"command_args": {
      "cert_file_type": "pkcs12",
      "cert_data_base64": "Base64 encoded string containing the contents of the pkcs12 file",
      "cert_password": "password for the pkcs12 file if applicable",
      "cert_alias_name": "unique alias name with which the certificate needs to be installed",
      "cert_storage_type": "system"
}
      

Uninstall certificate

Uninstall a certificate. 

•  If the alias name does not exist on the device, no error will be shown. The command will be marked successful.
• Alias names are case-sensitive. 
• Any certificate may be deleted with this API. Ensure the alias name is correct before using this command.

Request

POST https://{tenant-name}-api.esper.cloud/api/commands/v0/commands/

Body 

"command_args": {
      "cert_alias_name": "alias name of the certificate that needs to be uninstalled",
      "cert_storage_type": "system"
}