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:
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:
Users can then update the permissions in the Skill's settings:
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.