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 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
.
Operations
The Skill Messaging API includes the following operations.
Operation | HTTP method and URI |
---|---|
|
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
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 |
---|---|---|---|---|
|
Path |
Identifies the user. The |
String |
Yes |
|
Header |
Bearer token for access to the skill. |
String |
Yes |
Request body example
{
"data": {
"sometag": "some message"
},
"expiresAfterSeconds":60
}
Request body properties
Property | Description | Type | Required |
---|---|---|---|
|
Defines the payload that Alexa includes in the message to your skill. If you don't include a payload, include an empty object. |
JSON object |
Yes |
|
Number of seconds to retain the message if message delivery isn't successful. Default is 3600 seconds (1 hour). |
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 |
---|---|
|
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 |
|
Indicates that one or more properties in the request body are missing or not valid. |
|
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. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Specified |
|
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. |
|
Error occurred on the server. The skill can retry the request by using exponential back-off. |
Related topics
- Messaging Interface Reference
- Call Alexa Service APIs Out of Session With Node.js
- Alexa Out-Of-Session Service Clients With Python
- Alexa Skills Kit SDK for Java
- Skill Events
Last updated: Aug 07, 2024