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

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

Click to enlarge

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.

Bluetooth State Diagram
Click to enlarge
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.

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.

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.

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.

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.

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.

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.

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.

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.

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 for supported types 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 to ACTIVE
  • The Bluetooth streaming state of a connected device changes from PAUSED to ACTIVE
{
  "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

Was this page helpful?

Last updated: Nov 27, 2023