Search code examples
aws-lambdaalexa-skills-kit

Implementing Proactive Events in Alexa

Hi I am having a difficult time enabling proactive events in my Alexa Skill. Here is what I have already done and is working perfectly :

My skill is active in development phase and I am able to discover my smart devices through it, switch on/off using the skill. I am using Google OAuth2 in account linking for my Alexa Skill.

To enable the proactive events, I went to Alexa Developer Console > Build > Permissions > Enabled 'Send Alexa Events'

Then I used Alexa CLI and added this to my skill.json manifest :

 "permissions": [
      {
        "name": "alexa::async_event:write"
      },
      {
        "name": "alexa::devices:all:notifications:write"
      }

I have also implemented the event handler in my lambda function and I can see a Alexa.Authorization / Alexa.AcceptGrant request coming into my lambda function, here is how I am handling the directive in my Lambda function :

//AUTHORIZATION ACCEPT GRANT
async function handleAcceptGrant(request, context) {
        console.log("REQUEST : ", request);
      try {
   
      // Build the response
      const response = {
        event: {
          header: {
            namespace: AUTHORIZATION,
            name: AcceptGrant,
            messageId: createMessageId(),
            payloadVersion: '3'
          },
          payload: {}
        }, 
 
      }
    console.log(response);
    return response;
        // If the directive is not Alexa.Authorization, return an error response
    return createErrorResponse('INVALID_DIRECTIVE', 'This skill only supports Alexa.Authorization directives.');
   }catch (error) {
    console.error('Error handling directive:', error);
    return createErrorResponse('INTERNAL_ERROR', 'An internal error occurred while handling the directive.');
  }

Response, my lambda function is sending :

 {
  event: {
    header: {
      namespace: 'Alexa.Authorization',
      name: 'AcceptGrant',
      messageId: 'e5c70465-c805-4b49-a3ca-33bee98b9fb3',
      payloadVersion: '3'
    },
    payload: {}
  }
}

However, since I made these changes, I am unable to link my account in the Alexa App with my Skill. I also tried to make a post call in Postman to https://api.amazon.com/auth/o2/token with the following fields : grant_type, client_id, client_secret and scope. Where scope="alexa::proactive_events". The response I get from the Amazon server is 'Invalid Scope'.

I am not sure how to proceed and feel lost. Can anyone please help me?

Solution

  • The naming conventions and terminology here can get a little muddled so I totally understand where you're coming from. Let's start by taking a step back and describing the features associated with the two permissions you've listed.

    Alexa Event Gateway

    • Permission Name In skill.json Manifest: alexa::async_event:write
    • Skill Type Supported: Smart Home Skills Only

    When creating a smart home skill, toggling the "Send Alexa Events" permission switch adds the alexa::async_event:write permission to your skill's manifest. This permission allows you to proactively send a ChangeReport, an AddOrUpdateReport or DeleteReport event to the Alexa Event Gateway.

    In this way, you can tell Alexa when a customer has added a new device to their device cloud, removed a device, or interacted with a device, even when those interactions happened without the customer interacting directly with an Alexa device.

    For example, if I have a customer with a contact sensor attached to a door, and they physically open the door, I can send a ChangeReport to the Alexa Event Gateway reporting that the detectionState property changed to DETECTED (open) as result of a PHYSICAL_INTERACTION. Proactively reporting these changes in device properties has multiple benefits, a big one that your customers can create routines in their Alexa apps using these changes in device state as triggers.

    Proactive Events

    • Permission Name In skill.json Manifest: alexa::devices:all:notifications:write
    • Skill Type Supported: Custom Skills Only

    When creating a custom skill, you may optionally choose to enable "Proactive Events". The Proactive Events API allows you to make an API call to send notifications to your skill customers. Those notifications must conform to one of a number of pre-defined Proactive Events Schemas.

    For example, if I had a trash collection custom skill and I wanted to tell my customers that the coming Monday is trash collection day, I could send an AMAZON.TrashCollectionAlert.Activated event to notify them.

    Recommendations

    The recommendations below are operating from the assumption that you are indeed working with a smart home skill and that your goal is to send smart home events to the "Alexa Event Gateway":

    1. Remove the alexa::devices:all:notifications:write permission from your smart home skill's manifest. This permission is not supported by smart home skills.

    2. When making the call to the /auth/o2/token endpoint to get your access_token and refresh_token remove the alexa::proactive_events scope added previously.

    As a point of reference, here's a screen-shot of my own, working, Postman request in which I receive an access_token and refresh_token: enter image description here