Set Up Voice Permissions for Reminders

With voice permissions for reminders, your skill can ask the user, via voice, for this particular permission. After the skill initiates the request, Alexa prompts the user as to whether they want to grant permission to create a specific reminder. The user responds, and if the user grants this permission, the skill can then create the reminder. If the user does not grant this permission, then the skill cannot create a reminder. Your skill should provide a fallback workflow if the user does not grant permission to create a reminder.

Voice permissions for reminders make your skill more convenient to your users. The skill does not have to send a card to the Alexa app when requesting permissions for reminders, and the user does not have to open the Alexa app to grant permissions to the skill.

Standard voice permission workflows

A skill initiates the initial prompt asking if the user wants to set a reminder. You can determine when your skill should ask the user if they want to set a reminder.

User grants permission by voice to reminders

In this example, the skill is linked to a third-party sports news app called Sports News Example. Some of the skill's output responses are controlled by the skill, and some by Alexa.

User: Alexa, when do the Oranges play next?

Alexa (as determined by skill): The Oranges play the Apples next Thursday at 7pm. Would you like to set a reminder?

User: Yes.

Alexa (as determined by Alexa): Do you give Sports New permission to update your reminders? You can say I approve or no.

User: I approve.

Alexa (as determined by skill): I'll remind you at 7pm next Thursday to watch the Oranges versus Apples.

In this example, the skill first answers the user's question. The skill controls the content of the second sentence, "Sports News Example can give you reminders when your favorite teams play."

Alexa controls the content of the third sentence asking for permission, and as the skill developer, you cannot change the wording.

The last two sentences are part of the same response, but the second-to-last is controlled by Alexa, and the last sentence is controlled by the skill.

When the user grants permission, the skill receives a request that indicates that the permission was granted. Alexa sets the reminder. Your skill should inform the user that the reminder is set, and the skill continues its session.

User denies permission for reminders after initial agreement

In this case, the user denies permission to set a reminder, after initially agreeing to do so. Alexa acknowledges the refusal, and the skill continues its session. Note that the user here first says "Yes," before later saying "No." If the user said "No" initially, the voice permissions workflow should not start, and the skill would continue its session as before.

You cannot control Alexa's interaction with the user in respect to this permissions workflow, other than when you send out the first prompt.

User: Alexa, when do the Oranges play next?

Alexa (as determined by skill): The Oranges play the Apples next Thursday at 7pm. Would you like to set a reminder?

User: Yes.

Alexa (as determined by Alexa): Do you give Sports News permission to update your reminders? You can say I approve or no.

User: No.

User response is unintelligible

Suppose the user, when Alexa asks for permission to set a reminder, has an unintelligible response. Alexa re-prompts the user with a rephrased question. If the user grants or denies permission after the re-prompt, the corresponding workflow then follows from that point.

User: Alexa, when do the Oranges play next?

Alexa (as determined by skill): The Oranges play the Apples next Thursday at 7pm. Would you like to set a reminder?

User: Yes.

Alexa (as determined by Alexa): Do you give Sports News permission to update your reminders? You can say I approve or no.

User: <Unintelligible>

Alexa (as determined by Alexa): Do you give Sports News permission to update your reminders? You can say I approve or no.

Standard prompts

A skill kicks off the voice permission for reminders workflow, and the skill controls the initial prompt to the user. Alexa controls the next prompts in the voice permissions workflow, which provides a consistent experience for users across skills. For clarity and easy reference, each prompt has been given a tag. Your skill should follow the AcceptConsentReminders prompt with a restatement of the reminder, its date and time, and its purpose, and your skill controls this portion of the response.

AskForConsentReminders: Alexa (as determined by Alexa): Do you give [skillName] permission to update your reminders? You can say I approve or no.

AskForConsentRetryReminders: Alexa (as determined by Alexa): Do you give [skillName] permission to update your reminders? You can say I approve or no.

Send a Connections.SendRequest directive

When the user responds affirmatively when the skill asks to set a reminder, your skill service code can then send a Connections.SendRequest directive, as shown here. The permissionScope value is for the reminders scope: alexa::alerts:reminders:skill:readwrite.

The token field in this directive is not used by Alexa, but the token value is returned in the resulting Connections.Response request. You can provide this token in a format that makes sense for the skill, and you can use an empty string if you do not need it.

The consentLevel parameter is 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.
{
   "type": "Connections.SendRequest",
   "name": "AskFor",
   "payload": {
      "@type": "AskForPermissionsConsentRequest",
      "@version": "2",
      "permissionScopes": [
        {
          "permissionScope": "alexa::alerts:reminders:skill:readwrite",
          "consentLevel": "ACCOUNT"
        }
      ]
   },
   "token": ""
}

After receiving this directive, Alexa asks the user to grant permission for the specified reminders permission scope, which results in a Connections.Response request, as shown. The body.status value is one of:

  • ACCEPTED – the user has granted the permissions, either in response to the last request or previously.
  • DENIED – the user has refused the permissions.
  • NOT_ANSWERED – the user did not answer the request for permissions, or the response was not understood. In this case, Alexa will re-prompt the user.
{
   "type": "Connections.Response",
   "requestId": "string",
   "timestamp": "string",
   "locale": "string",
   "name": "AskFor",
   "status": {
      "code": "string",
      "message": "string"
   },
   "token": "string",
   "payload": {
      "permissionScopes" : [
       {
         "permissionScope" : "alexa::alerts:reminders:skill:readwrite",
         "consentLevel": "ACCOUNT"
       },
      "status" : <status enum> // ACCEPTED, DENIED, or NOT_ANSWERED
      ]
   }
}

As you can see in the examples, Alexa has a set of standard prompts that you cannot change when you develop a skill. You do not have to code these prompts, as they are included with the standard voice permissions workflow.

Code example for a voice permissions request

The following example shows how you can add code to an AWS Lambda function to send the Connections.SendRequest directive for a voice permissions request. You can use the token field to keep track of state. Any value that you provide in the token field appears in the user's requests to Alexa. For example, you could use the token field to store the userId value. You can also set the token to be an empty string.

Copied to clipboard.

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

return handlerInput.responseBuilder
  .addDirective({
		type: "Connections.SendRequest",
		name: "AskFor",
		payload: {
			"@type": "AskForPermissionsConsentRequest",
			"@version": "2",
			"permissionScopes": [
			  {
			    "permissionScope": "alexa::alerts:reminders:skill:readwrite",
			    "consentLevel": "ACCOUNT"
			  } 
			]
		},
		token: "<token string>"
	})
  .getResponse();

Copied to clipboard.

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

this.handler.response = {
	'version': '1.0',
	'response': {
		'directives': [{
			'type': 'Connections.SendRequest',
			'name': 'AskFor',
			'payload': {
			   '@type': 'AskForPermissionsConsentRequest',
			   '@version': '2',
			   'permissionScopes': [
			    {
			      'permissionScope': 'alexa::alerts:reminders:skill:readwrite',
			      'consentLevel': 'ACCOUNT'
			    } 
			   ]
			},
			'token': '<string>'
		}],
		'shouldEndSession': true
	}
};
this.emit(':responseReady');

Copied to clipboard.

JSON syntax for a Connections.SendRequest directive for a voice request for permissions. In this case, the name is AskFor.

{
  "directives": [
    {
      "type": "Connections.SendRequest",
      "name": "AskFor",
      "payload": {
        "@type": "AskForPermissionsConsentRequest",
        "@version": "2",
        "permissionScopes": [
          {
            "permissionScope": "alexa::alerts:reminders:skill:readwrite",
            "consentLevel": "ACCOUNT" 
          } 
        ]
      },
      "token": "<string>"
    }
  ]
}

Best practices for user experience of reminders

See Alexa Reminders Guidelines for Usage.

Was this page helpful?

Last updated: May 22, 2024