Amazon Alexa

Integration published by Jovo | 13,513 downloads

Build apps for Amazon's Alexa assistant platform

User Data and Permissions

Learn more about how to get access to Alexa Skill user information, permissions, and other data.

Location

You can use the user's address data to provide location specific features, but you have to obtain their permission first.

First add it to your skill's permission. You can do that in your project.js file:

After that you have to send the user a permission card for them to grant you access to the data:

Get the country and postal code:

Get the address:

Learn more in the official documentation by Amazon.

Geolocation

The geolocation allows you to access your user's real time location, which the system gets from the alexa enabled mobile device, e.g. their phone.

Geolocation Permission

To access the user's geolocation, you have to first add it to your skill's permission. You can do that in your project.js file:

After you've added it to your skill's permissions, your users can grant or deny you permission to access their geolocation data at any time. You can check the current status the following ways:

If the permission was denied you can send your user a permission card to ask them to turn it back on:

Geolocation Interface

After your user has given their consent the incoming requests may contain a Geolocation object, as it depends on the device and its settings.

To see whether a device supports the geolocation interface or not, you can use the following method:

Geolocation Object

The incoming Geolocation object has the following structure:

Name Description Value Optional
locationServices Contains information whether location sharing is turned on object Yes
locationServices.access Specifies whether location sharing is enabled or disabled enum - either ENABLED or DISABLED No
locationServices.status Specifies whether location sharing is running or not enum - either RUNNING or STOPPED No
timestamp Timestamp specifying when the location data was retrieved string - ISO 8601 No
coordinate Contains information about the coordinates object No
coordinate.latitudeInDegrees Specifies the latitude in degrees number - [-90.0, 90.0] No
coordinate.longitudeInDegrees Specifies the longitude in degrees number - [-180.0, 180] No
coordinate.accuracyInMeters Specifies the uncertainty in the latitude and longitude in meters number - [0, MAX_INTEGER] No
altitude Contains information about the altitude object Yes
altitude.altitudeInMeters Specifies the altitude in meters number - [-6350, 18000] Yes
altitude.accuracyInMeters The uncertainty in the altitude in meters number - [0, MAX_INTEGER] Yes
heading Contains information about the direction the device is heading object Yes
heading.directionInDegrees The degrees from true north number - (0.0, 360.0] Yes
heading.accuracyInDegrees The accuracy of the direction number - [0, MAX_INTEGER] Yes
speed Contains information about the speed at which the device is moving object Yes
speed.speedInMetersPerSecond The meters per second within GPS limits number - [0, 1900] Yes, except for automotive
speed.accuracyInMetersPerSecond The accuracy of the speed number - [0, MAX_INTEGER] Yes

Each of these values can be undefined, but either the locationServices or coordinate object will be defined at all times.

You can access them the following way:

Contact Information

You can use contact information (name, email address, mobile number) to provide more personalized experiences for the user. To get access to the contact information, ask for permissions first. You can do this by using the contact permission card.

Get the full name:

Get the given name:

Get the email address:

Get the mobile number:

Lists

Amazon Alexa offers the ability to its users to add items to a shopping list and a to-do list. Custom Skills can get the permission to access these lists for read and write operations. For a general overview, read the official list reference by Amazon.

Learn more in the following sections:

List Permissions

Users need to grant your Alexa Skill permission for read and/or write access to their lists.

In the Amazon Developer Portal, you can do this by checking the following permissions:

Alexa List Permissions

The same result is achieved by adding the following to the manifest in your skill.json via the project.js file:

If your users haven't granted your Skill the permission to access lists yet, you can use a List Permission Card to ask for the required permission.

This is mostly used after the error code 'NO_USER_PERMISSION' is returned. Here is an example:

You can ask for both read and write access with the Permission Card:

This is what it looks like in the Alexa app:

Alexa List Permission Card in the Alexa App

Users can then update the permissions in the Skill's settings:

Update List Permissions in the Alexa App

Shopping List

Get the user's shopping list:

Add an item to the shopping list:

Update the shopping list:

Delete an item:

To-Do List

Get the user's to-do list:

Add an item to the to-do list:

Update the to-do list:

Delete an item from the to-do list:

Reminders

To create a reminder, send a JSON object to Amazon's API endpoint. You can find out what that these JSON objects look like here

Add Reminder

To add a reminder you use the setReminder() method, which takes in the JSON object as a parameter:

As a response to the API call you will receive an object containing the following data:

Name Description Value
alertToken Unique ID of the reminder String
createdTime Created time of the reminder (ISO 8601) String
updatedTime Last updated time of the reminder (ISO 8601) String
status Either ON or COMPLETED Enum
version Version of the reminder String
href URI to retrieve the alert String

Update Reminder

To update a reminder you need the JSON object to update with as well as the alertToken to define which one you want to update and the updateReminder() method:

You will receive the same response you receive after adding a new reminder.

Delete Reminder

To delete an active reminder you need the deleteReminder() method which takes in the alertToken as a parameter:

Get Reminder

You can also send out a request to get a reminder using its alertToken:

There is also the possibility to get all your reminders at once:

Settings

The Alexa Settings API allows you to access the time zone, distance measurement unit and temperature measurement unit of your user.

Timezone

Here is an example how you can get the user's timezone in a GetTimezoneIntent:

You can use this information to get the local time of the user. For example, you can use the moment-timezone package:

Distance Measurement Unit

Here is an example how you can get the user's distance measurement unit in a GetDistanceUnitIntent:

Temperature Measurement Unit

Here is an example how you can get the user's temperature measurement unit in a GetDistanceUnitIntent:

Skill Events

Skill Events can be used to notify you if a certain event occurs, which range from the customer disabling your Skill to them linking their account using the Alexa app. The notification comes in form of a request to your Skill.

Official Documentation from Amazon.

Skill Event Requirements

To enable the Skill Events you have to make changes to the skill.json file (/platforms/alexaSkill/), which you can do by updating the project.js file in your Jovo project.

Add the following to your alexaSkill object in the project.js file:

Events

As described earlier, your Skill gets notified in form of request. To map that request to one of your handlers you have to add the following state:

Inside that state you can define the intents, which will be mapped to one of the events. Here's an example:

Skill Enabled

This Skill Event gets triggered the moment your Skill gets enabled by the user.

Enable that event by adding the following to your subscription array inside your events object in your project.js:

And adding the AlexaSkillEvent.SkillEnabled inside your ON_EVENT state:

Official Documentation by Amazon.

Skill Disabled

This Skill Event gets triggered the moment your Skill gets disabled by the user. If you are using Database Integrations to store user specific data, then you should delete the user data. Otherwise you will have orphaned records in your database. The userId will not be re-used if the user re-enables the skill later: they will get a new userId.

Enable that event by adding the following to your subscription array inside your events object in your project.js:

And adding the AlexaSkillEvent.SkillDisabled inside your ON_EVENT state:

Official Documentation by Amazon.

Account Linked

This Skill Event gets triggered, if the user links their account using the companion app/website. The incoming request will also contain the access token, which you can access using this.getAccessToken().

Enable that event by adding the following to your subscription array inside your events object in your project.js:

And adding the AlexaSkillEvent.SkillAccountLinked inside your ON_EVENT state:

Official Documentation by Amazon.

Skill Permission Accepted

This Skill Event gets triggered, if your user grants permissions for the first time or if they grant them after they were revoked. The request will include the most recently accepted permissions. You can access the body of the request using the this.$alexaSkill.getSkillEventBody() method, which will contain an array with the permissions. Check out the sample requests in the official documentation to get a feeling for the JSON structure.

Enable that event by adding the following to your subscription array inside your events object in your project.js:

And adding the AlexaSkillEvent.SkillPermissionAccepted inside your ON_EVENT state:

Official Documentation by Amazon.

Skill Permission Changed

This Skill Event gets triggered, if your user grants your Skill additional permission or revokes existing ones. The request will include the most recently accepted permissions. You can access the body of the request using the this.$alexaSkill.getSkillEventBody() method, which will contain an array with the permissions. Check out the sample requests in the official documentation to get a feeling for the JSON structure.

Enable that event by adding the following to your subscription array inside your events object in your project.js:

And adding the AlexaSkillEvent.SkillPermissionChanged inside your ON_EVENT state:

Official Documentation by Amazon.

Proactive Subscription Changed

Find a detailed description of the Proactive Subscription Changed event here.

Amazon Alexa Changelog

Jovo Marketplace | GitHub | npm

Current version might be higher than the latest changes displayed below because of updates of dependencies.

2021-10-27 [3.5.5]

2021-02-22 [3.5]

  • #901 Move setResponse from response to after.response middleware (@aswetlow)
  • #901 Route Alexa.Presentation.APLA.RuntimeError requests to ON_ERROR (@aswetlow)

2020-11-10 [3.2.1]

2020-08-21 [3.0.30]

3.0.17 (2020-05-13)

🐛 Bug fix

  • jovo-platform-alexa Fix http status in ReminderAPI

Committers: 1

3.0.13 (2020-05-04)

💅 Enhancements

  • jovo-platform-alexa #734 Add getPermissionIsCardThrown (@rmtuckerphx)
  • jovo-platform-alexa Add types for skill event body objects

Committers: 2

3.0.11 (2020-04-06)

  • Updated Typescript to 3.8.x
  • Updated Prettier to 2.x

Committers: 2

2.x

Find the 2.x changelog here.

Join Our Newsletter

Be the first to get our free tutorials, courses, and other resources for voice app developers.