Voice-Forward Consent API Reference

If your Alexa skill requires the user's information, you can enable the user to verbally consent to share that information with your skill. This feature is called voice-forward consent. To support voice-forward consent, your skill uses skill connections. Skill connections is an Alexa feature that enables a skill to call another skill or service to perform a specific task.

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

For details on where these items fit into voice-forward consent workflows, Standard voice-forward consent workflows. For details about using skill connections, see Use Skill Connections to Request Tasks.

The following sections describe the skill connection fields specific to the voice-forward consent flow.

Connections.StartConnection directive schema

The following tables describe the fields within the 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).

SessionResumedRequest schema

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 tables describe the fields within the request object of a SessionResumedRequest.

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.
Was this page helpful?

Last updated: Mar 31, 2022