Receive an Event in Your Skill

You can use the Skill Messaging REST API to send an asynchronous message request to your skill from an out-of-session app or service. On receipt of the REST API, Alexa delivers the message to your skill in the message body of the Messaging.MessageReceived intent.

Follow these guidelines to receive out-of-session messages.

Skill messaging guidelines

In response to a Send skill message request, Alexa accepts the message and queues it for delivery to your skill. To deliver the accepted message to the skill successfully, the skill endpoint must be available. A successful delivery requires that your skill acknowledge the message by "succeeding" the context.

If the skill is online, Alexa delivers the message as the message is received. Amazon doesn't guarantee the delivery time or order of the delivery of messages as there might be more than one Alexa-enabled device receiving messages from the app. The caller is responsible for determining whether a message was delivered to the skill. There's no built-in receipt or confirmation of delivery mechanism. The caller is also responsible for handling duplicate messages in the skill if multiple requests are sent.

The following image shows the out-of-session messaging flow.

Messaging between app and LWA, followed by skill messaging API and List API.
Click to enlarge

Handle messages received by your skill

Your skill receives the message as a Messaging.MessageReceived intent. For details about the request format, see Messaging Interface Reference.

The following example shows a request that Alexa received from the Skill Messaging API.

{
    "version": "1.0",
    "context": {
        "System": {
            "user": {
                "userId": "user.id.1",
                "accessToken": "someAccessToken.1"
            },
            "apiEndpoint": "https://api.amazonalexa.com",
            "apiAccessToken": "someAccessToken.2"
        }
    },
    "request": {
        "type": "Messaging.MessageReceived",
        "requestId": "unique request ID",
        "timestamp": "2022-10-03T16:20:50.52Z",
        "message": {
            "sometag": "some message"
        }
    }
}

Your skill must send an acknowledgement to the Messaging.MessageReceived intent promptly to indicate that it received the message. Otherwise, Alexa continues to send the message until it expires.

Send an empty success message as an acknowledgment. When your skill service makes other API calls upon receiving messages, it's important to succeed the context after those API requests are synchronously returned. For details, see Messaging.MessageReceived response.

Was this page helpful?

Last updated: Aug 07, 2024