Use Voice-Forward Consent in Your Alexa Skill

If your skill requires the user's information, you can enable the user to verbally consent to share that information with your skill. For example, in the following exchange, the user consents to give a skill, Ride Hailer, access to their name, current location, and mobile number.

User: Alexa, open Ride Hailer.

Alexa: Welcome to Ride Hailer. Where would you like to go?
User: The Space Needle.

Alexa: Sure. I need access to your name, current location, and mobile number so that I can find a ride for you.
Alexa: Do you give Ride Hailer permission to access your name, current location, and mobile number? You can say 'I approve' or 'no'.
User: I approve.

Alexa: Thank you. A ride to the Space Needle from your current location will cost fifteen dollars, and the driver can pick you up in ten minutes. Do you want me to book it?
User: Yes.

Alexa: Great. Your driver will arrive in ten minutes.

If the user doesn't grant permission by using their voice, they can grant permission later by using the Alexa app. Your skill should provide a fallback workflow for these cases.

Due to the type of user information requested, Alexa sometimes needs additional verification from the user, such as a PIN or a one-time password. This verification might also include sending the user to the Alexa app. Your skill doesn't need to handle these details; it just needs to check the result that Alexa returns and handle it gracefully.

Overview of skill permissions

A skill permission represents one piece of user information, such as the user's name or phone number. In programmatic terms, each permission is associated with a permission scope.

The following table shows this information about permissions:

  • The permissions that you can use with voice-forward consent.
  • The associated scope that you use in the directive to start the voice-forward consent flow.
  • The available consent level, which indicates whether the permission is available at the Amazon account level, the recognized speaker (also called person) level, or both. For example, the permission "alexa::profile:name:read" can represent the name of the Amazon account to which the Echo device is registered, or the name of the recognized speaker. For details about recognized speakers, see Add Personalization to Your Alexa Skill.
Permission Scope Consent Level

First name

alexa::profile:given_name:read

Account level and person level

Full name

alexa::profile:name:read

Account level and person level

Mobile number

alexa::profile:mobile_number:read

Account level and person level

Email

alexa::profile:email:read

Account level only

Zip code

alexa:devices:all:address:country_and_postal_code:read

Account level only

Geolocation

alexa::devices:all:geolocation:read

Account level only

Timers

alexa::alerts:timers:skill:readwrite

Account level only

Reminders

alexa::alerts:reminders:skill:readwrite

Account level only

Prerequisites

To use voice-forward consent, your skill must meet the following requirements:

  • Your skill must be a custom skill.
  • Your skill must not be a child-directed skill.
  • If you want the information of the recognized speaker (rather than the account holder, which might or might not be the person speaking to Alexa), your skill must support personalization.

Standard voice-forward consent workflows

When your skill reaches a point at which it needs user information, your skill attempts to access the user information by using the access token Alexa passed to the skill in the launch request. If the access token doesn't contain permission to access the data in question (such as the user's first name), your skill receives an error when it tries to get the data. At that point, your skill initiates the voice-forward consent process by passing control to an Amazon-owned voice consent skill by using an Alexa feature called skill connections. Alexa interacts with the user to handle the voice-forward consent process and then passes control back to your skill with a success or failure status so that your skill can handle the outcome accordingly.

The following examples show the standard workflows for voice-forward consent. The examples show the point at which your skill passes control to the Amazon-owned voice consent skill, and where the Amazon-owned skill passes control back to your skill.

These examples are for demonstration purposes only. When you implement voice-forward consent, you can alter the dialog for your skill, but Amazon controls the dialog for Alexa.

User consents to share their information

The following example shows what happens when the user agrees to share their information with the ride-hailing skill.

Step Speaker Speech or Action

1

User

"Alexa, open Ride Hailer."

2

Alexa (your skill)

"Welcome to Ride Hailer. Where would you like to go?"

3

User

"The Space Needle."

4

Alexa (your skill)

"Sure. I need access to your name, current location, and mobile number so that I can find a ride for you."

5

N/A

The skill sends a Connections.StartConnection directive to pass control to Alexa through skill connections.

6

Alexa (Amazon-owned skill)

"Do you give Ride Hailer permission to access your name, current location, and mobile number? You can say 'I approve' or 'no'."

7

User

"I approve."

8

N/A

Based on the type of user information, there might be an additional authentication flow here. For example, Alexa might ask the user for a PIN or a one-time password.

9

N/A

Alexa sends the skill a SessionResumedRequest request (with an ACCEPTED status) to pass control back to the skill.

10

Alexa (your skill)

"Thank you. A ride to the Space Needle from your current location will cost fifteen dollars, and the driver can pick you up in ten minutes. Do you want me to book it?"

11

User

"Yes."

12

Alexa (your skill)

"Great. Your driver will arrive in ten minutes."

User declines to share their information

The following example shows what happens when the user explicitly declines to share their information with the ride-hailing skill.

Step Speaker Speech or Action

1

User

"Alexa, open Ride Hailer."

2

Alexa (your skill)

"Welcome to Ride Hailer. Where would you like to go?"

3

User

"The Space Needle."

4

Alexa (your skill)

"Sure. I need access to your name, current location, and mobile number so that I can find a ride for you."

5

N/A

The skill sends a Connections.StartConnection directive to pass control to Alexa through skill connections.

6

Alexa (Amazon-owned skill)

"Do you give Ride Hailer permission to access your name, current location, and mobile number? You can say 'I approve' or 'no'."

7

User

"No."

8

N/A

Alexa sends the skill a SessionResumedRequest request (with a DENIED status) to pass control back to the skill.

9

Alexa (your skill)

(Handling the DENIED status) "Ok. To order you a car, Ride Hailer needs access to that information. Please go to the Alexa app to give Ride Hailer permission, and then open Ride Hailer again. Thank you for using Ride Hailer."

User doesn't answer the question

The following example shows what happens when the user doesn't respond to the request for consent by voice.

Step Speaker Speech or Action

1

User

"Alexa, open Ride Hailer."

2

Alexa (your skill)

"Welcome to Ride Hailer. Where would you like to go?"

3

User

"The Space Needle."

4

Alexa (your skill)

"Sure. Sure. I need access to your name, current location, and mobile number so that I can find a ride for you."

5

N/A

The skill sends a Connections.StartConnection directive to pass control to Alexa through skill connections.

6

Alexa (Amazon-owned skill)

"Do you give Ride Hailer permission to access your name, current location, and mobile number? You can say 'I approve' or 'no'."

7

User

User does not respond and Alexa times out after eight seconds.

8

N/A

Alexa sends the skill a SessionResumedRequest request to pass control back to the skill. This request might be a code 200 with a NOT_ANSWERED status, or a code 204 with message (NO CONTENT/CANCELLED) THE SKILL SESSION WAS ENDED BY THE USER).

9

Alexa (your skill)

(Handling the lack of permission) "To order you a car, Ride Hailer needs access to that information. Please go to the Alexa app to give Ride Hailer permission, and then open Ride Hailer again. Thank you for using Ride Hailer."

How to initiate the voice-forward consent flow

After the user makes a request that requires user information, have your skill pass control to Alexa by returning a Connections.StartConnection directive in the response object. Your skill code must leave the shouldEndSession flag undefined when it returns a Connections.StartConnection directive.

For descriptions of the fields within the Connections.StartConnection directive, see Connections.StartConnection directive schema.

The following example shows a Connections.StartConnection directive that your skill uses to pass control to Alexa. You put this directive in a response to a request from Alexa. For details about the format of Alexa requests and responses, see Request and Response JSON Reference. For details about using skill connections, see Use Skill Connections to Request Tasks.

How to resume control after the voice-forward consent flow

After attempting to get consent from the user, Alexa sends your skill a SessionResumedRequest that contains the result of the voice-consent attempt. For descriptions of the fields within the request object of a SessionResumedRequest, see SessionResumedRequest schema.

The following example shows a SessionResumedRequest that your skill receives from Alexa.

Steps to implement voice-forward consent in your skill

To implement voice-forward consent in your skill, take the following steps:

  1. Create a custom skill.
  2. Configure your skill.
  3. Implement voice-forward consent in your skill code.
  4. Test your implementation.
  5. Certify your skill.
  6. Check the voice-forward consent metrics.

Step 1: Create a custom skill

For details about how to create a custom skill, see Understand Custom Skills or Steps to Build a Custom Skill.

Step 2: Configure your skill

Before your skill can use voice-forward consent, you must configure your skill for the desired permissions. You must also add support for the skill connection task.

To configure your skill for voice-forward consent

  1. Sign in to the Alexa developer console and navigate to your skill.
  2. Select the Build tab.
  3. On the left, click TOOLS, and then click Permissions.
  4. If you want the user information of the recognized speaker (who might or might not be the account holder), toggle on Skills Personalization.
    This setting is required to use voice IDs in your skill.
  5. Toggle on the options for the user information you need. Examples are Customer Name > Full Name and Customer Phone Number.

Step 3: Implement voice-forward consent in your skill code

To implement voice-forward consent, your skill does the following:

For details on where these items fit into the overall workflow, Standard voice-forward consent workflows.

Step 4: Test your implementation

Take the following steps to test your voice-forward consent implementation with an Echo device.

To test your implementation

  1. To test voice-forward consent, you must first set up a voice ID in the Alexa app. If you already have a voice ID, you can skip this step.
    1. Open the Alexa app.
    2. At the bottom, select More.
    3. Select Settings, and then select Your Profile & Family.
    4. Follow the instructions on the screen to add a profile.
    5. Follow the instructions on the screen to add your voice ID.
  2. In the developer console, enable testing for your skill as follows.
    1. Sign in to the Alexa developer console.
    2. From the skill list, select your skill.
    3. At the top, click the Test tab.
    4. On the left, under the header bar, for Skill testing is enabled in, select Development.
  3. On an Echo device, open your skill, and then go through the flows that trigger your voice-forward consent integration. For examples of voice-forward consent scenarios, see Standard voice-forward consent workflows.

    If your skill uses high-risk permissions such as "Full Name," Alexa sends a one-time password to your phone.

Step 5: Certify your skill

After you build your skill and test it with your account, you can submit your skill for certification. For details about certifying a custom skill, see Certification Requirements.

Step 6: Check the voice-forward consent metrics

To view your skill's voice-forward consent metrics, go to the developer console and navigate to the Analytics dashboard. The following metrics are available for voice-forward consent:

  • Total voice consent users
  • Total voice consent events (voice consent invocations and completions)
  • Voice consent completion rate (the percentage of granted versus denied requests)
  • Voice consent exception count