# 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]
> **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]
> **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](https://console.actions.google.com) 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.

   ![](https://developers.google.com/static/assistant/conversational/images/permissions-slot-type.png)
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.

   ![](https://developers.google.com/static/assistant/conversational/images/permissions-writeback.png)

### 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:

![](https://developers.google.com/static/assistant/conversational/images/permissions-configure-slot.png)

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](https://console.actions.google.com) 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")

   ![](https://developers.google.com/static/assistant/conversational/images/permissions-check-status.png)
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"

   ![](https://developers.google.com/static/assistant/conversational/images/permissions-condition-final.png)
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

   ![](https://developers.google.com/static/assistant/conversational/images/permissions-last-condition.png)

### Read user information

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

> [!NOTE]
> **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](https://developers.google.com/assistant/conversational/df-asdk/reference/webhook/rest/Shared.Types/Location).

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.