UPDATE_WIFI_AP fails with "Unsupported" — migrate via ADD/REMOVE/ADD

Android

When you send an UPDATE_WIFI_AP command to change the password of a Wi-Fi network the device is actively using, the Esper Agent rejects it with an Unsupported error and the password is not updated.

Why this happens

The Esper Agent blocks in-place credential changes on the active network connection. Modifying the password of a network while the device is connected to it would invalidate the current session and disconnect the device before the new credentials could be applied. To avoid leaving devices offline, the agent rejects the command entirely. The safest resolution is a three-step migration: add a backup network, remove and re-add the primary network with the new password, then remove the backup.

Steps

1. Add a temporary backup network so the device has a fallback connection before you touch the primary profile. Replace <tenant>, <token>, <device_id>, and the backup network values with your own.

   curl -s -X POST "https://<tenant>-api.esper.cloud/api/commands/v0/commands/" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
       "command_type": "DEVICE",
       "devices": ["<device_id>"],
       "device_type": "all",
       "command": "ADD_WIFI_AP",
       "command_args": {
         "wifi_ssid": "<backup-ssid>",
         "wifi_password": "<backup-password>",
         "wifi_security_type": "WPA2",
         "hidden": false
       }
     }'

2. Confirm the device has connected to the backup network before proceeding. In the Esper Console, go to Devices & Groups → [Device Name] → Device Info → Network and verify the active SSID matches your backup network. Do not continue until this is confirmed — removing the primary profile while the device is still on it will disconnect it.
3. Remove the primary network profile. Because the device is now on the backup network, this command will succeed.

   curl -s -X POST "https://<tenant>-api.esper.cloud/api/commands/v0/commands/" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
       "command_type": "DEVICE",
       "devices": ["<device_id>"],
       "device_type": "all",
       "command": "REMOVE_WIFI_AP",
       "command_args": {
         "wifi_ssid": "<primary-ssid>"
       }
     }'

4. Re-add the primary network with the new password. The device will save the updated profile and attempt to connect automatically.

   curl -s -X POST "https://<tenant>-api.esper.cloud/api/commands/v0/commands/" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
       "command_type": "DEVICE",
       "devices": ["<device_id>"],
       "device_type": "all",
       "command": "ADD_WIFI_AP",
       "command_args": {
         "wifi_ssid": "<primary-ssid>",
         "wifi_password": "<new-password>",
         "wifi_security_type": "WPA2",
         "hidden": false
       }
     }'

5. Remove the backup network once the device is stable on the primary network. This keeps the saved network list clean and prevents unintended fallback connections.

   curl -s -X POST "https://<tenant>-api.esper.cloud/api/commands/v0/commands/" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
       "command_type": "DEVICE",
       "devices": ["<device_id>"],
       "device_type": "all",
       "command": "REMOVE_WIFI_AP",
       "command_args": {
         "wifi_ssid": "<backup-ssid>"
       }
     }'

Verify: In the Esper Console, go to Devices & Groups → [Device Name] → Device Info → Network and confirm the active SSID is the primary network. Then go to Devices & Groups → [Device Name] → Activity Feed and confirm all five commands show a Success status. The device should reflect the updated network state within 5 minutes of the final command completing.

If this doesn't resolve it

If any command in the sequence returns an error status or the device does not reconnect to the primary network, collect the following before contacting Esper Support:

• The full API response body for each failed command
• The device ID and your tenant name
• The Esper Agent version from Devices & Groups → [Device Name] → Device Info → Software Info
• A screenshot of the Activity Feed showing the failed command entries

Contact Esper Support at support.esper.io with this information.

Still need help?

If the steps above don't resolve the issue, submit a support ticket with your device model, Android version, Esper Agent version, and a description of what you've already tried — this helps the support team investigate without a follow-up.