PlaybackController Interface Reference
The PlaybackController
interface provides requests to notify your skill when the user interacts with player controls, such as the buttons on a device, a remote control, or the next and previous tap controls on an Alexa-enabled device with a screen. Your skill can respond to these requests with AudioPlayer
directives to start and stop playback.
PlaybackController
requests are not sent in response to voice requests such as "Alexa, next song." Voice requests are sent to your skill as built-in intents (such as AMAZON.NextIntent
) via a normal IntentRequest
request.The PlaybackController
interface has no directives.
PlaybackController requests
PlaybackController
requests in response to button presses. For example, the Amazon Tap device handles pause button events locally, so your skill won't receive these requests when used on this device. The (pause) tap control on an Alexa-enabled device with a screen also handles the pause automatically and doesn't send a request.
PlaybackController
sends the following requests to notify your skill about playback control events:
Request Type | Description |
---|---|
PlaybackController.NextCommandIssued |
Sent when the user uses (next) to skip to the next audio item. |
PlaybackController.PauseCommandIssued |
Sent when the user uses (pause) to stop playback. |
PlaybackController.PlayCommandIssued |
Sent when the user uses (play) to start or resume playback. |
PlaybackController.PreviousCommandIssued |
Sent when the user uses (previous) to go back to the previous audio item. |
session
object because the request isn't sent in the context of a skill session. Use the context
object to get details, such as the applicationId
and userId
.{
"version": "1.0",
"context": {
"System": {
"application": {},
"user": {},
"device": {}
},
"AudioPlayer": {
"token": "AAAABBBBCCCCCDDDDEEEEEFFFF",
"offsetInMilliseconds": 0,
"playerActivity": "PLAYING"
}
},
"request": {
"type": "PlaybackController.NextCommandIssued",
"requestId": "amzn1.echo-api.request.aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"timestamp": "2018-04-11T15:15:25Z",
"locale": "en-US"
}
}
For the full request format, see [Request Format][service_ref#request-format] in the [JSON Interface Reference for Custom Skills][service_ref].
PlaybackController
request, you can only respond with AudioPlayer
directives. The response can't include any of the standard properties such as outputSpeech
, card
, or reprompt
. Sending a response with these unsupported properties causes an error.Note that the Alexa simulator on the Test page of the developer console doesn't support testing PlaybackController
requests.
NextCommandIssued request
Sent when the user uses (next) with the intent to skip to the next audio item.
Example request
{
"type": "PlaybackController.NextCommandIssued",
"requestId": "unique.id.for.the.request",
"timestamp": "timestamp of request in format: 2018-04-11T15:15:25Z",
"locale": "a locale code such as en-US"
}
Request parameters
Parameter | Description | Type |
---|---|---|
type |
PlaybackController.NextCommandIssued |
String |
requestId |
Represents a unique identifier for the specific request. | String |
timestamp |
Provides the date and time when Alexa sent the request as an ISO 8601 formatted string. Used to [verify the request when hosting your skill as a web service][hosting-as-web-service#timestamp]. | String |
locale |
A string indicating the user's locale. For example: en-US . See [supported locale codes][service_ref#request-locale]. |
String |
Response
Your skill can respond to NextCommandIssued
with any AudioPlayer directive.
The response cannot include:
- Any standard properties such as
outputSpeech
,card
, orreprompt
. - Any other directives from other interfaces, such a [Dialog directive][dialog-interface-reference#directives].
PauseCommandIssued request
Sent when the user uses (pause) with the intent to stop playback.
Example request
{
"type": "PlaybackController.PauseCommandIssued",
"requestId": "unique.id.for.the.request",
"timestamp": "timestamp of request in format: 2018-04-11T15:15:25Z",
"locale": "a locale code such as en-US"
}
Request parameters
Parameter | Description | Type |
---|---|---|
type |
PlaybackController.PauseCommandIssued |
String |
requestId |
Represents a unique identifier for the specific request. | String |
timestamp |
Provides the date and time when Alexa sent the request as an ISO 8601 formatted string. Used to [verify the request when hosting your skill as a web service][hosting-as-web-service#timestamp]. | String |
locale |
A string indicating the user's locale. For example: en-US . See [supported locale codes][service_ref#request-locale]. |
String |
Response
Your skill can respond to PauseCommandIssued
with any AudioPlayer directive.
The response cannot include:
- Any standard properties such as
outputSpeech
,card
, orreprompt
. - Any other directives from other interfaces, such a [Dialog directive][dialog-interface-reference#directives].
PlayCommandIssued request
Sent when the user uses (play) to start or resume playback.
{
"type": "PlaybackController.PlayCommandIssued",
"requestId": "unique.id.for.the.request",
"timestamp": "timestamp of request in format: 2018-04-11T15:15:25Z",
"locale": "a locale code such as en-US"
}
Request parameters
Parameter | Description | Type |
---|---|---|
type |
PlaybackController.PlayCommandIssued |
String |
requestId |
Represents a unique identifier for the specific request. | String |
timestamp |
Provides the date and time when Alexa sent the request as an ISO 8601 formatted string. Used to [verify the request when hosting your skill as a web service][hosting-as-web-service#timestamp]. | String |
locale |
A string indicating the user's locale. For example: en-US . See [supported locale codes][service_ref#request-locale]. |
String |
Response
Your skill can respond to PlayCommandIssued
with any AudioPlayer directive.
The response cannot include:
- Any standard properties such as
outputSpeech
,card
, orreprompt
. - Any other directives from other interfaces, such a [Dialog directive][dialog-interface-reference#directives].
PreviousCommandIssued request
Sent when the user uses (previous) with the intent to go back to the previous audio item.
Example request
{
"type": "PlaybackController.PreviousCommandIssued",
"requestId": "unique.id.for.the.request",
"timestamp": "timestamp of request in format: 2018-04-11T15:15:25Z",
"locale": "a locale code such as en-US"
}
Request parameters
Parameter | Description | Type |
---|---|---|
type |
PlaybackController.PreviousCommandIssued |
String |
requestId |
Represents a unique identifier for the specific request. | String |
timestamp |
Provides the date and time when Alexa sent the request as an ISO 8601 formatted string. Used to [verify the request when hosting your skill as a web service][hosting-as-web-service#timestamp]. | String |
locale |
A string indicating the user's locale. For example: en-US . See [supported locale codes][service_ref#request-locale]. |
String |
Response
Your skill can respond to PreviousCommandIssued
with any AudioPlayer directive.
The response cannot include:
- Any standard properties such as
outputSpeech
,card
, orreprompt
. - Any other directives from other interfaces, such a [Dialog directive][dialog-interface-reference#directives].
System.ExceptionEncountered request
If a response to a PlaybackController
request causes an error, Alexa sends your skill a System.ExceptionEncountered
request. Alexa ignores any directives included in the response to this request.
Example request
{
"type": "System.ExceptionEncountered",
"requestId": "unique.id.for.the.request",
"timestamp": "timestamp of request in format: 2018-04-11T15:15:25Z",
"locale": "a locale code such as en-US",
"error": {
"type": "error code such as INVALID_RESPONSE",
"message": "description of the error that occurred"
},
"cause": {
"requestId": "unique identifier for the request that caused the error"
}
}
Request parameters
Parameter | Description | Type |
---|---|---|
type |
System.ExceptionEncountered |
string |
requestId |
Represents a unique identifier for the specific request. | string |
timestamp |
Provides the date and time when Alexa sent the request as an ISO 8601 formatted string. Used to [verify the request when hosting your skill as a web service][hosting-as-web-service#timestamp]. | string |
locale |
A string indicating the user's locale. For example: en-US . See [supported locale codes][service_ref#request-locale]. |
string |
error |
Contains an object with error information | object |
error.type |
Identifies the specific type of error (INVALID_RESPONSE , DEVICE_COMMUNICATION_ERROR , INTERNAL_ERROR ). |
string |
error.message |
A description of the error the device has encountered. | string |
cause.requestId |
The requestId for the request that caused the error |
string |
Response
Your skill can't return a response to System.ExceptionEncountered
request.
Related topics
Last updated: Nov 28, 2023