AoG ProTips: Handing Offline Devices

Missed our weekly video? Don’t worry, watch this week’s #AoGProTips 🎥

Many factors can affect device connectivity in the home, and it’s important to keep users aware when their devices are unreachable or offline. A critical element of your smart home Action is properly maintaining and reporting the reachability of each device to Google Assistant.

The smart home API supports multiple ways to indicate that a device is unreachable, so let’s explore when it’s appropriate to use each one.

Offline status

Each response that your smart home Action provides to a QUERY and EXECUTE intent should include a status code. For most intents, the status value will be SUCCESS. When Google Assistant attempts to QUERY an unreachable device, you should return the device status as OFFLINE. This indicates that there is no additional state available from the device at this time.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "123": {
        "status": "OFFLINE"
      }
    }
  }
}

Offline error

Each EXECUTE intent represents a command to change the state of the device. If that command fails to execute for any reason, it is appropriate to report that condition with an error response. When an EXECUTE intent fails because the device was unreachable, return an ERROR status with the error code set to deviceOffline.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "ERROR",
        "errorCode": "deviceOffline"
      }
    ]
  }
}

Note that if your integration handles commands asynchronously or any other conditions require you to return a PENDING status in the EXECUTE response, you can update the status of an unreachable device using the offline state flag.

Offline status flag

Finally, we have the online state flag. Use this flag to publish any changes in device connectivity through the Report State API. This ensures that Home Graph remains up to date and reduces the chance that the Assistant sends QUERY or EXECUTE intents to an unreachable device.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "agentUserId": "1234",
  "payload": {
    "devices": {
      "states": {
        "123": {
          "online": false
        }
      }
    }
  }
}

For more helpful tips on getting the most out of your actions, be sure to check out the rest of the AoG ProTips series — and share your tips with us on Twitter using the hashtag #AoGProTips.