UPDATE_WIFI_AP command behavior for offline devices: queuing, timeouts, and multi-device targeting

Android

When you use the UPDATE_WIFI_AP API to configure Wi-Fi settings on your devices, the command behaves differently depending on whether your devices are online or offline at the time you issue the request. This article explains how command queuing works, what timeouts to expect, and how to target multiple devices efficiently.

How commands are delivered to offline devices

When you issue an UPDATE_WIFI_AP command via the Esper API, the command enters a queuing system. If the target device is offline, the command waits in a Queued state until the device reconnects and checks in with the Esper cloud. At that point, the command is delivered and executed.

However, each command type has a built-in timeout. If a device remains offline longer than this timeout window, the command expires and will not be applied, even if the device later comes online. For UPDATE_WIFI_AP commands, verify the exact timeout duration in the Esper API reference documentation, as timeouts vary by command type and typically range from 2 minutes to 3 days.

Before you begin

Understand your device fleet's typical offline duration. If devices regularly stay offline longer than the command timeout, use scheduled/windowed commands instead of immediate commands.
Have access to the Esper Console to monitor command delivery states.

Step 1: Issue the UPDATE_WIFI_AP command

Use a single UPDATE_WIFI_AP API call to target multiple devices simultaneously. You do not need to make separate API calls for each device. You can either:

Pass a list of device IDs in one request to target specific devices, or
Send the command at the group level to target an entire device group.

Step 2: Choose between immediate or scheduled delivery

For device fleets with unreliable or intermittent connectivity, use a scheduled (windowed) command rather than an immediate command. A scheduled command gives offline devices a longer eligibility window to receive and apply the configuration when they reconnect.

Set the window duration to cover the expected maximum offline period for your device fleet. This maximizes the delivery rate and reduces the number of commands that expire before devices come online.

Step 3: Monitor command delivery states

After issuing the command, track its delivery progress in the Esper Console by navigating to Devices & Groups → [Device or Group Name] → Activity Feed.

Watch for the following states:

Queued — command received; device is not yet reachable
Initiated — delivery has started
Acknowledged — device has received the command
In Progress — device is executing the command
Success — command completed successfully
Failure — command execution failed
Time Out — command expired before device came online and will not be applied

For devices that were offline at the time of the command, you should see them transition from Queued → Acknowledged → Success once they reconnect.

Step 4: Handle timeouts

If devices show Time Out at a higher rate than expected:

Verify the default timeout for UPDATE_WIFI_AP in the Esper API documentation.
Compare the timeout against your device fleet's typical offline duration.
If devices routinely stay offline longer than the timeout, reissue the command as a scheduled command with an appropriately wide window to account for your fleet's connectivity patterns.

Known limitation with scheduled commands

In some Esper Agent versions, scheduled commands may continue to execute on devices even after the configured window has expired if the device was offline when the window closed. To check whether this affects you:

Note the Esper Agent version on your affected devices. You can find this in Devices & Groups → [Device Name] → Device Details under the Agent information section.
Check the Esper Agent release notes to confirm whether this issue has been resolved in your deployed Agent version.
If you are running an older Agent version and this behavior is problematic, contact Esper Support to discuss upgrading.

Still need help?

If commands are not being delivered at all (stuck in Queued indefinitely even when devices are online), or if you encounter other issues with the UPDATE_WIFI_AP command, contact Esper Support. Have the following information ready:

Specific device IDs affected
Command IDs from the Activity Feed
Timestamps of when the commands were issued and when devices came online
Your Esper Agent version