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.

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

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, or reprompt.
  • 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, or reprompt.
  • 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, or reprompt.
  • 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, or reprompt.
  • 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.

Was this page helpful?

Last updated: Nov 28, 2023