Requesting User Information

You can request name and address information from the user, which are typically hard for natural language processing to obtain. Actions on Google provides a built-in dialog that requests this information from users, allows them to consent to providing the information, and then provides you the information in the next request to your fulfillment endpoint. The Node.js client library provides function calls to request and parse this information.

You can currently access the following fields:

  • Display name
  • Given name
  • Family name
  • Coarse device location (zip code and city)
  • Precise device location (coordinates and street address)

User Experience

When your action requests any of this information, the Google Assistant takes control of the conversation and asks the user, on your behalf, for permission to obtain the personal information. After the user accepts or rejects the consent, the Google Assistant hands off control back to your action.

For example, a user can say:

"Recommend me a local bookstore"

If this is the first time the user interacts with your action, your action responds by asking for the user's location. The Google Assistant replies with the following message, using your action's voice:

"To find bookstores near you, I'll just need to get your zip code from Google. Is that okay?"

If the user consents to providing the information, the Google Assistant's next request to your fulfillment will contain the requested profile information.

Getting user information with the client library

Requesting User Information with the client library

The following code snippets show you how to ask for user permission using the Node.js client library.

In the following snippet, we request access to the user's name: with the askForPermission() function. This function lets you request a single piece of information at a time:

// Choose one or more supported permissions to request:
// assistant.SupportedPermissions.NAME
// assistant.SupportedPermissions.DEVICE_PRECISE_LOCATION
// assistant.SupportedPermissions.DEVICE_COARSE_LOCATION

// assistant is an instance of ApiAiAssistant or ActionsSdkAssistant
let permission = assistant.SupportedPermissions.NAME;
assistant.askForPermission('To address you by name', permission);

The Google Assistant then prompts the user in the following way:

"To address you by name, I'll just need to get your name from Google. Is that ok?"

You can also request more than one permission at once by calling askForPermissions(). In this case the user will have the choice of accepting all or none of the permissions at once.

Accessing user information with the client library

You can check if the permission has been granted by calling isPermissionGranted() and then access the data with getUserName() or getDeviceLocation().

// assistant is an instance of ApiAiAssistant or ActionsSdkAssistant
if (assistant.isPermissionGranted()) {
  let displayName = assistant.getUserName().displayName;
  let deviceCoordinates = assistant.getDeviceLocation().coordinates;
}

Accessing permissioned data in API.AI

When you submit a request for information, Google takes control of the conversation to ask the user for permission. After permission is granted or denied, your action is triggered again with the text of the user's response, as if the user were still in the dialog.

To handle this in API.AI:

  1. Create an intent to request the permission. In the fulfillment logic, specify which data to request from the user and send a response as described above. Make sure this intent has an outgoing context that represents the permission request cycle, like requesting_permission.

  2. Create a fallback intent with an incoming context, requesting_permission. By accepting this context, this fallback is guaranteed to be triggered after the user grants or denies permission. Enable fulfillment for this intent. Once a request reaches the webhook of this intent, the payload will contain the requested user data if permission was granted and can be read as described above. The fallback intent should not propagate the requesting_permission context in its list of outgoing contexts.

Persisting user information

Once you obtain the user's information, you may want to persist it, so you don't have to ask for it again. See the Name Psychic sample to see how to use Firebase to store user information.