Recurring scheduled commands not natively supported: use external scheduler with API

Android

Improved Title: Recurring device commands — use an external scheduler with the Esper API

When you need to run a command on a recurring schedule — such as rebooting a device group every morning — the Esper Console's built-in command scheduling does not repeat automatically, so each execution must be triggered individually.

Why this happens

The Esper API's schedule_args object defines a single time window for command execution. It has no native recurrence parameters (daily, weekly, or cron-based). To achieve recurring behavior, an external scheduler must call the Esper API once per desired interval, creating a fresh one-time command each time.

Before you begin

Retrieve your API access token from Esper Console → Settings → API Key Management.
Identify the Group ID for the devices you want to target. You can find this in Devices & Groups → [Group Name] — the ID appears in the page URL.
Confirm you have access to an external scheduler: Linux cron, AWS EventBridge, GitHub Actions, or Windows Task Scheduler.
Have Python 3 (or your preferred scripting language) available on the system running the scheduler.

Step 1: Construct the command payload

Build a one-time command payload targeting your device group. The start_datetime and end_datetime fields must be in UTC (indicated by the Z suffix). Convert your local target time to UTC before setting these values — for example, 7:00 AM UTC+2 equals 05:00 UTC.
```
{
  "command_type": "GROUP",
  "command": "REBOOT",
  "schedule": "WINDOW",
  "schedule_args": {
    "name": "Daily reboot 2026-08-04",
    "start_datetime": "2026-08-04T05:00:00Z",
    "end_datetime": "2026-08-04T05:10:00Z",
    "time_type": "device"
  },
  "groups": ["<YOUR_GROUP_ID>"],
  "device_type": "all"
}
```
Keep the execution window (the gap between start_datetime and end_datetime) at least 10 minutes wide. Devices that are offline when the command is issued will receive it as soon as they reconnect, provided they reconnect within this window.

Step 2: Write the scheduling script

Create a script that performs the following on each run:
- Calculates the next execution window dynamically, based on your recurrence interval.
- Stamps the name field with the current date (for example, Daily reboot 2026-08-04) so commands remain identifiable in the Activity Feed.
- POSTs the payload to the Esper group command endpoint, authenticating with your API access token in the request header.
- Checks the HTTP response code — a successful submission returns 200 or 202. Log any other response code for investigation.
The script should run several minutes before the intended command window opens — this gives the API call time to be processed before the window starts.

Step 3: Configure the external scheduler

Set your scheduler to trigger the script at your desired interval. The example below schedules a Linux cron job to run the script at 04:55 UTC every day — five minutes before a 05:00 UTC command window opens.
```
55 4 * * * /usr/bin/python3 /opt/esper/daily_reboot.py
```
If Linux cron is not available, the following alternatives work with the same script:
- AWS EventBridge — create a scheduled rule with a cron or rate expression targeting a Lambda function or ECS task that runs the script.
- GitHub Actions — use a schedule trigger with a cron expression in your workflow file.
- Windows Task Scheduler — create a basic task with a daily or custom trigger pointing to your Python interpreter and script path.

Step 4: Verify command execution

After the first scheduled run, navigate to Devices & Groups → [Group Name] → Activity Feed in the Esper Console.
Confirm a REBOOT command entry appears with the status Succeeded for your target devices at the expected time.

Verify: Each device in the group should show a Succeeded status for the command in the Activity Feed within 10 minutes of the command window opening. Devices that were offline but reconnected within the window will also show Succeeded once they check in.

If this doesn't resolve it

If commands are not appearing in the Activity Feed or are showing a status other than Succeeded, collect the following before contacting Esper Support:

The full API response body and HTTP status code returned when your script POSTed the command.
The exact start_datetime and end_datetime values used (confirm they are in UTC with a Z suffix).
The Group ID targeted and the number of devices in the group.
A screenshot of the Activity Feed entry showing the unexpected status.

Contact Esper Support with these details.

Still need help?

If you need assistance setting up an external scheduler with the Esper API for recurring commands, submit a support ticket and include details about your scheduling tool, command frequency requirements, and API authentication setup.