Skill Messaging REST API Reference | Alexa Skills Kit (original) (raw)

Alexa > Documentation > Alexa Skills Kit > 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 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:

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.

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.

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

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 missing or not valid.
401 Unauthorized Request didn't include the authorization token or the token is expired or not valid. 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.
Was this page helpful?

Last updated: Aug 07, 2024