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/previous touch 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
- NextCommandIssued Request
- PauseCommandIssued Request
- PlayCommandIssued Request
- PreviousCommandIssued Request
- System.ExceptionEncountered Request
- Service Interface Reference (JSON)
PlaybackController Requests
PlaybackController
requests in response to button presses. For example, the Amazon Tap device handles pause button events locally, so your skill will not receive these requests when used on this device. The pause touch control on an Alexa-enabled device with a screen also handles the pause automatically and does not 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 a "next" button with the intent to skip to the next audio item. |
PlaybackController.PauseCommandIssued |
Sent when the user uses a "pause" button with the intent to stop playback. |
PlaybackController.PlayCommandIssued |
Sent when the user uses a "play" or "resume" button with the intent to start or resume playback. |
PlaybackController.PreviousCommandIssued |
Sent when the user uses a "previous" button with the intent to go back to the previous audio item. |
session
object, since they are not 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 in the JSON Interface Reference for Custom Skills.
PlaybackController
request, you can only respond with AudioPlayer
directives. The response cannot 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 a "next" button with the intent to skip to the next audio item.
{
"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"
}
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. | string |
locale |
A string indicating the user's locale. For example: en-US . See supported locale codes. |
string |
Valid Response Types
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.
PauseCommandIssued Request
Sent when the user uses a "pause" button with the intent to stop playback.
{
"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"
}
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. | string |
locale |
A string indicating the user's locale. For example: en-US . See supported locale codes. |
string |
Valid Response Types
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.
PlayCommandIssued Request
Sent when the user uses a "play" or "resume" button 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"
}
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. | string |
locale |
A string indicating the user's locale. For example: en-US . See supported locale codes. |
string |
Valid Response Types
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.
PreviousCommandIssued Request
Sent when the user uses a "previous" button with the intent to go back to the previous audio item.
{
"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"
}
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. | string |
locale |
A string indicating the user's locale. For example: en-US . See supported locale codes. |
string |
Valid Response Types
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.
System.ExceptionEncountered Request
If a response to a PlaybackController
request causes an error, your skill is sent a System.ExceptionEncountered
request. Any directives included in the response are ignored.
{
"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"
}
}
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. | string |
locale |
A string indicating the user's locale. For example: en-US . See supported locale codes. |
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 |
Valid Response Types
Your skill cannot return a response to System.ExceptionEncountered
.
Service Interface Reference (JSON)
Request Format and Standard Request Types:
- Request and Response JSON Reference
- Request Types Reference (LaunchRequest, IntentRequest, SessionEndedRequest)
- Alexa.Presentation.APL Interface
- Alexa.Presentation.APLT Interface
- Alexa.Presentation.HTML Interface
- AudioPlayer Interface
- Connections Interface
- Dialog Interface
- Messaging Interface
- PlaybackController Interface (this document)
- VideoApp Interface
Last updated: Mar 30, 2022