Notifications for smart home Actions

The smart home notifications feature allows your Action to inform users via the Google Assistant when important device-related events or changes happen. You can implement notifications to alert users to timely device events, for example when someone is at the door.

Your smart home Action can send alerts to users as:

  • Proactive notifications: Alerts the user of a smart home device event without any preceding user requests to their devices, such as the doorbell ringing.

Users receive notifications from the Assistant as audio announcements. Users have the ability to turn on or off all proactive notifications from the Google Home app; by default, notifications are turned off.

Events that trigger notifications

When device events occur, your Action fulfilment sends a notification request to Google. The type of events that users can be alerted to and the notification data you send depends on the device traits that your Action supports.

The following traits support proactive notifications:

Trait Events
ObjectDetection Objects detected by the device, such as when a recognized face is detected at the door. For example: "Alice and Bob are at the front door."

All device types support notifications for the applicable traits.

Build notifications for your smart home Action

To implement notifications for smart home Actions, follow these steps:

  1. Indicate to Google if notifications are enabled from your smart home device app. If users turn notifications on or off in your app, send a SYNC request to inform Google of the device change.
  2. When a relevant device event or state change occurs that triggers a notification, send a notification request by calling the Report State reportStateAndNotification API. If the device state changed, you can send both a state and notification payload together in your Report State and Notification call.

The following sections cover these steps in more detail.

Indicate if notifications are enabled in your app

Users can choose whether they want to receive proactive notifications by enabling this feature in the Google Home app. In the app for your smart home device, you can also optionally add the ability for users to explicitly toggle notifications from the device (for example, from your app settings).

To indicate to Google that notifications are enabled for your device, make a Request SYNC call to update device data.

In your SYNC response, send one of these updates:

  • If the user explicitly toggled notifications on in your device app, or if you do not provide a toggle option, set the devices.notificationSupportedByAgent property to true.
  • If the user explicitly toggled notifications off in your device app, set the devices.notificationSupportedByAgent property to false.

The following snippet shows an example of how to set your SYNC response:

devices: [{
   id: 'device123',
   ...
   notificationSupportedByAgent: true,
}]

Send notification requests to Google

To trigger notifications on the Assistant, your fulfillment sends a notification payload to the Google Home Graph via a Report State and Notification API call.

Enable the Google HomeGraph API

  1. In the Google Cloud Platform Console, go to the HomeGraph API page.

    Go to the HomeGraph API page
  2. Select the project that matches your smart home project ID.
  3. Click ENABLE.

Create a Service Account Key

Follow these instructions to generate a service account key from the GCP Console:

Note: Ensure that you are using the correct GCP project when performing these steps. This is the project that matches your smart home project ID.
  1. In the GCP Console, go to the Create service account key page.

    Go to the Create Service Account Key page
  2. From the Service account list, select New service account.
  3. In the Service account name field, enter a name.
  4. In the Service account ID field, enter a ID.
  5. From the Role list, select Service Accounts > Service Account Token Creator.

  6. For the Key type, select the JSON option.

  7. Click Create. A JSON file that contains your key downloads to your computer.

Call the API

Make the notification request call using the devices.reportStateAndNotification API. Your JSON request must include an eventId, which is a unique ID generated by your platform for the event triggering the notification. The eventId should be a random ID that is different every time you send a notification request.

In the notifications object that you pass in your API call, include a priority value which defines how the notification should be presented. Your notifications object may include different fields depending on the device trait.

Send a proactive notification payload

To call the API, select an option from one of these tabs:

HTTP POST

  1. Use the downloaded service account JSON file to create a JSON Web Token (JWT). For more information, see Authenticating Using a Service Account.
  2. Obtain an OAuth 2.0 access token with the https://www.googleapis.com/auth/homegraph scope using oauth2l:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. Create the JSON request with the agentUserId. Here's a sample JSON request for Report State and Notification:
  5. {
      "agentUserId": "user1234",
      "eventId": "event-id-123",
      "requestId": "request-id-123",
      "payload": {
        "devices": {
          "notifications": {
            "device-456": {
              "ObjectDetected": {
                "priority": 0,
                "detectionTimestamp": 1534875126750,
                "objects": {
                  "named": [
                    "Alice"
                  ],
                  "unclassified": 2
                }
              }
            }
          }
        }
      }
    }
    
  6. Combine the Report State and Notification JSON and the token in your HTTP POST request to the Google Home Graph endpoint. Here's an example of how to make the request in the command line using curl, as a test:
  7. curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d @request-body.json \
      "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"
    

Node.js

The Google APIs Node.js Client provides bindings for the Home Graph API.

  1. Place the downloaded service account JSON in your project directory.
  2. Initialize a google.auth.JWT object.
  3. Initialize the google.homegraph service.
  4. Call the reportStateAndNotification method with the ReportStateAndNotificationRequest. It returns a Promise with the ReportStateAndNotificationResponse.
const keys = require('./smart-home-key.json');
const auth = new google.auth.JWT(
  keys.client_email,
  undefined,
  keys.private_key,
  ['https://www.googleapis.com/auth/homegraph']
);

// Acquire an auth client, and bind it to all future calls
const homegraph = google.homegraph({
  version: 'v1',
});

const eventId = 'event-id-123' // Generate randomly
const requestId = 'request-id-123' // Generate randomly

const res = await homegraph.devices.reportStateAndNotification({
  auth,
  requestBody: {
    agentUserId: 'user1234',
    eventId,
    requestId,
    payload: {
      devices: {
        notifications: {
          'device-456': {
            ObjectDetected: {
              priority: 0,
              detectionTimestamp: 1534875126750,
              objects: {
                named: ['Alice'],
                unclassified: 2
              }
            }
          }
        }
      }
    }
  }
});
    

Java

The HomeGraph API Client Library for Java provides bindings for the Home Graph API.

  1. Place the downloaded service account JSON in your project directory.
  2. Initialize a GoogleCredentials object.
  3. Initialize the HomeGraphApiService with the credentials
  4. Call the reportStateAndNotification method with the ReportStateAndNotificationRequest. It returns a ReportStateAndNotificationResponse
Struct objectDetectionNotification =
    Struct.newBuilder()
        .putFields(
            "ObjectDetected",
            Value.newBuilder()
                .setStructValue(
                    Struct.newBuilder()
                        .putFields("priority", Value.newBuilder().setNumberValue(0).build())
                        .putFields(
                            "detectionTimestamp",
                            Value.newBuilder().setNumberValue(1534875126).build())
                        .putFields(
                            "objects",
                            Value.newBuilder()
                                .setStructValue(
                                    Struct.newBuilder()
                                        .putFields(
                                            "named",
                                            Value.newBuilder()
                                                .setListValue(
                                                    ListValue.newBuilder()
                                                        .addValues(
                                                            Value.newBuilder()
                                                                .setStringValue("Alice")
                                                                .build())
                                                        .build())
                                                .build())
                                        .putFields(
                                            "unclassified",
                                            Value.newBuilder().setNumberValue(2).build())
                                        .build())
                                .build())
                        .build())
                .build())
        .build();

HomeGraphApiServiceProto.ReportStateAndNotificationDevice.Builder deviceBuilder =
    HomeGraphApiServiceProto.ReportStateAndNotificationDevice.newBuilder()
        .setNotifications(
            Struct.newBuilder()
                .putFields(
                    "device-456",
                    Value.newBuilder().setStructValue(objectDetectionNotification).build()));

HomeGraphApiServiceProto.ReportStateAndNotificationRequest request =
    HomeGraphApiServiceProto.ReportStateAndNotificationRequest.newBuilder()
        .setRequestId(String.valueOf(Math.random()))
        .setAgentUserId("USER-ID") // our single user's id
        .setEventId("PLACEHOLDER-EVENT-ID")
        .setPayload(
            HomeGraphApiServiceProto.StateAndNotificationPayload.newBuilder()
                .setDevices(deviceBuilder))
        .build();

// Create gRPC channel
GoogleCredentials credentials =
    GoogleCredentials.fromStream(new FileInputStream("smart-home-key.json"));
ManagedChannel managedChannel =
    ManagedChannelBuilder.forTarget("homegraph.googleapis.com").build();
HomeGraphApiServiceGrpc.HomeGraphApiServiceBlockingStub homegraphService =
    HomeGraphApiServiceGrpc.newBlockingStub(managedChannel)
        .withCallCredentials(MoreCallCredentials.from(credentials));

homegraphService.reportStateAndNotification(request);
    

Logging

Notifications support event logging as outlined in the Smart Home Monitoring and Logging documentation. These logs are useful for testing and maintaining notifications quality within your Action.

The following is the schema of a notificationLog entry:

Property Description
requestId Notification request ID.
structName Name of the notification struct, such as "ObjectDetection".
status Indicates the status of the notification.

The status field includes various statuses that may indicate errors in the notification payload. Some of these may only be available on Actions that have not been launched to production.

Example statuses include:

Status Description
EVENT_ID_MISSING Indicates that the required eventId field is missing.
PRIORITY_MISSING Indicates that a priority field is missing.
NOTIFICATION_SUPPORTED_BY_AGENT_FALSE Indicates that the notifying device's notificationSupportedByAgent property provided in SYNC is false.
NOTIFICATION_ENABLED_BY_USER_FALSE Indicates that the user has not enabled notifications on the notifying device in the Google Home app. This status is only available on Actions that have not been launched to production.
NOTIFYING_DEVICE_NOT_IN_STRUCTURE Indicates that the user has not assigned the notifying device to a Home/Structure. This status is only available on Actions that have not been launched to production.

In addition to these general statuses that can apply to all notifications, the status field may also include trait-specific statuses where applicable (e.g. OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING).