Send a Message Request to a 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. Your skill receives the message as a 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, the message is delivered as it's processed. Amazon doesn't guarantee the delivery time or order of the delivery of messages. Because the caller also owns the skill being messaged, the caller is responsible for determining whether a message has been delivered to the skill. There is 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.

Handle messages received by your skill

Your skill receives the message as a Messaging.MessageReceived intent. For details on the standard request format, see Request Format.

Send an acknowledgment to the Skill Messaging API

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.

If using Node.js, send the acknowledgement by calling context.succeed(); after you handle the message. If using another language, 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 more information, see The Context Methods in Node.js Runtime v0.10.42 in the AWS Lambda documentation.

New request type

The Messaging.MessageReceived request type should be handled by the skill endpoint (whether that is AWS Lambda or web service). The request is a new type of intent, so your skill will require an additional handling method for this type of request. See Request Format.

RequestMessageRequest
InterfaceMessaging
Definitionjson "request": {    "type": "Messaging.MessageReceived", "requestId":"string", "timestamp":"string", "message": < object > }
Attributesmessage: A message blob provided by a third-party application back end. The message blob has a limit of 6 KB within our system.

The Messaging.MessageReceived request sample shown below uses a consentToken in the permissions object. For out-of-session messaging requests, a consentToken, which contains the user's consent, is provided to the skill. See Context Object.

A consent token is valid for 60 minutes, and should not be persisted. A consent token is refreshed automatically every time the Skill Messaging API receives a new in-session request or out-of-session request.

Each userId lasts for the lifetime of the skill enablement for the skill user. If a user disables and re-enables a skill, the userId will change. Thus, when this user next uses the skill, the user will be seen as a new user. As with a new user, the userId must be noted in-session so that it can be used to send a notification out-of-session. If the Skill Messaging API is used to call the skill messaging endpoint /skillmessages/users/{userId}, and a 404 error (userId not found) occurs, then the userId is no longer valid in the system.

apiEndpoint Value in context object in requests

The IntentRequest sample shown below uses an apiEndpoint value in the System object. The value varies depending on the location of the user. See Context Object.

North American (NA) userEuropean (EU) user
https://api.amazonalexa.comhttps://api.eu.amazonalexa.com

Sample Messaging.MessageReceived request

The IDs have been altered and truncated in this example.

{
  "version": "1.0",
  "context": {
    "System": {
      "application": {
        "applicationId": "amzn1.echo-sdk-ams.app.b4277435"
      },
      "user": {
        "userId": "amzn1.ask.account.AGQ3PQ",
        "permissions": {
         "consentToken": "ZZZZZZZ..."
        }	
      },
      "apiAccessToken": "AxThk...",
      "request": {
        "type": "Messaging.MessageReceived",
        "requestId": "amzn1.echo-api.request.0000000-0000-0000-0000-00000000000",
        "timestamp": "2015-05-13T12:34:56Z",
        "message": {
          "notice": "<< text of message >>"
        }
      }
    }
  }
}