Send a Message Request to a Skill

• Sample cURL Message Request
  • Message Object
  • Response (to a Request to the Skill Messaging API)
  • X-Amzn-RequestID Object
  • Error Codes
• Handle Messages Received by Your Skill
  • Skill Service Must Send Acknowlegments to the Skill Messaging API
  • New Request Type
    • Consent Token in Permissions Object in Requests
    • apiEndpoint Value in Context Object in Requests
    • Sample Messaging.MessageReceived Request

Use the Skill Messaging API to send a message request to a skill for a specified user.

See also: Skill Events and List Events

The Skill Messaging API is asynchronous. A successful response denotes that the message has been accepted, and will be enqueued to be sent to the skill. The skill endpoint must be available for an accepted message to be successfully delivered to the skill. If the skill endpoint is unavailable, the message will be retried periodically for the time period specified by the expiresAfterSeconds field (or a default expiry, if this value is not provided). A successful delivery requires the skill to acknowledge the message by "succeeding" the context.

If the skill is online, the message is delivered as it is processed. There is no guaranteed timing or ordering 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.

The message request format is as follows.

Sample cURL Message Request

This example shows the API_URL value for the North American (NA) endpoint.

If you use the EU endpoint, then API_URL=https://api.eu.amazonalexa.com/v1/skillmessages/users/USERID . If you use the FE endpoint, then API_URL=https://api.fe.amazon.com/v1/skillmessages/users/USERID .

ALEXA_USER_ID='ReplaceWithUserId'
SKILL_MESSAGING_TOKEN='ReplaceWithToken'
MESSAGE='{"data":{ "sampleMessage": "Sample Message"}, "expiresAfterSeconds": 60}'
API_URL=https://api.amazonalexa.com/v1/skillmessages/users/$ALEXA_USER_ID

 curl -v -s -k -X POST \
      -H "Authorization: Bearer $SKILL_MESSAGING_TOKEN" \
      -H "Content-Type: application/json" \
      -d "$MESSAGE" \
      $API_URL

Message Object

Response (to a Request to the Skill Messaging API)

X-Amzn-RequestID Object

Error Codes

Handle Messages Received by Your Skill

After you enable your skill for events and configure the corresponding application for your skill, ensure that the service for your skill (AWS Lambda or web service) knows how to handle the messages it receives. 

Messaging.MessageReceived is a request type similar to other requests that skills receive. For details on the standard request format, see Request Format.

Skill Service Must Send Acknowlegments to the Skill Messaging API

For an out-of-session message, the service for your skill (AWS Lambda or web service) must send an acknowledgement to the Skill Messaging API that it received the message. Otherwise, the API 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 is 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.

Consent Token in Permissions Object in Requests

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.

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 >>"
        }
      }
    }
  }
}