Sending notifications from applications in your mobile devices is a common feature nowadays but what if you can send notifications from your skills to Alexa devices. With the release of proactive events now you can send timely and relevant information to your users.
We have provided pre-defined set of schemas that best describe your events and send proactive events information that conforms to a schema via the Skill Management API (SMAPI) as part of a skill manifest. Each schema has a predefined template that represents the text read back to the end customers by Alexa.
To make sure Alexa notifications provide relevant updates, customers have the ability to enable notifications for each skill, and they can opt out at any time using the Alexa app.
When an Alexa notification is sent, customers see a yellow light on devices without screens and an on-screen banner on devices with screens that indicate that they have new notifications. Customers can ask Alexa to read their notifications when they want to hear them.
How to add:
To add proactive events in your Alexa skill you need to follow below details:
- Select schemas to represent the events you wanted to send to users.
- Update skill manifest with Proactive Events capabilities.
- In the Notification settings page in the Alexa app, enable notification for your skill.
- Send a proactive event and ensure you receive the notification on your Alexa-enabled device.
To call proactive event API you need to authenticate with Alexa as follows:
HTTP header:
POST /auth/O2/token HTTP/1.1 Host: api.amazon.com Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Request body syntax:
grant_type=client_credentials&client_id=(clientID)&client_secret=(clientSecret)&scope=alexa::proactive_events
function getTokenOptions(postLength){
// const TokenPostData = getTokenPostData();
return {
hostname: 'api.amazon.com',
port: 443,
path: '/auth/O2/token',
method: 'POST',
headers: {
'Content-Type': 'application/x-www-form-urlencoded',
'Content-Length': postLength // TokenPostData.length
}
}
}
function getTokenPostData() {
return 'grant_type=client_credentials&client_id=' + clientID + '&client_secret=' + clientSecret
+ '&scope=alexa::proactive_events';
}
function getToken() {
return new Promise(resolve => {
const TokenPostData = getTokenPostData();
const req = https.request(getTokenOptions(TokenPostData.length), (res) => {
res.setEncoding('utf8');
let returnData = '';
res.on('data', (chunk) => { returnData += chunk; });
res.on('end', () => {
const tokenRequestId = res.headers['x-amzn-requestid'];
// console.log(`Token requestId: ${tokenRequestId}`);
resolve(JSON.parse(returnData).access_token);
});
});
req.write(TokenPostData);
req.end();
});
}
To locate ClientId and ClientSecret in the developer console, select the Build tab, scroll down to the Permissions section, and get these values from Alexa Skill Messaging at the bottom right.
Developer needs to select schemas to represent the events they want to notify their customers about, and send these events to the ProactiveEvents API. Customers subscribed to receive notifications about these events from the skill will then receive an Alexa notification. Schemas are pre-defined by the Alexa Skills Kit.
Your skill can use different schemas to represent different themes about which you want to engage their customers. Your skill cannot implement multiple instances of the same schema.
Below schema is used to send weather alert to all customers who enabled this skill and subscribed for notification:
function getWeatherEvent() {
let timestamp = new Date();
let expiryTime = new Date();
expiryTime.setMinutes(expiryTime.getHours() + 24);
let referenceId = "SampleReferenceId" + new Date().getTime(); // cross reference to records in your existing systems
const eventJson = {
"timestamp": timestamp.toISOString(),
"referenceId": referenceId,
"expiryTime": expiryTime.toISOString(),
"event":{
"name":"AMAZON.WeatherAlert.Activated",
"payload":{
"alert":{
"source": "localizedattribute:source",
"alertType": "HURRICANE"
}
}
},
"localizedattribute":[
{
"locale": "en-US",
"source": "Weather Channel"
},
{
"locale": "en-GB",
"source": "Britain Met Office"
},
{
"locale": "fr-FR",
"source": "Canal météo"
}
],
"relevantAudience":{
"type":"Multicast",
"payload":{}
}
};
return eventJson;
}
In your skill manifest you must define the event your skill will provide to your customer. Publications Object has been added to the events section of the skill manifest. When specifying you must include “alexa::devices:all:notifications:write” as a permission.
"permissions": [
{
"name": "alexa::devices:all:notifications:write"
}
],
"events": {
"publications": [
{
"eventName": "AMAZON.WeatherAlert.Activated"
},
{
"eventName": "AMAZON.MessageAlert.Activated"
}
],
"endpoint": {
"uri": "Your-ARN-Here"
},
"subscriptions": [
{
"eventName": "SKILL_PROACTIVE_SUBSCRIPTION_CHANGED"
}
],
"regions": {
"NA": {
"endpoint": {
"uri": "Your-ARN-Here"
}
}
}
}
While your skill is in the development stage, you can test it by sending proactive events using the following development endpoint. This endpoint is always available to you, and you can use it without concerns of sending requests to your live customers. Use the Notifications settings in the Alexa app to subscribe to receive test notifications.
- https://api.amazonalexa.com/v1/proactiveEvents/stages/development (North America)
- https://api.eu.amazonalexa.com/v1/proactiveEvents/stages/development (Europe)
- https://api.fe.amazonalexa.com/v1/proactiveEvents/stages/development (Far East)
To send events to your live customers, send proactive events to the live endpoint. This endpoint is only available to you once your skill is certified, and it only accepts events that your skill has been certified to send to Alexa. Select the appropriate endpoint for your region.
- https://api.amazonalexa.com/v1/proactiveEvents/ (North America)
- https://api.eu.amazonalexa.com/v1/proactiveEvents/ (Europe)
- https://api.fe.amazonalexa.com/v1/proactiveEvents/ (Far East)
function getProactiveOptions(token, postLength){
return {
hostname: 'api.amazonalexa.com', // api.eu.amazonalexa.com (Europe) api.fe.amazonalexa.com (Far East)
port: 443,
path: '/v1/proactiveEvents/' + (mode && mode === 'prod' ? '' : 'stages/development'), // mode: global var
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Content-Length': postLength,
'Authorization' : 'Bearer ' + token
}
};
}
function sendEvent(token) {
return new Promise(resolve => {
const ProactivePostData = JSON.stringify(getWeatherEvent());
const ProactiveOptions = getProactiveOptions(token, ProactivePostData.length);
const req = https.request(ProactiveOptions, (res) => {
res.setEncoding('utf8');
if ([200, 202].includes(res.statusCode)) {
console.log('successfully sent event');
} else {
console.log(`Error https response: ${res.statusCode}`);
console.log(`requestId: ${res.headers['x-amzn-requestid']}`);
if ([403].includes(res.statusCode)) {
resolve(`error ${res.statusCode}`);
}
}
let returnData;
res.on('data', (chunk) => { returnData += chunk; });
res.on('end', () => {
const requestId = res.headers['x-amzn-requestid'];
resolve("sent event");
});
});
req.write(ProactivePostData);
req.end();
});
}
ProactiveEvents API is available in all locales supported by Alexa. Review our technical documentation to learn more. We have also provided sample code for proactive events on our official GitHub repository. If you need any help or have any feedback please reach out to us via contact-us . We are also present on Alexa Developer community forum.
