Permissions

You can use permissions in your Action to request personal data from the user for the purposes of completing a request. For example, a food delivery Action could use a device location permission to request information about the user's location.

When you add a permission to your Action, Assistant presents a standard, consistent interface to request permission from the user to provide the information to your Action.

Note: Asking for permission to a specific piece of data doesn't guarantee the user will grant permission for that information. Configure your Action to gracefully handle the user not giving permission.

Note: The permission persists for the length of the conversational session. The Action must re-request the information from the user in subsequent sessions.

Available permissions

The following permissions can be requested by your Action:

• DEVICE_PRECISE_LOCATION: Requests the user's precise device location (coordinates and street address).
• DEVICE_COARSE_LOCATION: Requests the user's coarse device location (postal code and city).

Set up permissions

To set up permissions for your Action, you add a new slot type to the scene. You then configure the slot for the data permission you want to request.

Add permission slot type

You can grant your Action the ability to obtain user information with the actions.type.Permission slot type.

To configure this slot type, follow these steps:

1. Go to the Actions console and select or create a project.
2. Click Develop in the top menu.
3. Under Scenes, click the scene you want to add the permission flow to.
4. Under the Slot filling section of the scene, click + to add a new slot.

5. In the Select type dropdown, select the actions.type.Permission slot type.

   

6. In the Enter slot name field, give the slot a name.

7. Enable Custom slot value writeback to write the result to a session parameter.

   

Configure slot

You can now provide a context string and a list of permissions to be granted to configure the slot. The context string is the rationale for why you're requesting information from the user, and is displayed to users when they're asked to grant permission to your Action.

You can configure the context string and permissions in the Configure slot section, as shown in the following screenshot:

The following code snippet shows an example slot configuration:

{
  "@type": "type.googleapis.com/google.actions.conversation.v3.PermissionValueSpec",
  "context": "Context string",
  "permissions": ["DEVICE_PRECISE_LOCATION"]
}

The prompt displayed to users will be in the form of "$context_string, I'll just need to get your current location from Google. Is that ok?"

You can obtain the following user information using the permission codes:

Permission	Description
DEVICE_PRECISE_LOCATION	Precise device location (coordinates and street address)
DEVICE_COARSE_LOCATION	Coarse device location (postal code and city)

Get permission result

The following sections describe how to check the permission status and read the user's information if they grant permission.

Check permission status

When the user grants permission, the resulting status is written to the session parameter associated with the slot.

You can check the permission status by checking the value of session.params.<slot_name>.permissionStatus in the condition of a scene.

To check the status of the permission slot, follow these steps:

1. Go to the Actions console and click Develop in the top menu.
2. Under Scenes, click the scene containing the permission slot.
3. Under the Condition section of the scene, click + to add a new condition.

4. Enter the following condition to check for the permission status (where <slot_name> is the name of the session parameter you configured in your slot):

   scene.slots.status == "FINAL" && (session.params.<slot_name>.permissionStatus == "PERMISSION_GRANTED" || session.params.<slot_name>.permissionStatus == "ALREADY_GRANTED")
   

   

5. Under the Condition section of the scene, click + to add a new condition.

6. Enter the following condition to handle the case where the user does not consent to sharing their information:

   scene.slots.status == "FINAL"
   

   

7. Under the Condition section of the scene, click + to add a new condition.

8. Enter the following condition to handle the case where the user has already granted permission, and doesn't need to be asked again:

   "DEVICE_PRECISE_LOCATION" in user.permissions
   

   

Read user information

If the user grants permission, the user information is provided in subsequent requests.

Note: The permission persists for the length of the conversational session. The Action must re-request the information from the user in subsequent sessions.

In the snippet below, you can see device location information contained within a request to the webhook under device.currentLocation:

Request JSON

{ "handler": { "name": "handler" }, "intent": { "name": "", "params": { "deviceLoc": { "original": "", "resolved": { "@type": "type.googleapis.com/google.actions.conversation.v3.PermissionValue", "permissionStatus": "PERMISSION_GRANTED", "grantedPermissions": [ "DEVICE_PRECISE_LOCATION" ] } } }, "query": "Yes" }, "scene": { "name": "Scene", "slotFillingStatus": "FINAL", "slots": { "deviceLoc": { "mode": "REQUIRED", "status": "SLOT_UNSPECIFIED", "value": { "grantedPermissions": [ "DEVICE_PRECISE_LOCATION" ], "@type": "type.googleapis.com/google.actions.conversation.v3.PermissionValue", "permissionStatus": "PERMISSION_GRANTED" }, "updated": true } }, "next": { "name": "actions.scene.END_CONVERSATION" } }, "session": { "id": "session_id", "params": { "deviceLoc": { "grantedPermissions": [ "DEVICE_PRECISE_LOCATION" ], "permissionStatus": "PERMISSION_GRANTED", "@type": "type.googleapis.com/google.actions.conversation.v3.PermissionValue" } }, "typeOverrides": [], "languageCode": "" }, "user": { "locale": "en-US", "params": {}, "accountLinkingStatus": "ACCOUNT_LINKING_STATUS_UNSPECIFIED", "verificationStatus": "VERIFIED", "packageEntitlements": [], "permissions": [ "DEVICE_PRECISE_LOCATION" ], "lastSeenTime": "2021-02-08T20:43:47Z" }, "home": { "params": {} }, "device": { "capabilities": [ "SPEECH", "RICH_RESPONSE", "LONG_FORM_AUDIO" ], "currentLocation": { "coordinates": { "latitude": 37.422, "longitude": -122.084 }, "postalAddress": { "revision": 0, "regionCode": "US", "languageCode": "en", "postalCode": "94043", "sortingCode": "", "administrativeArea": "California", "locality": "Mountain View", "sublocality": "", "addressLines": ["1600 Amphitheatre Parkway"], "recipients": [], "organization": "" } } } }

For more information about the schema of the location type, see the Location reference.

You can access the information contained in the request from your webhook, as shown in the following snippet:

Webhook
app.handle('handler', (conv) => { let location = conv.device.currentLocation; conv.add(`Your postal code is ${location.postalCode}`); });

Use permission in prompts

You can also reference the permission in static prompts. For example, for the device location, you can use $device.currentLocation.coordinates.* and $device.currentLocation.postalAddress.*. The following code snippet shows how to reference the user's city in a prompt:

candidates:
  - first_simple:
      variants:
        - speech: >-
            There are no events scheduled tomorrow in the city of $device.currentLocation.postalAddress.locality.