Messaging Interface Reference

Implement the Messaging intent in your skill to receive out-of-session messages, such as a message from a third-party app. For example, you can use the Skill Messaging REST API in your app to send list updates from your app to a skill. After Alexa receives a message and queues it for delivery to your skill, your skill must acknowledge the message. Otherwise, Alexa continues to try to deliver the message to your skill.

Messaging request types

Alexa sends the following messaging request types to your skill.

Request type Description

Messaging.MessageReceived

Delivery of an out-of-session message received by Alexa with the Send skill message API request.

MessageReceived request

The Messaging.MessageReceived request includes the same request body format as the standard request types for custom skills. For the full definition of the request body format, see Request Format.

Use the context.System.user.userId parameter to identify the Alexa user and the context.System.user.accessToken to identify the user in an account-linked system. Use the context.System.apiAccessToken in Alexa-specific APIs, such as the List Management APIs. The apiAccessToken is valid for 60 minutes and should not be persisted.

Request body example

{
    "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": "message blob"
        }
    }
}

Request body parameters

The following table shows the definition of the request object.

Parameter Description Type Required

type

Identifies the request.

String

Yes

requestId

Unique identifier for the message.

String

Yes

timestamp

Time of the message.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ..

String

Yes

message

Message blob provided by a third-party application or service.
Maximum size: 6 KB.

String

Yes

Response

To indicate that your skill received the message, send an acknowledgement to the Messaging.MessageReceived intent promptly . Otherwise, Alexa continues to send the message until the message expiry time. Respond with HTTP 200 OK to indicate message received. If 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 about standard message responses, see Response Format.

Was this page helpful?

Last updated: Oct 13, 2023