Your Alexa Dashboards

Your Alexa Dashboards Support

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 or remote control. Your skill can respond to these requests with AudioPlayer directives to start and stop playback.

Note: 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
- Parameters
- Valid Response Types
PauseCommandIssued Request
- Parameters
- Valid Response Types
PlayCommandIssued Request
- Parameters
- Valid Response Types
PreviousCommandIssued Request
- Parameters
- Valid Response Types
System.ExceptionEncountered Request
- Parameters
- Valid Response Types
Service Interface Reference (JSON)

PlaybackController Requests

Note: Note that some hardware devices do not support sending 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.

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.

Important: These requests do not include the 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": "string",
  "context": {
    "System": {
      "application": {},
      "user": {},
      "device": {}
    },
    "AudioPlayer": {
      "token": "string",
      "offsetInMilliseconds": 0,
      "playerActivity": "string"
    }
  },
  "request": {
    "type": "PlaybackController.NextCommandIssued",
    "requestId": "string",
    "timestamp": "string",
    "locale": "string"
  }
}

For the full request format, see Request Format in the JSON Interface Reference for Custom Skills.

Note: When responding to any 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: The service simulator does not support testing the 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": "string",
  "timestamp": "string",
  "locale": "string"
}

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, or reprompt.
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": "string",
  "timestamp": "string",
  "locale": "string"
}

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, or reprompt.
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": "string",
  "timestamp": "string",
  "locale": "string"
}

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, or reprompt.
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": "string",
  "timestamp": "string",
  "locale": "string"
}

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, or reprompt.
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": "string",
  "timestamp": "string",
  "locale": "string",
  "error": {
    "type": "string",
    "message": "string"
  },
  "cause": {
    "requestId": "string"
  }
}

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:

Interfaces:

AudioPlayer Interface Reference
Dialog Interface Reference
Display Interface Reference
PlaybackController Interface Reference (this document)
VideoApp Interface Reference