Request Sync

Note: You must implement Request Sync in order to submit a smart home Action.

Request Sync triggers a SYNC request to your fulfillment for any Google user with devices that have the specified agentUserId associated with them (which you sent in the original SYNC request). This allows you to update users' devices without unlinking and relinking their account. All users linked to this identifier will receive a SYNC request.

You must trigger a SYNC request:

• If the user adds a new device.
• If the user removes an existing device.
• If the user renames an existing device.
• If you implement a new device type, trait, or add a new device feature.

Get started

To implement Request Sync, follow these steps:

• Enable the Google HomeGraph API
• Create a Service Account Key
• Call the API

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

HTTP

The Home Graph API provides an HTTP endpoint

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:

oauth2l fetch --credentials service-account.json \
  --scope https://www.googleapis.com/auth/homegraph

3. Create the JSON request with the agentUserId. Here's a sample JSON request for Request Sync:

{
  "agentUserId": "user-123"
}

4. Combine the Request Sync 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:

curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @request-body.json \
  "https://homegraph.googleapis.com/v1/devices:requestSync"

gRPC

The Home Graph API provides a gRPC endpoint

1. Get the protocol buffers service definition for the Home Graph API.
2. Follow the gRPC developer documentation to generate client stubs for one of the supported languages.
3. Call the RequestSync method.

Node.js

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

1. Initialize the google.homegraph service using Application Default Credentials.
2. Call the requestSync method with the RequestSyncDevicesRequest. It returns a Promise with an empty RequestSyncDevicesResponse.

const homegraphClient = homegraph({
  version: 'v1',
  auth: new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/homegraph'
  })
});

const res = await homegraphClient.devices.requestSync({
  requestBody: {
    agentUserId: 'PLACEHOLDER-USER-ID',
    async: false
  }
});
    

Java

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

1. Initialize the HomeGraphApiService using Application Default Credentials
2. Call the requestSync method with the RequestSyncDevicesRequest. It returns an empty ReportStateAndNotificationResponse

// Get Application Default credentials.
GoogleCredentials credentials =
    GoogleCredentials.getApplicationDefault()
        .createScoped(List.of("https://www.googleapis.com/auth/homegraph"));

// Create Home Graph service client.
HomeGraphService homegraphService =
    new HomeGraphService.Builder(
            GoogleNetHttpTransport.newTrustedTransport(),
            GsonFactory.getDefaultInstance(),
            new HttpCredentialsAdapter(credentials))
        .setApplicationName("HomeGraphExample/1.0")
        .build();

// Request sync.
RequestSyncDevicesRequest request =
    new RequestSyncDevicesRequest().setAgentUserId("PLACEHOLDER-USER-ID").setAsync(false);
homegraphService.devices().requestSync(request);
    

Note: You should discontinue calling Request Sync upon receiving a DISCONNECT intent, indicating the user has unlinked their account.

Error responses

You may receive one of the following error responses when calling Request Sync. These responses come in the form of HTTP status codes.

• 400 - Failure: The server was unable to process the request sent by the client due to invalid syntax. Common causes include malformed JSON or using null instead of "" for a string value.
• 403 - Failure: The server was unable to process the the request for given agentUserId due to an error while refreshing the token. Please make sure your OAuth endpoint responds correctly to refresh token request and check the user's account linking status.
• 404 - Failure: The requested resource could not be found but may be available in the future. Typically, this means that the user account is not linked with Google or we received an invalid agentUserId. Ensure that the agentUserId matches the value provided in your SYNC response, and you are properly handling DISCONNECT intents.
• 429 - Failure: Maximum number of concurrent sync requests has been exceeded for the given agentUserId. A caller may only issue one concurrent sync request unless the async flag is set to true.