Bluetooth 2.0
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 source, A2DP sink, and AVRCP target and controller
Version changes
- Support for multiple simultaneous connections to Bluetooth peripherals
- CHANGED
BluetoothState
context entry:- REMOVED
activeDevice
object - ADDED
deviceCategory
string - ADDED
connectionState
string - CHANGED
supportedProfiles
list to support additional Bluetooth profiles
- REMOVED
- ADDED
SetDeviceCategories
directive - ADDED
SetDeviceCategoriesSucceeded
event - ADDED
SetDeviceCategoriesFailed
event - RENAMED the following messages:
ScanDeviceUpdated
event toScanDevicesReport
ConnectByDeviceId
event toConnectByDeviceIds
DisconnectDevice
directive toDisconnectDevices
PairDevice
directive toPairDevices
UnpairDevice
directive toUnpairDevices
- CHANGED the following events by removing the requirement to include
context
:ScanDevicesReport
ScanDevicesFailed
UnpairDevicesFailed
UnpairDevicesSucceeded
DisconnectDevicesSucceeded
DisconnectDevicesFailed
PairDevicesSucceeded
PairDevicesFailed
ConnectByDeviceIdsSucceeded
ConnectByDeviceIds
EnterDiscoverableModeFailed
EnterDiscoverableModeSucceeded
ConnectByProfileSucceeded
ConnectByProfileFailed
MediaControlPlaySucceeded
MediaControlPlayFailed
MediaControlNextSucceeded
MediaControlNextFailed
MediaControlPreviousSucceeded
MediaControlPreviousFailed
MediaControlStopSucceeded
MediaControlStopFailed
- CHANGED the payload object of the following messages:
UnpairDevicesFailed
eventUnpairDevicesSucceeded
eventDisconnectDevicesSucceeded
eventDisconnectDevicesFailed
eventPairDevicesSucceeded
eventPairDevicesFailed
eventConnectByDeviceIdsSucceeded
eventConnectByDeviceIdsFailed
eventConnectByProfileFailed
eventStreamingStarted
eventStreamingEnded
eventMediaControlPlaySucceeded
eventMediaControlPlayFailed
eventMediaControlNextSucceeded
eventMediaControlNextFailed
eventMediaControlPreviousSucceeded
eventMediaControlPreviousFailed
eventMediaControlStopSucceeded
eventMediaControlStopFailed
eventPairDevices
directiveUnpairDevices
directiveConnectByDeviceIds
directiveDisconnectDevices
directiveSetDeviceCategories
directivePlay
directivePrevious
directiveNext
directiveStop
directive
- CHANGED
Overview
The Bluetooth interface supports the following profiles:
- A2DP source - Originator of content, such as streaming audio.
- A2DP sink - Receiver of content, such as streaming audio.
- AVRCP controller and target - Controls media playback on remote devices. Typically, this profile handles functions such as next, previous, pause, and play.
The Bluetooth interface also controls media playback on connected Bluetooth A2DP source devices. For a complete list of directives and events to handle this functionality, see Media Control through Bluetooth.
Supported use cases:
- Scan, pair, and unpair Bluetooth devices with the Amazon Alexa App.
- Connect and disconnect Bluetooth devices with voice through the Amazon Alexa App.
- Control media playback on Bluetooth devices set to the A2DP source.
Sequence diagrams
The Bluetooth interface supports scanning, connecting/disconnecting, pairing/unpairing from Bluetooth peer devices using voice, on-product GUI, the Amazon Alexa App, and third-party companion apps.
The following sequence diagrams illustrate the directives and events exchanged between your client and the Alexa Voice Service (AVS) when using Bluetooth.
Pair a Bluetooth device by using voice

Media controls
Media control directives manage and control playback of content originating from a connected Bluetooth device with its profile set as A2DP_SOURCE
. It's the responsibility of your client to pass these commands to the connected device over the Bluetooth channel.
Media control requires accurate reporting of the streaming state with the context object. The following table explains which directives your AVS client delivers based on the streaming state and profile of your connected Bluetooth device.
User Request | Streaming State | Connected Device: A2DP source | Connected Device: A2DP sink |
---|---|---|---|
"Alexa, play." | INACTIVE or PAUSED |
Bluetooth.Play . Note: Initially, playback must start from the connected device. After playback initiates, Alexa has the necessary focus 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
The following diagram illustrates when a client should report a change in Bluetooth streaming state.

State | Description |
---|---|
INACTIVE |
The initial streaming state after connecting to a Bluetooth device, but before any content streams. |
ACTIVE |
The streaming state while audio streams to or from a connected Bluetooth device. |
PAUSED |
The streaming state when audio playback to or from a connected Bluetooth device pauses from user interaction. For example, a button press. |
Capability assertion
Bluetooth implements on the device on its own behalf. However, it can't implement on behalf of any connected endpoints.
Sample Object
{ "type": "AlexaInterface", "interface": "Bluetooth", "version": "2.0", "configurations": { "profiles": [ "AVRCP", "A2DP_SINK", "A2DP_SOURCE" ] } }
Context
Context is a container that communicates the state of your client components to AVS. Context should reflect the state of your client components immediately before an event is fired.
All Bluetooth events that require context must include an object for BluetoothState
.
Sample Context
{ "header": { "namespace": "Bluetooth", "name": "BluetoothState" }, "payload": { "alexaDevice": { "friendlyName": "{{STRING}}" }, "pairedDevices": [ { "supportedProfiles": [ { "name": "{{STRING}}", "version": "{{STRING}}", "state": { "streaming": "{{STRING}}" } } ], "uniqueDeviceId": "{{STRING}}", "deviceCategory": "{{STRING}}", "friendlyName": "{{STRING}}", "connectionState": "{{STRING}}" } ] } }
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 includes 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]. deviceCategory |
Category of the Bluetooth device. Accepted Values: REMOTE_CONTROL ,GADGET ,AUDIO_VIDEO ,PHONE ,OTHER ,UNKNOWN |
string |
pairedDevices[i]. friendlyName |
A friendly name for the device. For example: "My Smart Phone". | string |
pairedDevices[i]. connectionState |
Bluetooth connection status of paired device. Accepted Values: CONNECTED and DISCONNECTED |
String |
pairedDevices[i]. supportedProfiles[j] |
A list of supported profiles. Each item contains an object with name and version . |
list |
pairedDevices[i]. supportedProfiles[j]. name |
Identifies the Bluetooth profile in use. Accepted Values: A2DP_SOURCE , A2DP_SINK ,AVRCP ,HFP ,HID ,SPP |
string |
pairedDevices[i]. supportedProfiles[j]. version |
Bluetooth profile version | string |
pairedDevices[i]. supportedProfiles[j]. state |
An object that contains information about the active streaming state. Only required for A2DP_SOURCE or A2DP_SINK profiles. |
object |
pairedDevices[i]. supportedProfiles[j]. state. streaming |
The streaming state. Only required for A2DP_SOURCE and A2DP_SINK . Possible Values: INACTIVE ,ACTIVE ,PAUSED |
string |
Streaming State
Use the following rules for any pairedDevice
object that connects to a A2DP_SINK
or A2DP_SOURCE
profile. These rules determine the playback commands Alexa sends to the devices:
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 Alexa connects to a A2DP_SINK , playback initiates from a A2DP_SOURCE . For example a paired phone. When the Alexa product is A2DP_SOURCE, the user can start 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 pauses. | PAUSED |
PAUSED | "Alexa, resume." / "Alexa, resume music from my phone." | Playback resumes. | ACTIVE |
Directives
ScanDevices
This directive instructs your client to scan for discoverable Bluetooth devices.
- If the scan discovers a Bluetooth device Send the
ScanDevicesReport
event to AVS. - If the scan fails: Send the
ScanDevicesFailed
event to AVS.
ScanDevices
does not support voice-initiated requests. Scans can only start by using the Amazon Alexa app or on-product GUI controls. 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.
SetDeviceCategories
This directive updates the deviceCategory
for each discovered device. When a new device pairs with these newly discovered devices, update the Bluetooth Context to include this deviceCategory
.
Sample Message
{ "directive": { "header": { "namespace": "Bluetooth", "name": "SetDeviceCategories", "messageId": "{{STRING}}" }, "payload": { "devices": [ { "uniqueDeviceId": "{{STRING}}", "deviceCategory": "{{STRING}}" } ] } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload Parameters
Parameter | Description | Type |
---|---|---|
devices | A list of devices | list |
devices[i].uniqueDeviceId | A universally unique identifier (UUID) generated using the RFC 4122 specification. | string |
devices[i].deviceCategory | Category of Bluetooth device | string |
EnterDiscoverableMode
This directive instructs a client to initiate Bluetooth discovery mode. This mode allows a user to start Bluetooth pairing from a peer device, such as a smart phone.
- When your client to initiate discovery mode, send the
EnterDiscoverableModeSucceeded
event to AVS. - If your client fails to initiate discovery mode, send a
EnterDiscoverableModeFailed
directive to AVS.
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 |
ExitDiscoverableMode
This directive instructs a client to exit discovery mode. For example, AVS sends ExitDiscoverableMode
if a user cancels Bluetooth pairing from the Amazon Alexa app.
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.
PairDevices
This directive instructs a client to initiate pairing with a specific Bluetooth device. Use uniqueDeviceId
to maintain a local mapping with the MAC address of the peer device.
- When your client pairs with the specified device, send a
PairDevicesSucceeded
event to AVS. - If your client fails to pair with the specified device, send a
PairDevicesFailed
event to AVS.
Sample Message
{ "directive": { "header": { "namespace": "Bluetooth", "name": "PairDevices", "messageId": "{{STRING}}" }, "payload": { "devices": [ { "uniqueDeviceId": "{{STRING}}" } ] } } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload Parameters
Parameter | Description | Type |
---|---|---|
devices | A list of devices | list |
devices[i].uniqueDeviceId | A universally unique identifier (UUID) generated using the RFC 4122 specification. This UUID identifies the Bluetooth device the client should pair with. Your client must maintain a local mapping between this UUID and the Bluetooth MAC address on the device. | string |
Stop
This directive instructs the A2DP source to stop playback on the connected A2DP sink.
- When the directive processes, send the
MediaControlStopSucceeded
event. - If the client fails to process the directive, send a
MediaControlStopFailed
event.
Sample Message
{ "directive": { "header": { "namespace": "Bluetooth", "name": "Stop", "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 | Includes information about the device. | object |
device.uniqueDeviceId | A universally unique identifier (UUID) generated using the RFC 4122 specification. Each discovered device should have a UUID. | string |
Play
This directive instructs a connected Bluetooth device to start playback on the A2DP sink device. It only applies to devices that use a Bluetooth profile set to A2DP_SOURCE
.
- When a client processes the directive, send the
MediaControlPlaySucceeded
event. - If a client fails to process the directive, send the
MediaControlPlayFailed
event.
Sample Message
{ "directive": { "header": { "namespace": "Bluetooth", "name": "Play", "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 | Includes information about the device. | object |
device.uniqueDeviceId | A universally unique identifier (UUID) generated using the RFC 4122 specification. Each discovered device should have a UUID. | string |
Previous
This directive instructs the A2DP source to skip to the previous media item on the connected A2DP sink device.
- When the directive processes, send the
MediaControlPreviousSucceeded
event. - If the client fails to process the directive, send the
MediaControlPreviousFailed
event.
Sample Message
{ "directive": { "header": { "namespace": "Bluetooth", "name": "Previous", "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 | Includes information about the device. | object |
device.uniqueDeviceId | A universally unique identifier (UUID) generated using the RFC 4122 specification. Each discovered device should have a UUID. | string |
Next
This directive instructs the A2DP source to skip to the next media item on the connected A2DP sink device. For example, skipping to the next song in a playlist.
- When the directive processes, send the
MediaControlNextSucceeded
event. - If the client fails to process the directive, send the
MediaControlNextFailed
event.
Sample Message
{ "directive": { "header": { "namespace": "Bluetooth", "name": "Next", "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 | Includes information about the device. | object |
device.uniqueDeviceId | A universally unique identifier (UUID) generated using the RFC 4122 specification. Each discovered device should have a UUID. | string |
UnpairDevices
This directive instructs a client to unpair from a specific Bluetooth device.
- When a client successfully unpairs with the specified Bluetooth device, send an
UnpairDevicesSucceeded
event to AVS - If the client fails to unpair with the specified Bluetooth device, send an
UnpairDevicesFailed
event to AVS.
Sample Message
{ "directive": { "header": { "namespace": "Bluetooth", "name": "UnpairDevices", "messageId": "{{STRING}}" }, "payload": { "devices": [ { "uniqueDeviceId": "{{STRING}}" } ] } } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload Parameters
Parameter | Description | Type |
---|---|---|
devices | A list of devices | list |
devices[i].uniqueDeviceId | A universally unique identifier (UUID) generated using the RFC 4122 specification. This UUID identifies the Bluetooth device the client should pair with. Your client must maintain a local mapping between this UUID and the Bluetooth MAC address on the device. | string |
ConnectByDeviceIds
This directive instructs a client to establish a connection with a paired Bluetooth device using its uniqueDeviceId
as the identifier.
- When a client establishes a connection with the specified device, send the
ConnectByDeviceIdsSucceeded
event to AVS. - If the client fails to establish a connection with the specified device, send the
ConnectByDevicesIdFailed
event to AVS.
Sample Message
{ "directive": { "header": { "namespace": "Bluetooth", "name": "ConnectByDeviceIds", "messageId": "{{STRING}}" }, "payload": { "devices": [ { "uniqueDeviceId": "{{STRING}}" } ] } } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload Parameters
Parameter | Description | Type |
---|---|---|
devices | A list of devices | list |
devices[i].uniqueDeviceId | A universally unique identifier (UUID) generated using the RFC 4122 specification. This UUID identifies the Bluetooth device the client should pair with. Your client must maintain a local mapping between this UUID and the Bluetooth MAC address on the device. | 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 most recent device it previously connected to.
- When a client establishes a connection with the specified device, send the
ConnectByProfileSucceeded
event to AVS. - If the client fails to establish a connection with the specified device, send the
ConnectByProfileFailed
event to AVS.
Use the name
parameter to determine the Bluetooth profile of a device. SOURCE or SINK are the only two supported profiles. For example:
- When a user says, "Alexa, pair my phone." The Bluetooth profile is
A2DP_SOURCE
, since the phone acts as SOURCE. - When a user says "Alexa, pair my speaker." The Bluetooth profile is
A2DP_SINK
, since the speaker acts as SINK. - When a user says, "Alexa, connect to Bluetooth." The Bluetooth profile is
A2DP
, since the device can connect as either SOURCE or SINK.
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. Used to determine the profile type, such as A2DP_SOURCE or A2DP_SINK . |
string |
profile.version | Identifies the profile version. | string |
DisconnectDevices
This directive instructs a client to disconnect from a specified Bluetooth device.
- When a client disconnects from a specified Bluetooth device, send the
DisconnectDevicesSucceeded
event. - If the client fails to establish a connection with the specified device, send the
DisconnectDevicesFailed
event.
Sample Message
{ "directive": { "header": { "namespace": "Bluetooth", "name": "DisconnectDevices", "messageId": "{{STRING}}" }, "payload": { "devices": [ { "uniqueDeviceId": "{{STRING}}" } ] } } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload Parameters
Parameter | Description | Type |
---|---|---|
devices | A list of devices. | list |
devices[i].uniqueDeviceId | A universally unique identifier (UUID) generated using the RFC 4122 specification. This UUID identifies the Bluetooth device the client should pair with. Your client must maintain a local mapping between this UUID and the Bluetooth MAC address on the device. | string |
Events
ScanDevicesReport
This event updates your list of discoverable Bluetooth devices. Send it periodically after receiving a ScanDevices
directive.
discoveredDevices
must contain an object for all discovered device from when the scan initiates. Do not create generate the delta from the previous event.Sample Message
{ "event": { "header": { "namespace": "Bluetooth", "name": "ScanDevicesReport", "messageId": "{{STRING}}" }, "payload": { "discoveredDevices": [ { "uniqueDeviceId": "{{STRING}}", "friendlyName": "{{STRING}}", "truncatedMacAddress": "{{STRING}}", "metadata": { "classOfDevice": {{LONG}}, "vendorId": {{LONG}}, "productId": {{LONG}}, "vendorDeviceSigId": {{LONG}}, "vendorDeviceId": "{{STRING}}" } } ], "hasMore": {{BOOLEAN}} } } }
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 include information about discovered devices. | list |
discoveredDevices[i]. uniqueDeviceId |
A universally unique identifier (UUID) generated to the RFC 4122 specification. Each discovered device should have a UUID. | string |
discoveredDevices[i]. friendlyName |
A friendly name for a discovered device. For example: "My Smart Phone." When unavailable, send an empty string. | string |
discoveredDevices[i]. truncatedMacAddress |
Optional The display name of a device when friendlyName does not exist. Contains the partially masked MAC address associated with the Bluetooth device. Mask the first eight hexadecimal digits with the character X . |
string |
discoveredDevices[i]. metadata |
An object that contains additional details about the Bluetooth device. | object |
discoveredDevices[i]. metadata. classOfDevice |
Required The baseband value in base-10 integer that Bluetooth devices publish. | long |
discoveredDevices[i]. metadata. vendorId |
Optional The vendor ID of the Bluetooth device. |
long |
discoveredDevices[i]. metadata. productId |
Optional The product Id of the Bluetooth device. Set by the manufacturer |
long |
discoveredDevices[i]. metadata. vendorDeviceSigId |
Optional The vendor SigId. |
long |
discoveredDevices[i]. metadata. vendorDeviceId |
Optional The vendor Id. For example, an Amazon UUID in EIR. |
string |
hasMore | Notifies your client of the scan status. Accepted Values: true : the scan did not complete. false : the scan completed. |
boolean |
ScanDevicesFailed
This event checks if a scan operation has failed. If it detects a failure, it clears the list of discovered Bluetooth devices in the companion app. Only send this event after receiving a ScanDevices
directive.
Sample Message
{ "event": { "header": { "namespace": "Bluetooth", "name": "ScanDevicesFailed", "messageId": "{{STRING}}" }, "payload": { "errorCode": {{LONG}} } } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload Parameters
Parameter | Description | Type |
---|---|---|
errorCode | Optional Bluetooth low level error codes. Follows Bluetooth protocol standards. |
long |
Error codes
SetDeviceCategoriesSucceeded
This event informs AVS that the Bluetooth device category successfully updated after receiving the SetDeviceCategories
directive. Send SetDeviceCategoriesSucceeded
after receiving the SetDeviceCategories
directive.
Sample Message
{ "event": { "header": { "namespace": "Bluetooth", "name": "SetDeviceCategoriesSucceeded", "messageId": "{{STRING}}" }, "payload": { "devices": [ { "uniqueDeviceId": "{{STRING}}", "deviceCategory": "{{STRING}}" } ] } } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload Parameters
Parameter | Description | Type |
---|---|---|
devices | A list of devices | list |
devices[i].uniqueDeviceId | A universally unique identifier (UUID) generated using the RFC 4122 specification. | string |
devices[i].deviceCategory | Category of Bluetooth device | string |
SetDeviceCategoriesFailed
This event informs AVS that the Bluetooth device category did not update. Send SetDeviceCategoriesFailed
after receiving the SetDeviceCategories
directive.
Resend all applicable metadata with a this event so AVS can re-determine the device category again. If the device category resolves, AVS sends a new SetDeviceCategories
directive.
{ "event": { "header": { "namespace": "Bluetooth", "name": "SetDeviceCategoriesFailed", "messageId": "{{STRING}}" }, "payload": { "devices": [ { "uniqueDeviceId": "{{STRING}}", "metadata": { "classOfDevice": {{LONG}}, "vendorId": {{LONG}}, "productId": {{LONG}}, "vendorDeviceSigId": {{LONG}}, "vendorDeviceId": "{{STRING}}" } } ] } } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload Parameters
Parameter | Description | Type |
---|---|---|
devices | A list of devices | list |
devices[i]. uniqueDeviceId |
A universally unique identifier (UUID) generated to the RFC 4122 specification. Each discovered device should have a UUID. | string |
devices[i]. friendlyName |
A friendly name for a discovered device. For example: "My Smart Phone." When unavailable, send an empty string. | string |
devices[i]. metadata |
An object that contains additional details about the Bluetooth device. | object |
devices[i]. .metadata. classOfDevice |
Required The baseband value in base-10 integer that Bluetooth devices publish. | long |
devices[i]. metadata.vendorId |
Optional The vendor ID of the Bluetooth device. |
long |
devices[i]. metadata.productId |
Optional The product Id of the Bluetooth device. Set by the manufacturer |
long |
devices[i]. metadata.vendorDeviceSigId |
Optional The vendor SigId. |
long |
devices[i]. metadata.vendorDeviceId |
Optional The vendor Id. For example, an Amazon UUID in EIR |
string |
EnterDiscoverableModeSucceeded
Send this event when your client enters discovery mode.
Sample Message
{ "event": { "header": { "namespace": "Bluetooth", "name": "EnterDiscoverableModeSucceeded", "messageId": "{{STRING}}" }, "payload": {} } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload Parameters
Sends an empty payload.
EnterDiscoverableModeFailed
This event informs AVS that your devices failed to initiate discovery mode after receiving the EnterDiscoverableMode
directive. A failure can occur due to low-level protocol issues or driver issues. Send EnterDiscoverableModeFailed
after the failure occurs.
Sample Message
{ "event": { "header": { "namespace": "Bluetooth", "name": "EnterDiscoverableModeFailed", "messageId": "{{STRING}}" }, "payload": {} } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload Parameters
Sends an empty payload.
PairDevicesSucceeded
This event informs AVS that your devices successfully paired after receiving the PairDevices
directive. Send PairDevicesSucceeded
after the pairing occurs.
Sample Message
{ "event": { "header": { "namespace": "Bluetooth", "name": "PairDevicesSucceeded", "messageId": "{{STRING}}" }, "payload": { "devices": [ { "uniqueDeviceId": "{{STRING}}", "deviceCategory": "{{STRING}}", "friendlyName": "{{STRING}}", "profiles": [ { "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 |
---|---|---|
devices | A list of devices | list |
devices[i].uniqueDeviceId | A universally unique identifier (UUID) generated to the RFC 4122 specification. | string |
devices[i].deviceCategory | Category of Bluetooth device. See context for supported types | string |
devices[i].friendlyName | A friendly name for the device. For example: "My Smart Phone". | string |
devices[i].profiles | A list of profiles on the devices. | list |
devices[i].profiles[j].name | Bluetooth Profile. See |
string |
devices[i].profiles[j].version | Bluetooth Profile Version | string |
PairDevicesFailed
Send this event when your client fails to pair with a peer Bluetooth device.
Sample Message
{ "event": { "header": { "namespace": "Bluetooth", "name": "PairDevicesFailed", "messageId": "{{STRING}}" }, "payload": { "devices": [ { "uniqueDeviceId": "{{STRING}}", "errorCode": {{LONG}} } ] } } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload Parameters
Parameter | Description | Type |
---|---|---|
devices | A list of devices | list |
devices[i].uniqueDeviceId | A universally unique identifier (UUID) generated using the RFC 4122 specification. | string |
devices[i].errorCode | Optional Bluetooth low level error codes. Follows Bluetooth protocol standard. See the ScanDevicesFailed event for error code descriptions |
long |
UnpairDevicesSucceeded
This event informs AVS when a client successfully pairs with a device. Send UnpairDevicesSucceeded
after the success occurs.
Sample Message
{ "event": { "header": { "namespace": "Bluetooth", "name": "UnpairDevicesSucceeded", "messageId": "{{STRING}}" }, "payload": { "devices": [ { "uniqueDeviceId": "{{STRING}}" } ] } } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload Parameters
Parameter | Description | Type |
---|---|---|
devices | A list of devices | list |
devices[i].uniqueDeviceId | A universally unique identifier (UUID) generated using the RFC 4122 specification. | string |
UnpairDevicesFailed
This event informs AVS when a client fails to unpair with a Bluetooth device. Send UnpairDevicesFailed
after the failure occurs.
Sample Message
{ "event": { "header": { "namespace": "Bluetooth", "name": "UnpairDevicesFailed", "messageId": "{{STRING}}" }, "payload": { "devices": [ { "uniqueDeviceId": "{{STRING}}", "errorCode": "{{STRING}}" } ] } } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload Parameters
Parameter | Description | Type |
---|---|---|
devices | A list of devices | list |
devices[i].uniqueDeviceId | A universally unique identifier (UUID) generated using the RFC 4122 specification. | string |
devices[i].errorCode | Optional Bluetooth low level error codes. Follows Bluetooth protocol standard. See the ScanDevicesFailed event for error code descriptions |
long |
ConnectByDeviceIdsSucceeded
This event informs AVS that a client established a connection with a paired Bluetooth device using its uniqueDeviceId
as an identifier. Send ConnectByDeviceIdsSucceeded
after successfully connecting
Sample Message
{ "event": { "header": { "namespace": "Bluetooth", "name": "ConnectByDeviceIdsSucceeded", "messageId": "{{STRING}}" }, "payload": { "devices": [ { "uniqueDeviceId": "{{STRING}}", "friendlyName": "{{STRING}}" } ], "requester": "{{STRING}}" } } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload Parameters
Parameter | Description | Type |
---|---|---|
devices | A list of devices | object |
devices[i].uniqueDeviceId | A universally unique identifier (UUID) generated using the RFC 4122 specification. | string |
devices[i].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 a user interaction with the device triggered the event. - CLOUD indicates that AVS sent the event. |
string |
ConnectByDeviceIdsFailed
This event informs AVS that a client failed to establish a connection with a paired Bluetooth device using its uniqueDeviceId
as an identifier. Send ConnectByDeviceIdsFailed
after the failure occurs.
Sample Message
{ "event": { "header": { "namespace": "Bluetooth", "name": "ConnectByDeviceIdsFailed", "messageId": "{{STRING}}" }, "payload": { "devices": [ { "uniqueDeviceId": "{{STRING}}", "friendlyName": "{{STRING}}", "errorCode": {{LONG}} } ], "requester": "{{STRING}}" } } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload Parameters
Parameter | Description | Type |
---|---|---|
devices | A list of devices | list |
devices[i].uniqueDeviceId | A universally unique identifier (UUID) generated using the RFC 4122 specification. | string |
devices[i].friendlyName | A friendly name for the device. For example: "My Smart Phone". | string |
devices[i].errorCode | Optional Bluetooth low level error codes. Follows Bluetooth protocol standard. See the ScanDevicesFailed event for error code descriptions |
long |
requester | Identifies the initiator of the connection request. Accepted values: DEVICE or CLOUD . - DEVICE indicates that a user interaction with the device triggered the event. - CLOUD indicates that AVS sent the event. |
string |
ConnectByProfileSucceeded
This event informs AVS that a client established a connection with a paired Bluetooth device using the profile
provided in the ConnectByProfile
directive. Send ConnectByProfileSucceeded
after the connection succeeds.
Sample Message
{ "event": { "header": { "namespace": "Bluetooth", "name": "ConnectByProfileSucceeded", "messageId": "{{STRING}}" }, "payload": { "device": { "uniqueDeviceId": "{{STRING}}", }, "profileName": "{{STRING}}", "requester": "{{STRING}}" } } }
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 using the RFC 4122 specification. | string |
requester | Identifies the initiator of the connection request. Accepted values: DEVICE or CLOUD . - DEVICE indicates that a user interaction with the device triggered the event. - CLOUD indicates that AVS sent the event. |
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 informs AVS that a client failed to establish a connection with a paired Bluetooth device using the profile
provided in the ConnectByProfile
directive. Send ConnectByProfileFailed
after the failure occurs.
Sample Message
{ "event": { "header": { "namespace": "Bluetooth", "name": "ConnectByProfileFailed", "messageId": "{{STRING}}" }, "payload": { "requester": "{{STRING}}", "profileName": "{{STRING}}", "errorCode": {{LONG}} } } }
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 a user interaction with the device triggered the event. - CLOUD indicates that AVS sent the event. . |
string |
profileName | The profile name associated with the connected device. This parameter should match the profile.name provided in the ConnectByProfile . |
string |
errorCode | Optional Bluetooth low level error codes. Follows Bluetooth protocol standard. See the ScanDevicesFailed event for error code descriptions |
long |
DisconnectDevicesSucceeded
This event informs AVS that a client disconnected from a paired Bluetooth device, after receiving a DisconnectDevices
directive. Send DisconnectDevicesSucceeded
after the disconnection succeeds.
Sample Message
{ "event": { "header": { "namespace": "Bluetooth", "name": "DisconnectDevicesSucceeded", "messageId": "{{STRING}}" }, "payload": { "devices": [ { "uniqueDeviceId": "{{STRING}}", "friendlyName": "{{STRING}}" } ], "requester": "{{STRING}}" } } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload Parameters
Parameter | Description | Type |
---|---|---|
devices | A list of devices | list |
devices[i].uniqueDeviceId | A universally unique identifier (UUID) generated using the RFC 4122 specification. | string |
devices[i].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 a user interaction with the device triggered the event. - CLOUD indicates that AVS sent the event. |
string |
DisconnectDevicesFailed
This event informs AVS that a client failed to disconnect from a paired Bluetooth device, after receiving a DisconnectDevice
directive. Send DisconnectDevicesFailed
after the disconnection fails.
Sample Message
{ "event": { "header": { "namespace": "Bluetooth", "name": "DisconnectDevicesFailed", "messageId": "{{STRING}}" }, "payload": { "devices": [ { "uniqueDeviceId": "{{STRING}}", "friendlyName": "{{STRING}}", "errorCode": {{LONG}} } ], "requester": "{{STRING}}" } } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload Parameters
Parameter | Description | Type |
---|---|---|
devices | A list of devices | list |
devices[i].uniqueDeviceId | A universally unique identifier (UUID) generated using the RFC 4122 specification. | string |
devices[i].friendlyName | A friendly name for the device. For example: "My Smart Phone". | string |
devices[i].errorCode | Optional Bluetooth low level error codes. Follows Bluetooth protocol standard. See the ScanDevicesFailed event for error code descriptions |
long |
requester | Identifies the initiator of the connection request. Accepted values: DEVICE or CLOUD . - DEVICE indicates that a user interaction with the device triggered the event. - CLOUD indicates that AVS sent the event. |
string |
StreamingStarted
This event informs AVS that the Bluetooth streaming state of a connected device has started. Send StreamingStarted
when the following state changes occur:
- The Bluetooth streaming state of a connected device changes from
INACTIVE
toACTIVE
- The Bluetooth streaming state of a connected device changes from
PAUSED
toACTIVE
{ "event": { "header": { "namespace": "Bluetooth", "name": "StreamingStarted", "messageId": "{{STRING}}" }, "payload": { "device": { "uniqueDeviceId": "{{STRING}}", "profileName": "{{STRING}" } } } }
Payload Parameters
Parameter | Description | Type |
---|---|---|
device | Includes information about the device. | object |
device.uniqueDeviceId | A universally unique identifier (UUID) generated using the RFC 4122 specification. Each discovered device should have a UUID. | string |
device.profileName | The profile name associated with the connected device. This should match the profile.name provided in the ConnectByProfile directive. |
string |
StreamingEnded
This event informs AVS that the Bluetooth streaming state of a connected device has stopped. Send the StreamingEnded
event when the Bluetooth state changes from ACTIVE to PAUSED.
{ "event": { "header": { "namespace": "Bluetooth", "name": "StreamingEnded", "messageId": "{{STRING}}" }, "payload": { "device": { "uniqueDeviceId": "{{STRING}}", "profileName": "{{STRING}}" } } } }
Parameter | Description | Type |
---|---|---|
device | Includes information about the device. | object |
device.uniqueDeviceId | A universally unique identifier (UUID) generated using the RFC 4122 specification. Each discovered device should have a UUID. | string |
device.profileName | The profile name associated with the connected device. This should match the profile.name provided in the ConnectByProfile directive. |
string |
MediaControlPlaySucceeded
This event informs AVS that a connected Bluetooth device started audio playback. Send the MediaControlPlaySucceeded
event after the A2DP source handles the Play
directive.
Sample Message
{ "event": { "header": { "namespace": "Bluetooth", "name": "MediaControlPlaySucceeded", "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 | Includes information about the device. | object |
device.uniqueDeviceId | A universally unique identifier (UUID) generated using the RFC 4122 specification. Each discovered device should have a UUID. | string |
MediaControlPlayFailed
This event informs AVS that a connected Bluetooth device failed to start audio playback. Send the MediaControlPlayFailed
event after the A2DP source fails to handles the Play
directive.
Sample Message
{ "event": { "header": { "namespace": "Bluetooth", "name": "MediaControlPlayFailed", "messageId": "{{STRING}}" }, "payload": { "device": { "uniqueDeviceId": "{{STRING}}" }, "errorCode": {{LONG}} } } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload Parameters
Parameter | Description | Type |
---|---|---|
device | Includes information about the device. | object |
device.uniqueDeviceId | A universally unique identifier (UUID) generated using the RFC 4122 specification. Each discovered device should have a UUID. | string |
errorCode | Optional Bluetooth low level error codes. Follows Bluetooth protocol standard. See the ScanDevicesFailed event for error code descriptions |
long |
MediaControlStopSucceeded
This event informs AVS that the A2DP source successfully handled the Stop
directive.
Sample Message
{ "event": { "header": { "namespace": "Bluetooth", "name": "MediaControlStopSucceeded", "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 | Includes information about the device. | object |
device.uniqueDeviceId | A universally unique identifier (UUID) generated using the RFC 4122 specification. Each discovered device should have a UUID. | string |
MediaControlStopFailed
This event informs AVS that the Stop
directive failed to stop Media Playback on the A2DP source.
Sample Message
{ "event": { "header": { "namespace": "Bluetooth", "name": "MediaControlStopFailed", "messageId": "{{STRING}}" }, "payload": { "device": { "uniqueDeviceId": "{{STRING}}" }, "errorCode": {{LONG}} } } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload Parameters
Parameter | Description | Type |
---|---|---|
device | Includes information about the device. | object |
device.uniqueDeviceId | A universally unique identifier (UUID) generated using the RFC 4122 specification. Each discovered device should have a UUID. | string |
errorCode | Optional Bluetooth low level error codes. Follows Bluetooth protocol standard. See the ScanDevicesFailed event for error code descriptions |
long |
MediaControlNextSucceeded
This event informs AVS that the A2DP source successfully handled the Next
directive. Send the MediaControlNextSucceeded
event after the success occurs.
Sample Message
{ "event": { "header": { "namespace": "Bluetooth", "name": "MediaControlNextSucceeded", "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 | Includes information about the device. | object |
device.uniqueDeviceId | A universally unique identifier (UUID) generated using the RFC 4122 specification. Each discovered device should have a UUID. | string |
MediaControlNextFailed
This event informs AVS that the A2DP source failed to handle the Next
directive. Send the MediaControlNextFailed
event after the failure occurs.
Sample Message
{ "event": { "header": { "namespace": "Bluetooth", "name": "MediaControlNextFailed", "messageId": "{{STRING}}" }, "payload": { "device": { "uniqueDeviceId": "{{STRING}}" }, "errorCode": {{LONG}} } } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload Parameters
Parameter | Description | Type |
---|---|---|
device | Includes information about the device. | object |
device.uniqueDeviceId | A universally unique identifier (UUID) generated using the RFC 4122 specification. Each discovered device should have a UUID. | string |
errorCode | Optional Bluetooth low level error codes. Follows Bluetooth protocol standard. See the ScanDevicesFailed event for error code descriptions |
long |
MediaControlPreviousSucceeded
This event informs AVS that the A2DP source processed the previous
directive. Send the MediaControlPreviousSucceeded
event after the success occurs.
Sample Message
{ "event": { "header": { "namespace": "Bluetooth", "name": "MediaControlPreviousSucceeded", "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 | Includes information about the device. | object |
device.uniqueDeviceId | A universally unique identifier (UUID) generated using the RFC 4122 specification. Each discovered device should have a UUID. | string |
MediaControlPreviousFailed
This event informs AVS if the A2DP source fails to handle the Previous
directive.
Sample Message
{ "event": { "header": { "namespace": "Bluetooth", "name": "MediaControlPreviousFailed", "messageId": "{{STRING}}" }, "payload": { "device": { "uniqueDeviceId": "{{STRING}}" }, "errorCode": {{LONG}} } } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload Parameters
Parameter | Description | Type |
---|---|---|
device | Includes information about the device. | object |
device.uniqueDeviceId | A universally unique identifier (UUID) generated using the RFC 4122 specification. Each discovered device should have a UUID. | string |
errorCode | Optional Bluetooth low level error codes. Follows Bluetooth protocol standard. See the ScanDevicesFailed event for error code descriptions |
long |
Last updated: Dec 17, 2020