Bluetooth 1.0


Overview

The Bluetooth interface exposes directives and events that are used to manage a client's Bluetooth connection with peer devices, such as smart phones, and Bluetooth-enabled speakers. The interface supports the following profiles: A2DP sink and source, and AVRCP target and controller.

  • A2DP source - Originates content, such as streaming audio.
  • A2DP sink - Receives content, such as streaming audio.
  • AVRCP controller and target - Controls media playback on remote devices. Typically, this profiles is used with A2DP profiles for next, previous, pause, and play controls.

Additionally, this interface exposes directives and events that are used to control media playback on connected Bluetooth A2DP source devices (see Media Control via Bluetooth for a complete list of directives and events.).

Supported use cases:

  • Scan, pair, and unpair Bluetooth devices via the Amazon Alexa App.
  • Connect and disconnect Bluetooth devices with voice and via the Amazon Alexa App.
  • Control media playback when a connected Bluetooth device is set as A2DP source.

Sequence diagrams

The Bluetooth interface supports scanning, connecting/disconnecting, and pairing/unpairing from Bluetooth peer devices using voice, on-product GUI, the Amazon Alexa App, and third-party companion apps. These sequence diagrams illustrate supported Bluetooth interactions, and the associated directives and events exchanged between your client and AVS.

This set of sequence diagrams illustrate interactions initiated via voice.

Pair a Bluetooth device using voice

Click to enlarge

Media Controls

Media control directives in the Bluetooth interface are used to manage and control playback of content originating from a connected Bluetooth device with its profile set as A2DP-SOURCE. It is the responsibility of your AVS client to pass these commands to the connected device over the Bluetooth channel.

Media control via Bluetooth requires accurate reporting of streaming state in the context. This table shows which directives are delivered to your AVS client based on the streaming state and profile of your connected Bluetooth device:

User Request Streaming State Connected Device is A2DP source Connected Device A2DP sink
"Alexa, play." INACTIVE or PAUSED Bluetooth.Play. Note: Initially, playback must be started from the connected device. After playback has been initiated, Alexa will have the focus necessary to send subsequent Bluetooth.Play directives. AudioPlayer.Play
"Alexa, stop." ACTIVE Bluetooth.Stop AudioPlayer.Stop
"Alexa, next." - If ACTIVE, Bluetooth.Next is sent. If INACTIVE or PAUSED, then Bluetooth.Next and Bluetooth.Play are sent. AudioPlayer.Play
"Alexa, previous." - If ACTIVE, two Bluetooth.Previous directives are sent. If INACTIVE or PAUSED, then two Bluetooth.Previous directives are sent followed by Bluetooth.Play. AudioPlayer.Play
"Alexa, restart." ACTIVE A Bluetooth.Previous directive is sent, which instructs the A2DP source device to restart playback from the start for the current audio item. AudioPlayer.Play

Manage Bluetooth Streaming State

These events are sent to notify Alexa that Bluetooth streaming has started or ended.

This diagram illustrates when a client is required to report a change in Bluetooth streaming state:

SpeechRecognizer State Diagram
Click to enlarge
State Description
INACTIVE This is the initial streaming state after connecting to a Bluetooth device, but before any content has been streamed.
ACTIVE This is the streaming state while audio is streamed to/from a connected Bluetooth device.
PAUSED This is the streaming state when audio playback to/from a connected Bluetooth device is paused as a result of a user interaction. For example, a button press.

Capability assertion

Bluetooth 1.0 may be implemented by the device on its own behalf, but not on behalf of any connected endpoints.

New AVS integrations must assert support through Alexa.Discovery, but Alexa will continue to support existing integrations using the Capabilities API.

Sample Object

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

Context

Context is a container used to communicate the state of your client components to AVS. Context should reflect the state of client components just before an event is fired.

All events that require context must include an object for Bluetooth.BluetoothState if Bluetooth is enabled.

Sample Context

{
  "header": {
    "namespace": "Bluetooth",
    "name": "BluetoothState"
  },
  "payload": {
    "alexaDevice": {
      "friendlyName": "{{STRING}}"
    },
    "pairedDevices": [
      {
        "uniqueDeviceId": "{{STRING}}",
        "friendlyName": "{{STRING}}",
        "supportedProfiles": [
          {
            "name": "{{STRING}}",
            "version": "{{STRING}}"
          },
          {
            // Additional objects may be included for each
            // profile that the device supports.
          }
        ]
      },
      {
        // Additional objects should be included for each
        // paired device.
      }
    ],  
    "activeDevice": {
      "uniqueDeviceId": "{{STRING}}",
      "friendlyName": "{{STRING}}",
      "supportedProfiles": [
        {
          "name": "{{STRING}}",
          "version": "{{STRING}}"
        },
        {
          // Additional objects may be included for each
          // profile that the device supports.
        }
      ],
      "streaming": "{{STRING}}"
    }
  }
}

{
    "header": {
        "namespace": "Bluetooth",
        "name": "BluetoothState"
    },
    "payload": {
        "alexaDevice": {
            "friendlyName": "Echo-0ST"
        },
        "pairedDevices": [
            {
                // This identifies AVS Device 1 as a paired device
                // that supports three profiles.
                "uniqueDeviceId": "353088131600891",
                "friendlyName": "AVS Device 1",
                "supportedProfiles":[
                    {
                        "name" : "A2DP-SOURCE",
                        "version" : "1.3"
                    },
                    {
                        "name" : "AVRCP",
                        "version" : "1.0"
                    },
                    {
                        "name" : "A2DP-SINK",
                        "version" : "1.3"
                    }
                ]
            },
            // If additional devices have been paired, they are
            // included in the pairedDevices list.
            {
                // This identifies Wendy's Phone as a paired device
                // that supports two profiles.
                "uniqueDeviceId": "85308813234230897",
                "friendlyName": "Wendy's Phone",
                "supportedProfiles":[
                    {
                        "name" : "A2DP-SOURCE",
                        "version" : "1.0"
                    },
                    {
                        "name" : "AVRCP",
                        "version" : "1.0"
                    }
                ]             
            }
        ],
        // This identifies the connected device and its supported
        // profiles. IMPORTANT: An activeDevice will always be in
        // the list of pairedDevices.
        "activeDevice": {
           "uniqueDeviceId": "353088131600891",
           "friendlyName": "AVS Device 1",
           "supportedProfiles":[
                {
                    "name" : "A2DP-SOURCE",
                    "version" : "1.3"
                },
                {
                    "name" : "AVRCP",
                    "version" : "1.0"
                },
                {
                    "name" : "A2DP-SINK",
                    "version" : "1.3"
                }
           ],
           // This is the streaming state at the time an event is sent.
           // This will determine what playback directives are sent to your
           // product.
           "streaming": "ACTIVE"
        }
    }
}

Payload Parameters

Parameter Description Type
alexaDevice An object that contains information about the AVS-enabled device. object
alexaDevice.friendlyName A friendly name for the device. Alexa will include this value in TTS. For example: "My Smart Phone". string
pairedDevices A list of paired Bluetooth devices. list
pairedDevices[i].uniqueDeviceId A universally unique identifier (UUID) generated to the RFC 4122 specification. string
pairedDevices[i].friendlyName A friendly name for the device. For example: "My Smart Phone". string
pairedDevices[i].supportedProfiles[j] A list of supported profiles. Each item in the list is an object containing name and version. list
pairedDevices[i].supportedProfiles[j].name Identifies the device and notifies Alexa if the device is A2DP-SOURCE or A2DP-SINK. string
pairedDevices[i].supportedProfiles[j].version Identifies the profile version. string
activeDevice An object that contains information about the active Bluetooth device. Note: A paired Bluetooth device must only be advertised as an activeDevice if connected. If not connected, activeDevice must be omitted from the context. object
activeDevice.uniqueDeviceId A universally unique identifier (UUID) generated to the RFC 4122 specification. string
activeDevice.friendlyName A friendly name for the device. For example: "My Smart Phone". string
activeDevice.supportedProfiles[j] A list of supported profiles. Each item in the list is an object containing name and version. list
activeDevice.supportedProfiles[j].name Identifies the device and is used to determine if it is source or sink. string
activeDevice.supportedProfiles[j].version Identifies the profile version. string
activeDevice.streaming The streaming status of the device. Accepted values: ACTIVE, INACTIVE, PAUSED. string

Streaming State

The streaming state your product sends up in the Context object determines if your product will receive playback commands. Use this table to determine which state must be provided to Alexa for activeDevice.streaming:

State Description
INACTIVE This is the initial streaming state of an activeDevice after it has been connected, but before any content has been streamed.
ACTIVE This is the streaming state of an activeDevice that is playing audio to/from a connected Bluetooth device.
PAUSED This is the streaming state when audio playback to/from a connected Bluetooth device is paused as a result of a user interaction. For example, a button press.

This table shows the streaming state that your product must be in before and after a user request, such as pairing:

Streaming State Before Action User Request Action Taken by Product Streaming State After Action
- "Alexa, connect my phone." Connect to the targeted Bluetooth device. INACTIVE
INACTIVE When the Alexa product is A2DP-SINK, the user initiates playback from an A2DP-SOURCE device, for example a paired phone. When the Alexa product is A2DP-SOURCE, the user may initiate playback using voice, for example, "Alexa, play classical music." Stream content from the SOURCE device. ACTIVE
ACTIVE "Alexa, pause." / "Alexa, pause music from my phone." Playback is paused. PAUSED
PAUSED "Alexa, resume." / "Alexa, resume music from my phone." Playback resumes. ACTIVE

Directives

ScanDevices

This directive instructs a client to scan for discoverable Bluetooth devices. Your client must send a ScanDevicesUpdated each time Bluetooth devices are discovered. If the scan fails, your client must send the ScanDevicesFailed event to AVS.

Sample Message


{
  "directive": {
    "header": {
      "namespace": "Bluetooth",
      "name": "ScanDevices",
      "messageId": "{{STRING}}"
    },
    "payload": {
    }
  }
}

Header Parameters

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

Payload Parameters

This directive has an empty payload.

EnterDiscoverableMode

This directive instructs a client to enter discoverable mode, which allows a user to initiate Bluetooth pairing from a peer device, such as a smart phone. When your client successfully enters discoverable mode, the EnterDiscoverableModeSucceeded event must be sent to AVS. If your client fails to enter "discoverable" mode, it must send EnterDiscoverableModeFailed.

Sample Message


{
  "directive": {
    "header": {
      "namespace": "Bluetooth",
      "name": "EnterDiscoverableMode",
      "messageId": "{{STRING}}"
    },
    "payload": {
      "durationInSeconds": {{LONG}}
    }
  }
}

Header Parameters

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

Payload Parameters

Parameter Description Type
durationInSeconds Indicates how long a product should remain in discoverable mode. long

PairDevice

This directive instructs a client to initiate pairing with a specific Bluetooth device. The uniqueDeviceId should be used to maintain a local mapping with the peer device's MAC address.

When a client successfully pairs with the specified device, the PairDeviceSucceeded event must be sent. If your client fails to pair with the specified device, it must send PairDeviceFailed.

Sample Message


{
  "directive": {
    "header": {
      "namespace": "Bluetooth",
      "name": "PairDevice",
      "messageId": "{{STRING}}"
    },
    "payload": {
      "device": {
        "uniqueDeviceId": "{{STRING}}"
      }
    }
  }
}

Header Parameters

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

Payload Parameters

Parameter Description Type
device.uniqueDeviceId A universally unique identifier (UUID) generated to the RFC 4122 specification. This identifies the Bluetooth device the client should pair with. Your client must maintain a local mapping between this UUID and the Bluetooth device's MAC address. string

ExitDiscoverableMode

This directive instructs a client to exit discoverable mode. For example, if a user cancels Bluetooth pairing from the Amazon Alexa App, this directive is sent from the service to your client.

Sample Message


{
  "directive": {
    "header": {
      "namespace": "Bluetooth",
      "name": "ExitDiscoverableMode",
      "messageId": "{{STRING}}"
    },
    "payload": {
    }
  }
}

Header Parameters

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

Payload Parameters

This directive has an empty payload.

UnpairDevice

This directive instructs a client to unpair from a specific Bluetooth device. When a client successfully unpairs with the specified Bluetooth device, the UnpairDeviceSucceeded event must be sent. If the client fails to unpair with the specified Bluetooth device, it must send UnpairDeviceFailed.

Sample Message


{
  "directive": {
    "header": {
      "namespace": "Bluetooth",
      "name": "UnpairDevice",
      "messageId": "{{STRING}}"
    },
    "payload": {
      "device": {
        "uniqueDeviceId": "{{STRING}}"
      }
    }
  }
}

Header Parameters

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

Payload Parameters

Parameter Description Type
device.uniqueDeviceId A universally unique identifier (UUID) generated to the RFC 4122 specification. This identifies the Bluetooth device the client should pair with. Your client must maintain a local mapping between this UUID and the Bluetooth device's MAC address. string

ConnectByDeviceId

This directive instructs a client to establish a connection with a paired Bluetooth device using that device's uniqueDeviceId. When a client successfully establishes a connection with the specified device, the ConnectByDeviceIdSucceeded event must be sent. If the client fails to establish a connection with the specified device, it must send ConnectByDeviceIdFailed.

Sample Message


{
  "directive": {
    "header": {
      "namespace": "Bluetooth",
      "name": "ConnectByDeviceId",
      "messageId": "{{STRING}}"
    },
    "payload": {
      "device": {
        "uniqueDeviceId": "{{STRING}}"
      }
    }
  }
}

Header Parameters

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

Payload Parameters

Parameter Description Type
device.uniqueDeviceId A universally unique identifier (UUID) generated to the RFC 4122 specification. This identifies the Bluetooth device the client should pair with. Your client must maintain a local mapping between this UUID and the Bluetooth device's MAC address. string

ConnectByProfile

This directive instructs a client to establish a connection with a paired Bluetooth device using profile information from the peer Bluetooth device. If multiple devices share the specified profile, the client should establish a connection with the last device to establish a connection.

The name parameter should be used to determine if the device is SOURCE or SINK. For example:

  • When a user says, "Alexa, pair my phone" the profile is A2DP-SOURCE, since the phone acts as SOURCE.
  • When a user says "Alexa, pair my speaker" the profile is A2DP-SINK, since the speaker acts as SINK.
  • When a user says, "Alexa, connect to Bluetooth" the profile is A2DP, since the device can connect as SOURCE or SINK.

When a client successfully establishes a connection with the specified device, the ConnectByProfileSucceeded event must be sent to AVS. If the client fails to establish a connection with the specified device, it must send ConnectByProfileFailed.

Sample Message


{
  "directive": {
    "header": {
      "namespace": "Bluetooth",
      "name": "ConnectByProfile",
      "messageId": "{{STRING}}"
    },
    "payload": {
      "profile": {
        "name": "{{STRING}}",
        "version": "{{STRING}}"
      }
    }
  }
}

Header Parameters

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

Payload Parameters

Parameter Description Type
profile An object that contains information about the Bluetooth device, such as name and version. object
profile.name Identifies the device and is used to determine if it is A2DP-SOURCE or A2DP-SINK. string
profile.version Identifies the profile version. string

DisconnectDevice

This directive instructs a client to disconnect from a specified Bluetooth device. When a client successfully disconnects from a specified Bluetooth device, the DisconnectDeviceSucceeded event must be sent. If the client fails to establish a connection with the specified device, it must send DisconnectDeviceFailed.

Sample Message


{
  "directive": {
    "header": {
      "namespace": "Bluetooth",
      "name": "ConnectByDeviceId",
      "messageId": "{{STRING}}"
    },
    "payload": {
      "device": {
        "uniqueDeviceId": "{{STRING}}"
      }
    }
  }
}

Header Parameters

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

Payload Parameters

Parameter Description Type
device.uniqueDeviceId A universally unique identifier (UUID) generated to the RFC 4122 specification. This identifies the Bluetooth device the client should pair with. Your client must maintain a local mapping between this UUID and the Bluetooth device's MAC address. string

Play

This directive instructs the connected Bluetooth device, with its profile set as A2DP-SOURCE, to initiate playback on the A2DP sink device. When the directive is successfully processed, the MediaControlPlaySucceeded. If the client fails to process the directive, it must send MediaControlPlayFailed.

Sample Message


{
  "directive": {
    "header": {
      "namespace": "Bluetooth",
      "name": "Play",
      "messageId": "{{STRING}}"
    },
    "payload": {
    }
  }
}

Header Parameters

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

Payload Parameters

This directive has an empty payload.

Stop

This directive instructs the A2DP source to stop playback on the connected A2DP sink device. When the directive is successfully processed, the MediaControlStopSucceeded must be sent. If the client fails to process the directive, MediaControlStopFailed must be sent.

Sample Message


{
  "directive": {
    "header": {
      "namespace": "Bluetooth",
      "name": "Stop",
      "messageId": "{{STRING}}"
    },
    "payload": {
    }
  }
}

Header Parameters

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

Payload Parameters

This directive has an empty payload.

Next

This directive instructs the A2DP source to skip to the next media item on the connected A2DP sink device. When the directive is successfully processed, the MediaControlNextSucceeded is sent. If the client fails to process the directive, MediaControlNextFailed must be sent.

Sample Message


{
  "directive": {
    "header": {
      "namespace": "Bluetooth",
      "name": "Next",
      "messageId": "{{STRING}}"
    },
    "payload": {
    }
  }
}

Header Parameters

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

Payload Parameters

This directive has an empty payload.

Previous

This directive instructs the A2DP source to skip to the previous media item on the connected A2DP sink device. When the directive is successfully processed, the MediaControlPreviousSucceeded. If the client fails to process the directive, it must send MediaControlPreviousFailed.

Sample Message


{
  "directive": {
    "header": {
      "namespace": "Bluetooth",
      "name": "Previous",
      "messageId": "{{STRING}}"
    },
    "payload": {
    }
  }
}

Header Parameters

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

Payload Parameters

An empty payload is sent.

Events

ScanDevicesUpdated

After receiving a ScanDevices directive, this event must be sent periodically as Bluetooth devices are discovered. discoveredDevices must contain an object for all discovered device from when the scan was initiated (not the delta from the previous event).

Sample Message

{
  "context": [
    // This is an array of context objects that are used to communicate the
    // state of all client components to Alexa. See Context for details.
  ],
  "event": {
    "header": {
      "namespace": "Bluetooth",
      "name": "ScanDevicesUpdated",
      "messageId": "{{STRING}}"
    },
    "payload": {
      "discoveredDevices": [
        {
          "uniqueDeviceId": "{{STRING}}",
          "friendlyName": "{{STRING}}",
          "truncatedMacAddress": "{{STRING}}"
        }
      ],
      "hasMore": {{BOOLEAN}}
    }
  }
}

Context

This event requires the client to send the status of all client component states to Alexa. For additional information see Context.

Header Parameters

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

Payload Parameters

Parameter Description Type
discoveredDevices A list of objects that included information about discovered devices. list
discoveredDevices.uniqueDeviceId A universally unique identifier (UUID) generated to the RFC 4122 specification. Each discovered device should have a UUID. string
discoveredDevices.friendlyName A friendly name for the discovered device. For example: "My Smart Phone". When friendlyName is unavailable, an empty string must be sent. string
discoveredDevices.truncatedMacAddress Optional: This parameter should be sent when the friendlyName is unavailable. It contains the partially masked MAC address associated with the Bluetooth device. The first 8 hexadecimal digits must be masked with the character X. When friendlyName is unavailable, this value is used to represent the device on screen. string
hasMore A boolean value that notifies your client of the scan status. If true, the scan is not yet complete. If false, the scan is complete. boolean

ScanDevicesFailed

After receiving a ScanDevices directive, this event must be sent if the scan operation fails. If the scan fails, the list of discovered Bluetooth devices in the companion app will be cleared. Note: A scan failure is indepedent of devices being discovered. Most often, this a failure is the result of: a low-level protocol issue, driver issues, or being in an incompatible state when the scan is initiated.

Sample Message

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

Context

This event requires the client to send the status of all client component states to Alexa. 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 is sent.

EnterDiscoverableModeSucceeded

This event must be sent when your client enters discoverable mode.

Sample Message

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

Context

This event requires the client to send the status of all client component states to Alexa. 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 is sent.

EnterDiscoverableModeFailed

This event must be sent when your client fails to enter discoverable mode. Note: This may occur as the result of a low-level protocol or driver issue.

Sample Message

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

Context

This event requires the client to send the status of all client component states to Alexa. 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 is sent.

PairDeviceSucceeded

This event must be sent when a client successfully pairs with a peer Bluetooth device.

Sample Message

{
  "context": [
    // This is an array of context objects that are used to communicate the
    // state of all client components to Alexa. See Context for details.
  ],
  "event": {
    "header": {
      "namespace": "Bluetooth",
      "name": "PairDeviceSucceeded",
      "messageId": "{{STRING}}"
    },
    "payload": {
      "device": {
        "uniqueDeviceId": "{{STRING}}",
        "friendlyName": "{{STRING}}"
      }
    }
  }
}

Context

This event requires the client to send the status of all client component states to Alexa. For additional information see Context.

Header Parameters

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

Payload Parameters

Parameter Description Type
device An object that contains information about the device. object
device.uniqueDeviceId A universally unique identifier (UUID) generated to the RFC 4122 specification. string
device.friendlyName A friendly name for the device. For example: "My Smart Phone". string

PairDeviceFailed

This event must be sent when a client fails to pair with a peer Bluetooth device.

Sample Message

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

Context

This event requires the client to send the status of all client component states to Alexa. 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 is sent.

UnpairDeviceSucceeded

This event must be sent when a client unpairs with a Bluetooth device.

Sample Message

{
  "context": [
    // This is an array of context objects that are used to communicate the
    // state of all client components to Alexa. See Context for details.
  ],
  "event": {
    "header": {
      "namespace": "Bluetooth",
      "name": "UnpairDeviceSucceeded",
      "messageId": "{{STRING}}"
    },
    "payload": {
      "device": {
        "uniqueDeviceId": "{{STRING}}",
        "friendlyName": "{{STRING}}"
      }
    }
  }
}

Context

This event requires the client to send the status of all client component states to Alexa. For additional information see Context.

Header Parameters

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

Payload Parameters

Parameter Description Type
device An object that contains information about the device. object
device.uniqueDeviceId A universally unique identifier (UUID) generated to the RFC 4122 specification. string
device.friendlyName A friendly name for the device. For example: "My Smart Phone". string

UnpairDeviceFailed

This event must be sent when a client fails to unpair with a Bluetooth device.

Sample Message

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

Context

This event requires the client to send the status of all client component states to Alexa. 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 is sent.

ConnectByDeviceIdSucceeded

This event must be sent when a client establishes a connection with a paired Bluetooth device using uniqueDeviceId.

Sample Message

{
  "context": [
    // This is an array of context objects that are used to communicate the
    // state of all client components to Alexa. See Context for details.
  ],
  "event": {
    "header": {
      "namespace": "Bluetooth",
      "name": "ConnectByDeviceIdSucceeded",
      "messageId": "{{STRING}}"
    },
    "payload": {
      "device": {
        "uniqueDeviceId": "{{STRING}}",
        "friendlyName": "{{STRING}}"
      },
      "requester": "{{STRING}}"
    }
  }
}

Context

This event requires the client to send the status of all client component states to Alexa. For additional information see Context.

Header Parameters

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

Payload Parameters

Parameter Description Type
device An object that contains information about the device. object
device.uniqueDeviceId A universally unique identifier (UUID) generated to the RFC 4122 specification. string
device.friendlyName A friendly name for the device. For example: "My Smart Phone". string
requester Identifies the initiator of the connection request. Accepted values: DEVICE or CLOUD. DEVICE indicates that the event was triggered by a user interaction with the device. CLOUD indicates that the event was sent from AVS. string

ConnectByDeviceIdFailed

This event must be sent when the attempt to connect to a paired Bluetooth device using uniqueDeviceId fails.

Sample Message

{
  "context": [
    // This is an array of context objects that are used to communicate the
    // state of all client components to Alexa. See Context for details.
  ],
  "event": {
    "header": {
      "namespace": "Bluetooth",
      "name": "ConnectByDeviceIdFailed",
      "messageId": "{{STRING}}"
    },
    "payload": {
      "device": {
        "uniqueDeviceId": "{{STRING}}",
        "friendlyName": "{{STRING}}"
      },
      "requester": "{{STRING}}"
    }
  }
}

Context

This event requires the client to send the status of all client component states to Alexa. For additional information see Context.

Header Parameters

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

Payload Parameters

Parameter Description Type
device An object that contains information about the device. object
device.uniqueDeviceId A universally unique identifier (UUID) generated to the RFC 4122 specification. string
device.friendlyName A friendly name for the device. For example: "My Smart Phone". string
requester Identifies the initiator of the connection request. Accepted values: DEVICE or CLOUD. DEVICE indicates that the event was triggered by a user interaction with the device. CLOUD indicates that the event was sent from AVS. string

ConnectByProfileSucceeded

This event must be sent when a client establishes a connection with a paired Bluetooth device using the profile provided in the ConnectByProfile directive.

Sample Message

{
  "context": [
    // This is an array of context objects that are used to communicate the
    // state of all client components to Alexa. See Context for details.
  ],
  "event": {
    "header": {
      "namespace": "Bluetooth",
      "name": "ConnectByProfileSucceeded",
      "messageId": "{{STRING}}"
    },
    "payload": {
      "device": {
        "uniqueDeviceId": "{{STRING}}",
        "friendlyName": "{{STRING}}"
      },
      "requester": "{{STRING}}",
      "profileName": "{{STRING}}"
    }
  }
}

Context

This event requires the client to send the status of all client component states to Alexa. For additional information see Context.

Header Parameters

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

Payload Parameters

Parameter Description Type
device An object that contains information about the device. object
device.uniqueDeviceId A universally unique identifier (UUID) generated to the RFC 4122 specification. string
device.friendlyName A friendly name for the device. For example: "My Smart Phone". string
requester Identifies the initiator of the connection request. Accepted values: DEVICE or CLOUD. DEVICE indicates that the event was triggered by a user interaction with the device. CLOUD indicates that the event was sent from AVS. string
profileName The profile name associated with the connected device. This should match the profile.name provided in the ConnectByProfile directive. string

ConnectByProfileFailed

This event must be sent when the attempt to connect to a paired Bluetooth device using the profile provided in the ConnectByProfile directive fails.

Sample Message

{
  "context": [
    // This is an array of context objects that are used to communicate the
    // state of all client components to Alexa. See Context for details.
  ],
  "event": {
    "header": {
      "namespace": "Bluetooth",
      "name": "ConnectByProfileFailed",
      "messageId": "{{STRING}}"
    },
    "payload": {
      "requester": "{{STRING}}",
      "profileName": "{{STRING}}"
    }
  }
}

Context

This event requires the client to send the status of all client component states to Alexa. For additional information see Context.

Header Parameters

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

Payload Parameters

Parameter Description Type
requester Identifies the initiator of the connection request. Accepted values: DEVICE or CLOUD. DEVICE indicates that the event was triggered by a user interaction with the device. CLOUD indicates that the event was sent from AVS. string
profileName The profile name associated with the connected device. This should match the profile.name provided in the ConnectByProfile directive. string

DisconnectDeviceSucceeded

This event must be sent after receiving a DisconnectDevice directive, when a client successfully disconnects from a paired Bluetooth device.

Sample Message

{
  "context": [
    // This is an array of context objects that are used to communicate the
    // state of all client components to Alexa. See Context for details.
  ],
  "event": {
    "header": {
      "namespace": "Bluetooth",
      "name": "DisconnectDeviceSucceeded",
      "messageId": "{{STRING}}"
    },
    "payload": {
      "device": {
        "uniqueDeviceId": "{{STRING}}",
        "friendlyName": "{{STRING}}"
      },
        "requester": "{{STRING}}"
    }
  }
}

Context

This event requires the client to send the status of all client component states to Alexa. For additional information see Context.

Header Parameters

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

Payload Parameters

Parameter Description Type
device An object that contains information about the device. object
device.uniqueDeviceId A universally unique identifier (UUID) generated to the RFC 4122 specification. string
device.friendlyName A friendly name for the device. For example: "My Smart Phone". string
requester Identifies the initiator of the connection request. Accepted values: DEVICE or CLOUD. DEVICE indicates that the event was triggered by a user interaction with the device. CLOUD indicates that the event was sent from AVS. string

DisconnectDeviceFailed

This event must be sent after receiving a DisconnectDevice directive, when a client fails to disconnect from a paired Bluetooth device.

Sample Message

{
  "context": [
    // This is an array of context objects that are used to communicate the
    // state of all client components to Alexa. See Context for details.
  ],
  "event": {
    "header": {
      "namespace": "Bluetooth",
      "name": "DisconnectDeviceFailed",
      "messageId": "{{STRING}}"
    },
    "payload": {
      "device": {
        "uniqueDeviceId": "{{STRING}}",
        "friendlyName": "{{STRING}}"
      },
      "requester": "{{STRING}}"
    }
  }
}

Context

This event requires the client to send the status of all client component states to Alexa. For additional information see Context.

Header Parameters

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

Payload Parameters

Parameter Description Type
device An object that contains information about the device. object
device.uniqueDeviceId A universally unique identifier (UUID) generated to the RFC 4122 specification. string
device.friendlyName A friendly name for the device. For example: "My Smart Phone". string
requester Identifies the initiator of the connection request. Accepted values: DEVICE or CLOUD. DEVICE indicates that the event was triggered by a user interaction with the device. CLOUD indicates that the event was sent from AVS. string

StreamingStarted

This event is sent to Alexa when:

  • Bluetooth streaming state of a connected device changes from INACTIVE to ACTIVE
  • Bluetooth streaming state of a connected device changes from PAUSED to ACTIVE
{
    "event": {
        "header": {
            "namespace": "Bluetooth",
            "name": "StreamingStarted",
            "messageId": "{{STRING}}",
        },
        "payload": {
            "device": {
                "uniqueDeviceId": "{{STRING}}"
            }
        }
    }
}

Payload Parameters

Parameter Description Type
device Includes information about the device. object
device.uniqueDeviceId A universally unique identifier (UUID) generated to the RFC 4122 specification. Each discovered device should have a UUID. string

StreamingEnded

This event is sent to Alexa when Bluetooth streaming state of a connected device changes from ACTIVE to PAUSED.

{
    "event": {
        "header": {
            "namespace": "Bluetooth",
            "name": "StreamingEnded",
            "messageId": "{{STRING}}",
        },
        "payload": {
            "device": {
                "uniqueDeviceId": "{{STRING}}"
            }
        }
    }
}
Parameter Description Type
device Includes information about the device. object
device.uniqueDeviceId A universally unique identifier (UUID) generated to the RFC 4122 specification. Each discovered device should have a UUID. string

MediaControlPlaySucceeded

This event must be sent when the Play directive is successfully handled by the A2DP source.

Sample Message

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

Context

This event requires the client to send the status of all client component states to Alexa. 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 is sent.

MediaControlPlayFailed

This event must be sent when the A2DP source fails to handle the Play directive.

Sample Message

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

Context

This event requires the client to send the status of all client component states to Alexa. 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 is sent.

MediaControlStopSucceeded

This event must be sent when the Stop directive is successfully handled by the A2DP source.

Sample Message

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

Context

This event requires the client to send the status of all client component states to Alexa. 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 is sent.

MediaControlStopFailed

This event must be sent when the A2DP source fails to handle the Stop directive.

Sample Message

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

Context

This event requires the client to send the status of all client component states to Alexa. 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 is sent.

MediaControlNextSucceeded

This event must be sent when the Next directive is successfully handled by the A2DP source.

Sample Message

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

Context

This event requires the client to send the status of all client component states to Alexa. 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 is sent.

MediaControlNextFailed

This event must be sent if the A2DP source fails to handle the Stop directive.

Sample Message

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

Context

This event requires the client to send the status of all client component states to Alexa. 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 is sent.

MediaControlPreviousSucceeded

This event must be sent when the Previous directive is successfully handled by the A2DP source.

Sample Message

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

Context

This event requires the client to send the status of all client component states to Alexa. 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 is sent.

MediaControlPreviousFailed

This event must be sent if the A2DP source fails to handle the Previous directive.

Sample Message

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

Context

This event requires the client to send the status of all client component states to Alexa. 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 is sent.


Was this page helpful?

Last updated: Nov 27, 2023