Skill Messaging REST API Reference

Note: Sign in to the developer console to build or publish your skill.

Use the Skill Messaging REST API to send an asynchronous message for a specified user from your app or service to an Alexa skill. On receipt of the API request, Alexa accepts the message and responds to your app. Then, Alexa queues the message for delivery, and attempts to deliver the message to the skill.

For details about the message that Alexa delivers to the skill, see Handle messages received by your skill.

API endpoint

Use one of the following endpoints, based on the region for your skill:

North America: https://api.amazonalexa.com
Europe: https://api.eu.amazonalexa.com
Far East: https://api.fe.amazon.com

Authentication

You send the Skill Messaging API out-of-session from a third-party app or service. Before you call the API, you must retrieve an access token to access your skill. For details, see Get access token with skill credentials operation. In the request body, set the scope to scope=alexa:skill_messaging.

Note: Cross-Origin Request Sharing (CORS) is not enabled for the Skill Messaging API.

Operations

The Skill Messaging API includes the following operations.

Operation	HTTP method and URI
Send skill message	`POST /v1/skillmessages/users/{userId}`

Send skill message

Send an asynchronous message for a specified user to an Alexa skill. On receipt of the API request, Alexa accepts the message and attempts to deliver it to the skill.

Request

To send a message to your skill, you make a POST request to the skillmessages/users resource.

Request path and header example

Copied to clipboard.

POST /v1/skillmessages/users/{userId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`userId`	Path	Identifies the user. The `userId` must correspond to a valid user of the skill identified by the `access_token`. This ID value is the same as the `context.System.user.userId` provided in requests sent to your skill from Alexa.	String	Yes
`access token`	Header	Bearer token for access to the skill.	String	Yes

Request body example

Copied to clipboard.

{
    "data": {
        "sometag": "some message"
    },
    "expiresAfterSeconds":60
}

Request body properties

Property	Description	Type	Required
`data`	Defines the payload that Alexa includes in the message to your skill. If you don't include a payload, include an empty object. Valid value: JSON-formatted key-value pairs of type String. Maximum size: 6 KB, including quotes, commas, and brackets.	JSON object	Yes
`expiresAfterSeconds`	Number of seconds to retain the message if message delivery isn't successful. Default is 3600 seconds (1 hour). Valid values: 1 – 86400 seconds. Alexa retries message delivery by using exponential back-off. Alexa retries after 30 seconds and doubles the retry interval on every retry. When the total elapsed time after the message was received exceeds the `expiresAfterSeconds` value, Alexa stops retrying and drops the message. Your skill must send a response promptly.	Integer	No

Response

A successful response returns HTTP 202 Accepted that indicates that the Alexa accepted the message and queued the message for delivery to the skill. The response doesn't mean that Alexa delivered the message. Also, on successful delivery, Alexa doesn't send a receipt or confirmation to the skill. For details about message delivery, see Handle messages received by your skill. On error, the response returns the appropriate HTTP status code.

Response body example

The response has no body.

Response body properties