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.

The PlaybackController interface has no directives.

PlaybackController Requests

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. 
{
  "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.

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, 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": "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, 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": "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, 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": "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, 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": "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:

Interfaces:

Last updated: Mar 30, 2022