Reconnect a lost Zigbee device

Reconnect a lost Zigbee device repairs an existing device instead of creating a second one. Use the recovery endpoints to read current recovery status, start a reconnect operation, and wait for fresh device contact plus the final recovery result before you show success. Sleeping battery devices behave differently from mains-powered devices, and a request acknowledgement or cached reading is not proof of recovery.

When to use reconnect

Use reconnect when a Zigbee device already exists in the home but has become unavailable. Reconnect preserves the device identity, room assignment, and routine or security references.

Do not guide users toward creating a duplicate device for the same hardware. Use Reconnect for an existing lost device rather than creating a duplicate.

Deletion is a separate flow. Before confirming deletion, review its impact on routines and security membership. A sleeping device may later need its documented physical reset before a deliberate new acquisition.

Supported client surfaces

Web and mobile support repair and deletion. TV is for status and usage.

If you deep-link from an unavailable-device notification, keep navigation scoped to the identified device and home. The notification opens that exact device in its home, subject to current account access.

Recovery API

Read recovery status

GET /integrations/zigbee/recovery/:endpointId with tenantId and propertyId returns:

• current availability
• last actual contact
• expected report interval
• durable operation progress

Use the authenticated API and capability/settings descriptors for the selected tenant and home. Respect server-returned permissions, availability, versions and pending versus confirmed results.

Do not infer a supported action from brand, model, cached state or a successful request acknowledgement.

Preview deletion impact

Before deletion, call:

GET /integrations/zigbee/recovery/:endpointId/impact

Review the affected routines and security membership before the user confirms.

Start an operation

POST /integrations/zigbee/recovery/:endpointId/operations with the same scope requires:

Field	Required	Notes
tenantId	Yes	Selected tenant scope
propertyId	Yes	Selected home scope
requestId	Yes	Must be unique per operation attempt
operation	Yes	reconnect or delete
impactToken	When applicable	Use the token returned by impact preview
removeUnreachable	Only for explicit second confirmation	Not an automatic fallback

Keep request identity on redelivery; do not create repeated operations on a timeout.

Recovery workflow

1. Read recovery status with GET /integrations/zigbee/recovery/:endpointId.
2. If the user wants deletion, fetch GET /integrations/zigbee/recovery/:endpointId/impact first.
3. Start reconnect or delete with POST /integrations/zigbee/recovery/:endpointId/operations.
4. Track the correlated operation result and current reported state.
5. Wait for fresh device contact and a terminal result before showing completion.

A repair request or old cached reading is not proof of recovery. Follow correlated operation results and current reported state.

Operation states

Handle these results distinctly:

• waiting_for_device
• waiting_for_hub
• configuring
• review_required
• needs_reset
• failed
• terminal results

Pending states are not confirmation. Confirm recovery only after the device reports fresh contact and the repair completes.

If the hub is unavailable, do not offer recovery as if it can proceed. Local functions can keep working during a cloud outage; Zigbee recovery depends on the home hub being online.

Sleeping battery devices

Sleeping battery devices can wait for their next report and must not be treated like mains-powered devices.

Developer guidance:

• show model-specific wake instructions when available
• do not repeatedly poll as proof of recovery
• do not equate inactivity with failure during the normal sleep interval
• expect recovery to remain pending until the device checks in again

A sleeping device may need its documented physical reset before a deliberate new acquisition.

Delete versus reconnect

Reconnect keeps the current device record and references.

Delete removes the device from the home and can affect:

• routines
• security membership
• other references tied to that endpoint

removeUnreachable is explicit second confirmation, not an automatic fallback.

If deletion completes locally after a device fails to confirm leaving, tell the user that the physical device may still require a reset before it can be paired again.

Client behavior requirements

Public clients must not call internal transport endpoints or bypass home authorization. Never post fabricated contact or progress from a public client.

Also make sure your client:

• preserves settings fields the client does not edit
• respects server-returned permissions and availability
• treats pending and confirmed results differently
• does not infer support from brand, model, or cached state
• keeps device and home scoping exact for actionable notifications

Device-type settings are shared across brands exposing the required capabilities.

Permissions and credential boundaries

Household permissions are narrower than staff, so always honor the server response for the current account and home.

Live connector credentials cannot start household repairs. LIVE credentials only for their own installed connector.

DEV credentials act in the developer sandbox.

UX guidance

Show the device as recovered only when there is a fresh verified check-in and the operation reaches a successful final state.

Avoid telling users to do any of the following as part of reconnect:

• factory-reset the whole hub
• repeatedly lock or unlock a door to test connectivity

For lock devices, recovery should be framed as a reconnect or pairing-network step, not as a lock test.

When deletion is offered, present the impact review before the destructive confirmation.