Alexa Proactive Notification Java Client Sender

This article aims at simplifying sending proactive events to an Alexa Skill from an external Java process.

Based on the video, From Zero to Hero, Part 13: Proactive Events Notifications by German Viscuso, and the Github project by Luca Rosellini  written in NodeJS. I have created a Java client so that it is easy to send notifications from any Java/Kotlin-based backend or, for example, from any Android device.

This code performs the following operations:

1. Obtain an authentication token from Alexa by using the skill's client_id and client_secret. You can obtain these in the Build Tab — Permissions section of your skill in the Alexa developer console.
2. Use the authentication token obtained in the previous step to broadcast notifications to those users of the skill that granted permissions to notifications in the Alexa app. It sends events following the AMAZON.MessageAlert.Activated schema.

Adding Proactive Events to Your Skill

Remember that if you want to send proactive events to your Skill, you need to modify the Skill's manifest (skill.json) to add notification permissions to the Skill and declare the schema(s) of the proactive events your Skill is allowed to send. Using SMAPI, you need to:

• Add the permissions object to the skill's manifest property (skill.json):

xxxxxxxxxx

"permissions": [

    {

        "name": "alexa::devices:all:notifications:write"

    }

]

• Add the events object to the skill's manifest property:

xxxxxxxxxx

"events": {

  "publications": [

    {

      "eventName": "AMAZON.MessageAlert.Activated"

    }

  ],

  "endpoint": {

    "uri": "** TODO: REPLACE WITH YOUR Lambda ARN after created **"

  },

  "subscriptions": [

    {

      "eventName": "SKILL_PROACTIVE_SUBSCRIPTION_CHANGED"

    }

  ]

}

• Redeploy your skill by running:

xxxxxxxxxx

ask deploy -t skill

If you want to declare that the Skill accepts more than one schema, just add them into events.publications above and remember to change the template in your Event class from package com.xavidop.alexa.model.event.

The process is more thoroughly described in the official Alexa Proactive Events API documentation.

You can find a working example on how to configure your Skill for Proactive Events in the official Alexa Github repository: https://github.com/alexa/alexa-cookbook/tree/master/feature-demos/skill-demo-proactive-events.

Prerequisites

1. You need Java >= 1.8 to run the code and Maven to download the required dependencies.
2. How to install these two tools goes beyond the scope of this document.

Install

To download project dependencies simply add this dependency to your pom.xml file:

xxxxxxxxxx

<dependency>

  <groupId>com.xavidop.alexa</groupId>

  <artifactId>alexa-proactive-event-sender</artifactId>

  <version>LATEST</version>

</dependency>

How to Use It

After adding the dependency, you can use the client, as shown below:

xxxxxxxxxx

String clientId = "YOUR-CLIENT";

String secretId = "YOUR-SECRET";

AlexaProactiveEventSenderClient client = new     AlexaProactiveEventSenderClient(clientId, secretId);

ProactiveEvent event = new ProactiveEvent();

event.getEvent().getPayload().getMessageGroup().getCreator().setName("Test");

URLRegion urlRegion = new URLRegion();

urlRegion.setRegion(Region.NA);

urlRegion.setEnvironment(Environment.DEV);

client.sendProactiveEvent(event, urlRegion);

• Environment: whether the target events will be sent to the live or development endpoints. Allowed values are dev and pro.
• Region: identifies the region of the Alexa endpoint to use to send proactive events. Allowed values are EU (Europe), NA (North America), and FE (Far East). Remember: if your users are located in NA, and you are sending events trough the EU endpoint, users located in NA won't receive any notifications.

These are the values by default of an event when you create it:

xxxxxxxxxx

{

        "timestamp": "",

        "referenceId": "UUID-AUTOGENERATED",

        "expiryTime": "",

        "event": {

          "name": "AMAZON.MessageAlert.Activated",

          "payload": {

            "state": {

              "status": "UNREAD",

              "freshness": "NEW"

            },

            "messageGroup": {

              "urgency": "URGENT",

              "creator": {

                "name": ""

              },

              "count": 1

            }

          }

        },

        "relevantAudience": {

            "type": "Multicast",

            "payload": {}

        }

    }

That's all!

You can find all the releases and source code in my GitHub.

Happy coding!