Send a Message Request to a Skill

Sample cURL Message Request
Handle Messages Received by Your Skill
- Skill Service Must Send Acknowlegments to the Skill Messaging API
- New Request Type

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

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

Name	Location	Type	Required?	Description
`userId`	path	string	Required	The ID of the skill user. This ID is the same as the `userId` provided in requests sent by Alexa. It must correspond to a valid user for the specified skill.
`skillMessagingToken`	head	string	Required	The token provided from the authorization API. This is a Bearer type token. For example: `Authorization: Bearer Atz\|zzzzbbbccc`
`message`	body	object	Required	The message you want to send to the skill, in the following format, with the appropriate numeric value for `expiresAfterSeconds`. `json { data: { }, expiresAfterSeconds: integer }`

Message Object

Parameter	Type	Description
data	JSON	Required. The payload data to send with the message. The data must be in the form of JSON-formatted key-value pairs. Both keys and values must be of type String. The total size of the data cannot be greater than 6KB. This 6KB size includes includes keys and values, the quotes that surround them, the ":" character that separates them, the commas that separate the pairs, and the opening and closing braces around the field. However, any space between key/value pairs is not included in the calculation of the payload size. If the message does not include payload data, as in the case of a sync message, you can pass in an empty object, such as `json "data": {}`
`expiresAfterSeconds`	integer	Optional. The number of seconds that the message will be retained to retry if message delivery is not successful. Allowed values are from 60 (1 minute) to 86400 (1 day), inclusive. The default is 3600 (1 hour). Multiple retries may occur during this interval. The retry logic is exponential. The first retry occurs after 30 seconds, and this time period doubles on every retry. The retries end when the total time elapsed since the message was first sent has exceeded the value you provided for `expiresAfterSeconds`. Message expiry is unlikely to be a problem if the message handler has been set up correctly, such as if the skill has a handler that automatically succeeds the context. With a correct setup, you will always receive the message once promptly. This mechanism for retries is provided as a safeguard in case your skill goes down during a message delivery.

Response (to a Request to the Skill Messaging API)

Code	Description	Headers
202	Message has been successfully accepted, and will be sent to the skill.	X-Amzn-RequestID

X-Amzn-RequestID Object

Name	Type	Description
X-Amzn-RequestID	string	A value created that uniquely identifies the request. If you have an issue, Amazon support can use this value to troubleshoot the problem.

Error Codes

Code	Error	Description
400	Bad request	Data is missing or not valid.
403	Forbidden request	The `skillmessagingToken` is expired or not valid.
404	Not found.	The `userId` does not exist.
429	Message rate exceeded.	The requester has exceeded their maximum allowable rate of messages.
500	Internal service exception

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.

Request	MessageRequest
Interface	Messaging
Definition	`json "request": { "type": "Messaging.MessageReceived", "requestId":"string", "timestamp":"string", "message": < object > }`
Attributes	message: 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) user	European (EU) user
https://api.amazonalexa.com	https://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 >>"
        }
      }
    }
  }
}