Use Voice-Forward Consent in Your Alexa Skill

Note: Sign in to the developer console to build or publish your 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
Prerequisites
Standard voice-forward consent workflows
How to initiate the voice-forward consent flow
How to resume control after the voice-forward consent flow
Steps to implement voice-forward consent in your skill
Related topics

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.

Raw JSON
Node.js SDK v2

Copied to clipboard.

{
   "type": "Connections.StartConnection",
   "uri": "connection://AMAZON.AskForPermissionsConsent/2",
   "input": {
      "@type": "AskForPermissionsConsentRequest",
      "@version": "2",
      "permissionScopes": [
        {
           "permissionScope": "<permission scope>", // Such as alexa::profile:name:read
           "consentLevel": "ACCOUNT" // Or PERSON
        },
        {
           "permissionScope": "<another permission scope>", // Such as alexa::devices:all:geolocation:read
           "consentLevel": "ACCOUNT" // Or PERSON
        },
        ...
      ]
   },
   "token": "example-token"
}                    

Copied to clipboard.

This code example uses the Alexa Skills Kit SDK for Node.js (v2).

return handlerInput.responseBuilder
   .addDirective({
      'type': 'Connections.StartConnection',
      'uri': 'connection://AMAZON.AskForPermissionsConsent/2',
      'input': {
         '@type': 'AskForPermissionsConsentRequest',
         '@version': '2',
         'permissionScopes': [
           {
              'permissionScope': '<permission scope>', // Such as alexa::profile:name:read
              'consentLevel': 'ACCOUNT' // Or PERSON
           },
           {
              'permissionScope': '<another permission scope>', // Such as alexa::devices:all:geolocation:read
              'consentLevel': 'ACCOUNT' // Or PERSON
           },
           ...
         ]
      },
      'token': 'example-token'
   })
   .getResponse();

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.

Raw JSON
Node.js SDK v2

Copied to clipboard.

{
   "context": {
      ....
   },
   "request": {
      "type": "SessionResumedRequest",
      ....
      "cause": {
         "type": "ConnectionCompleted",
         "token": "some connection token data",
         "status": {
            "code": "200",
            "message": "Ok."
         },
         "result": {
            "permissionScopes" : [
             {
                "permissionScope" : "<external permission scope name>",
                "consentLevel": "<consent_level enum>"
             }
            ],
            "status" : <permission status enum>
         }
      }
   }
}

Copied to clipboard.

This code example uses the Alexa Skills Kit SDK for Node.js (v2).

/**
 * Handler to handle SessionResumedRequest.
 */
const SessionResumedRequestHandler = {
    canHandle(handlerInput) {
        const request = handlerInput.requestEnvelope.request;
        return request.type === 'SessionResumedRequest';
    },
    handle(handlerInput) {
        const connectionsStatus = handlerInput.requestEnvelope.request.cause.status;
        const connectionsCode = connectionsStatus.code;
        const person = handlerInput.requestEnvelope.context.System.person;

        // First, check to see if the skill connection attempt completed successfully.
        // This does not tell us if the task was successful or not; we will check that next.
        if ((connectionsCode != 200) && (connectionsCode != 204)) {
            return handlerInput.responseBuilder
                .speak("Sorry, something went wrong.")
                .getResponse();
        }
        // Now check to see if the user consented to share their information.
        const voiceConsentStatus = handlerInput.requestEnvelope.request.cause.result.status;

        if (voiceConsentStatus == 'ACCEPTED') {
           performBusinessLogic(...);
           return handlerInput.responseBuilder
              .speak("Thank you.")
              .getResponse();
        }
        else {
           return handlerInput.responseBuilder
              .speak("To fulfill your request, I need access to that information. Please see the Alexa app to grant permission.")
              .withAskForPermissionsConsentCard([
                 "<permissionScope>",
                  "<another permissionScope>",
                  ...
               ])
              .getResponse();
        }

};

Steps to implement voice-forward consent in your skill

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

Create a custom skill.
Configure your skill.
Implement voice-forward consent in your skill code.
Test your implementation.
Certify your skill.
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

Sign in to the Alexa developer console and navigate to your skill.
Select the Build tab.
On the left, click TOOLS, and then click Permissions.
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.
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:

Passes control to the Amazon-owned voice consent skill at the point at which the user information is needed. For details, see How to initiate the voice-forward consent flow.
Receives control from the Amazon-owned voice consent skill, and handles the outcome accordingly. For details, see How to resume control after the voice-forward consent flow.

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.

Note: The Alexa app and Echo device must be registered to the same Amazon account as the developer account you use to create skills.

To test your implementation

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.
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.
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.
Note: As with any user, if you answer Alexa's permissions question with "I approve," Alexa saves the permissions and you aren't asked again.

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 Certify and Publish Your Skill.

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

Was this page helpful?

Provide feedback

Last updated: May 01, 2024

Use Voice-Forward Consent in Your Alexa Skill

Overview of skill permissions

Prerequisites

Standard voice-forward consent workflows

User consents to share their information

User declines to share their information

User doesn't answer the question

How to initiate the voice-forward consent flow

How to resume control after the voice-forward consent flow

Steps to implement voice-forward consent in your skill

Step 1: Create a custom skill

Step 2: Configure your skill

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

Step 4: Test your implementation

Step 5: Certify your skill

Step 6: Check the voice-forward consent metrics

Related topics

Was this page helpful?