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 passcode. 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

Address

alexa::devices:all:address:full: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

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

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

9

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?"

10

User

"Yes."

11

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 details about using skill connections, see Use Skill Connections to Request Tasks.

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.

The following tables describe the fields within the Connections.StartConnection directive.

Connections.StartConnection directive

Name Required? Type Description
type Yes

String

Directive type. Set this to Connections.StartConnection.

uri Yes

String

Resource that defines the task and the task version. Set this to connection://AMAZON.AskForPermissionsConsent/2.

input Yes

Object

An object that contains information about the task request. In this case, it contains a list of permission scopes to which the skill requests access. For details, see input object.

token No

String

A token that is returned to the skill as-is in the SessionResumedRequest. You can use the token to resume the skill after the task is complete.

input object

Name Required? Type Description

@type

Yes

String

Task type. Set this to AskForPermissionsConsentRequest.

@version

Yes

String

Task version. Set this to 2.

permissionScopes

Yes

Object

A list of objects that specify which permissions to request from the user, and whether the permissions are at the account level or person level. For details, see permissionScopes object.

permissionScopes object

Name Required? Type Description

permissionScope

Yes

String

The permissions to request from the user. For a list of valid permission scopes, see Overview of skill permissions. An example is alexa::profile:given_name:read.

consentLevel

Yes

String

The granularity of the user to which to ask for the consent. Valid values are ACCOUNT and PERSON:

  • ACCOUNT is the Amazon account holder to which the Alexa-enabled device is registered.
  • PERSON is the recognized speaker. For details about recognized speakers, see Add Personalization to Your Alexa Skill.
    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 (person).

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.

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

The following tables describe the fields within the request object of a SessionResumedRequest.

SessionResumedRequest request object

Name Type Description

type

String

The type of request, which is SessionResumedRequest in this case.

cause

Object

A string that the Connections.StartConnection directive included. You can use this token to resume the skill after the task request is complete.

cause object

Name Type Description

type

String

The type of SessionResumedRequest, which is ConnectionCompleted in this case.

token

String

A string that the Connections.StartConnection directive included. You can use this token to resume the skill after the task request is complete.

status

Object

A status code and message. For details, see status object.

result

Object

The outcome of the voice-forward consent workflow. For details, see result object.

status object

Name Type Description

code

String

An HTTP status code that Alexa provides to your skill after processing the task request. Possible values:

  • 200 – Alexa fulfilled the voice-forward consent workflow. Check the result.status field to see the outcome.
  • 204 – The user didn't answer the question. This error might also be represented by a code 200 with a status of NOT_ANSWERED.
  • 400 – Bad request. The request was invalid.
  • 403 – The requester was not allowed to invoke provider. This error might occur because you didn't configure voice-forward consent for the skill.
  • 404 – There are no providers available at this time.
  • 500 – Server error.

message

String

A message that describes the outcome of the request.

result object

Name Type Description

permissionScopes

String enum

A repeat of the permissionScopes object you specified in the Connections.StartConnection directive.

status

String enum

Enum string that indicates the result of the voice-forward consent. In all cases, the status code is 200. Valid values:

  • ACCEPTED: The user consented.
  • DENIED: The user explicitly declined to give consent.
  • NOT_ANSWERED: The user didn't answer the question before the eight-second Alexa timeout.
  • REDIRECT_TO_APP: Possible reasons for this outcome are that the user couldn't be recognized, the required level of authentication couldn't be achieved, the user turned off the personalization toggle, or the permission scope isn't available for voice consent. Your skill doesn't have insight into this information, so if you receive this status, your skill should throw a card to the Alexa app asking for permission to the appropriate scopes. For an example of such a permissions card, see Permissions card for requesting customer consent.

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 profiles 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

Use the developer console to test your implementation in the following way.

To test your implementation

  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.
  5. On an Echo device, launch your skill and then test it with different scenarios, such as the examples provided in Standard voice-forward consent workflows.
  6. Test different user account configurations, such as a test account with no voice profile, a voice profile without Personalize skills enabled, and so on.

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