PlaybackController Interface Reference | Alexa Skills Kit (original) (raw)

Alexa > Documentation > Alexa Skills Kit > Custom Skill Interface Reference > Interfaces >

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:

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

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

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

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

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

Response

Your skill can't return a response to System.ExceptionEncountered request.

• Request and Response JSON Reference
• Request Types Reference
• AudioPlayer Interface Reference

Was this page helpful?

Last updated: Nov 28, 2023