PlaybackController

    The PlaybackController interface of the Alexa Voice Service (AVS) exposes a series of events for navigating a playback queue with an on-client button press or GUI control, rather than through a speech request.

    Version changes

    Capability assertion

    A device can implement PlaybackController 1.1 on its own behalf, but not on behalf of any connected endpoints.

    New AVS integrations must assert support through Alexa.Discovery, but AVS continues support for legacy integrations through the Capabilities API.

    
    {
        "interface": "PlaybackController",  
        "type": "AlexaInterface",  
        "version": "1.1"  
    }  
      
    

    PlayCommandIssued event

    The PlayCommandIssued event must be sent when a user starts/resumes playback of a media item using an on-client button press or GUI affordance.

    Sample message

    {
        "context": [
        // Use an array of context objects to communicate the
        // state of all client components to Alexa. See Context for details.
        ],   
        "event": {
            "header": {
                "namespace": "PlaybackController",
                "name": "PlayCommandIssued",
                "messageId": "{{STRING}}"
            },
            "payload": {
            }
        }
    }
    

    Context

    The PlayCommandIssued event requires the client to send the status of all client component states to Alexa. See Context.

    Header parameters

    Parameter Description Type
    messageId A unique ID used to represent a specific message. string

    Payload parameters

    An empty payload should be sent.

    PauseCommandIssued event

    The PauseCommandIssued event must be sent when a user pauses the playback of a media item using an on-client button press or GUI affordance.

    Sample message

    {
        "context": [
        // Use an array of context objects to communicate the
        // state of all client components to Alexa. See Context for details.
        ],    
        "event": {
            "header": {
                "namespace": "PlaybackController",
                "name": "PauseCommandIssued",
                "messageId": "{{STRING}}"
            },
            "payload": {
            }
        }
    }
    

    Context

    The PauseCommandIssued event requires the client to send the status of all client component states to Alexa. See Context.

    Header parameters

    Parameter Description Type
    messageId A unique ID used to represent a specific message. string

    Payload parameters

    An empty payload should be sent.

    NextCommandIssued event

    The NextCommandIssued event must be sent when a user skips to the next media item in their playback queue using an on-client button press or GUI affordance.

    Sample message

    {
        "context": [
        // Use an array of context objects to communicate the
        // state of all client components to Alexa. See Context for details.
        ],     
        "event": {
            "header": {
                "namespace": "PlaybackController",
                "name": "NextCommandIssued",
                "messageId": "{{STRING}}"
            },
            "payload": {
            }
        }
    }
    

    Context

    The NextCommnadIssued event requires the client to send the status of all client component states to Alexa. See Context.

    Header parameters

    Parameter Description Type
    messageId A unique ID used to represent a specific message. string

    Payload parameters

    An empty payload should be sent.

    PreviousCommandIssued event

    The PreviousCommandIssued event must be sent when a user skips to the previous media item in their playback queue using an on-client button press or GUI affordance.

    Sample message

    {
        "context": [
        // Use an array of context objects to communicate the
        // state of all client components to Alexa. See Context for details.
        ],     
        "event": {
            "header": {
                "namespace": "PlaybackController",
                "name": "PreviousCommandIssued",
                "messageId": "{{STRING}}"
            },
            "payload": {
            }
        }
    }
    

    Context

    The PreviousCommandIssued event requires the client to send the status of all client component states to Alexa. See Context.

    Header parameters

    Parameter Description Type
    messageId A unique ID used to represent a specific message. string

    Payload parameters

    An empty payload should be sent.

    ButtonCommandIssued event

    Use the ButtonCommandIssued event to notify Alexa when a user presses a button on the device or GUI, such as skip forward or skip backward. Use the provider or Alexa skill to determine skip duration. Each ButtonCommandIssued event is additive. For example, a scenario where each button press skips forward playback by 30 seconds. If a user presses the skip forward button three times in a row and sends three ButtonCommandIssued events to Alexa, the additive effect is to skip forward a total of 90 seconds.

    Sample message

    {
        "context": [
        // Use an array of context objects to communicate the
        // state of all client components to Alexa. See Context for details.
        ],
        "event": {
            "header": {
                "namespace": "PlaybackController",
                "name": "ButtonCommandIssued",
                "messageId": "{{STRING}}"
            },
            "payload": {
                "name": "{{STRING}}"
            }
        }
    }

    Context

    The ButtonCommandIssued event requires the client to send the status of all client component states to Alexa. See Context.

    Header parameters

    Parameter Description Type
    messageId A unique ID used to represent a specific message. string

    Payload parameters

    Parameter Description Type
    name Specifies the command triggered by an on-client button press or GUI affordance. Accepted values: SKIPFORWARD, SKIPBACKWARD. string

    ToggleCommandIssued event

    Use the ToggleCommandIssued event to notify Alexa that a user has selected or de-selected an option or feature using an on-client button press or GUI control. Supported options include: shuffle, loop, repeat, thumbs up, and thumbs down.

    Sample message

    {
        "context": [
        // Use an array of context objects to communicate the
        // state of all client components to Alexa. See Context for details.
        ],
        "event": {
            "header": {
                "namespace": "PlaybackController",
                "name": "ToggleCommandIssued",
                "messageId": "{{STRING}}"
            },
            "payload": {
                "name": "{{STRING}}"
                "action": "{{STRING}}"
             }
        }
    }

    Context

    The ToggleCommandIssued event requires the client to send the status of all client component states to Alexa. See Context.

    Header parameters

    Parameter Description Type
    messageId A unique ID used to represent a specific message. string

    Payload parameters

    Parameter Description Type
    name Specifies the option/feature that a user toggles by an on-client button press or GUI control. Accepted values: SHUFFLE, LOOP, REPEAT, THUMBSUP, THUMBSDOWN. string
    action Indicates if the toggle has been selected or deselected. Accepted values: SELECT, DESELECT. string

      The PlaybackController interface of the Alexa Voice Service (AVS) exposes a series of events for navigating a playback queue with an on-client button press or GUI control, rather than through a speech request.

      Capability assertion

      A device can implement PlaybackController 1.0 on its own behalf, but not on behalf of any connected endpoints.

      New AVS integrations must assert support through Alexa.Discovery, but AVS continues support for legacy integrations through the Capabilities API.

      Sample Object

      {
          "type": "AlexaInterface",
          "interface": "PlaybackController",
          "version": "1.0"
      }
      

      PlayCommandIssued event

      The PlayCommandIssued event must be sent when a user starts/resumes playback of a media item using an on-client button press or GUI affordance.

      Sample Message

      {
          "context": [
              // Use an array of context objects to communicate the
              // state of all client components to Alexa. See Context for details.
          ],   
          "event": {
              "header": {
                  "namespace": "PlaybackController",
                  "name": "PlayCommandIssued",
                  "messageId": "{{STRING}}"
              },
              "payload": {
              }
          }
      }
      

      Context

      This event requires your product to report the status of all client component states to Alexa in the context object. For additional information see Context.

      Header Parameters

      Parameter Description Type
      messageId A unique ID used to represent a specific message. string

      Payload Parameters

      An empty payload should be sent.

      PauseCommandIssued event

      Send the PauseCommandIssued event a user presses a button or GUI control to pause playback of a media item. When PauseCommandIssued is sent, the client must wait until it receives a Stop directive before pausing or stopping the media item locally.

      Sample Message

      {
          "context": [
              // Use an array of context objects that to communicate the
              // state of all client components to Alexa. See Context for details.   
          ],    
          "event": {
              "header": {
                  "namespace": "PlaybackController",
                  "name": "PauseCommandIssued",
                  "messageId": "{{STRING}}"
              },
              "payload": {
              }
          }
      }
      

      Context

      This event requires your product to report the status of all client component states to Alexa in the context object. For additional information see Context.

      Header Parameters

      Parameter Description Type
      messageId A unique ID used to represent a specific message. string

      Payload Parameters

      An empty payload should be sent.

      NextCommandIssued event

      The NextCommandIssued event must be sent when an end user skips to the next media item in their playback queue using an on-client button press or GUI affordance. The next media item should play when the client receives a Play directive from Alexa.

      Sample Message

      {
          "context": [
              // Use an array of context objects that are to communicate the
              // state of all client components to Alexa. See Context for details.   
          ],     
          "event": {
              "header": {
                  "namespace": "PlaybackController",
                  "name": "NextCommandIssued",
                  "messageId": "{{STRING}}"
              },
              "payload": {
              }
          }
      }
      

      Context

      This event requires your product to report the status of all client component states to Alexa in the context object. For additional information see Context.

      Header Parameters

      Parameter Description Type
      messageId A unique ID used to represent a specific message. string

      Payload Parameters

      An empty payload should be sent.

      PreviousCommandIssued event

      The PreviousCommandIssued event must be sent when a user skips to the previous media item in their playback queue using an on-client button press or GUI affordance.

      Sample Message

      {
          "context": [
              // Use an array of context objects to communicate the
              // state of all client components to Alexa. See Context for details.   
          ],     
          "event": {
              "header": {
                  "namespace": "PlaybackController",
                  "name": "PreviousCommandIssued",
                  "messageId": "{{STRING}}"
              },
              "payload": {
              }
          }
      }
      

      Context

      This event requires your product to report the status of all client component states to Alexa in the context object. For additional information see Context.

      Header Parameters

      Parameter Description Type
      messageId A unique ID used to represent a specific message. string

      Payload Parameters

      An empty payload should be sent.