Send data to the skill backend

If you want to send data from your APL document to your skill backend, whether triggered by a user interaction or by another event, you need the SendEvent command.

The SendEvent command generates and sends an Alexa.Presentation.APL.UserEvent request to your skill backend. The UserEvent request contains information about the component/event that triggered the request and can also transmit values defined by you.

Let's assume that your APL document contains 2 buttons, one button stands for "Yes" and one button for "No", in your skill backend you want to know which of the buttons was pressed.

Here is an excerpt of how these buttons might look in your APL document:

{
    "type": "TouchWrapper",
    "item": {
        "type": "Text",
        "text": "Yes"
    }
},
{
    "type": "TouchWrapper",
    "item": {
        "type": "Text",
        "text": "No"
    }
}

The TouchWrapper component belongs to the category Touchable Components and therefore supports the property onPress, onPress is a handler that is called whenever a "press" event is triggered. With the help of the onPress handler we can define a sequence of commands to be executed.

{
    "type": "TouchWrapper",
    "onPress": [{
        "type": "SendEvent",
        "arguments": ["Decision", "Yes"]
    }],
    "item": {
        "type": "Text",
        "text": "Yes"
    }
},
{
    "type": "TouchWrapper",
    "onPress": [{
        "type": "SendEvent",
        "arguments": ["Decision", "No"]
    }],
    "item": {
        "type": "Text",
        "text": "No"
    }
}

The buttons would already send a request to your skill backend, so you need to define an intent handler to respond to it. Here is an example:

import {
    getRequest,
    getRequestType,
    HandlerInput,
    RequestHandler,
} from 'ask-sdk-core';

const UserEventDecisionHandler = {
    canHandle({ requestEnvelope }) {
        if (getRequestType(requestEnvelope) === 'Alexa.Presentation.APL.UserEvent') {
            const request = getRequest(requestEnvelope);
            const [arg0] = request.arguments;

            return arg0 === 'Decision';
        }

        return false;
    },

    async handle({ requestEnvelope, responseBuilder }) {
        const request = getRequest(requestEnvelope);
        const [, decision] = request.arguments;

        // custom code
    },
};

export default UserEventDecisionHandler;

You still need to register the handler, of course.

import UserEventDecisionHandler from './handlers/UserEventDecisionHandler';

const skill = Alexa.SkillBuilders.custom()
    .addRequestHandlers(
        UserEventDecisionHandler
    )
    .create()

I use TypeScript respectively ESM modules for my skills, it may be that "import" doesn't work for you, but you can simply change the corresponding lines to "require".

What can I do if my skill backend does not receive a request?

In APL there is a so called fast mode, some events like a scroll event or page change event are executed in fast mode, within the fast mode certain commands like the SendEvent command are ignored. But you can work around the Fast Mode by assigning your own sequencer to your SendEvent command. Think of the sequencer as a "thread", in APL there is the "Main" thread where all commands are executed, by assigning an own sequencer the command will be executed in normal mode again.

Well, that's it. Have fun sending data to your skill backend! If you liked the post, leave a comment and ❤️.