Skill Messaging REST API Reference

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 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 Configure an Application or Service to Send Messages to Your Skill.

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

The following example shows a request to your skill to update an item on an Alexa list. On receipt of the message, the skill can update the corresponding Alexa list by using the List Management Update list item REST API.

{
    "data": {
        "operation": "Update list item",
        "listId": "09d9d7df-05be-438c-9d32968c5608",
        "itemId": "item identifier",
        "status": "completed"
    },
    "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

The response has no body.

HTTP status codes

Status Description

202 Accepted

Message accepted and queued for delivery to the skill. To deliver the message, the skill endpoint must be available. If the endpoint is unavailable, Alexa retries for expiresAfterSeconds seconds.

400 Bad Request

Indicates that one or more properties in the request body are invalid or missing.

401 Unauthorized

Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Specified userId not found.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.