Bluetooth

The Bluetooth interface exposes directives and events for establishing and managing connections with external Bluetooth devices, such as Alexa-enabled gadgets or Bluetooth-enabled speakers.

    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

    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"
        ]
      }
    }
    

    Bluetooth 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

    Manage a Bluetooth connection

    The following directives and events manage a Bluetooth connection between an Alexa Built-in product and peer Bluetooth devices.

    ScanDevices directive

    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.

    ScanDevicesReport event

    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 event

    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

    SetDeviceCategories directive

    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

    SetDeviceCategoriesSucceeded event

    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 event

    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

    EnterDiscoverableMode directive

    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

    EnterDiscoverableModeSucceeded event

    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 event

    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.

    ExitDiscoverableMode directive

    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 directive

    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

    PairDevicesSucceeded event

    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 event

    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

    UnpairDevices directive

    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

    UnpairDevicesSucceeded event

    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 event

    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

    ConnectByDeviceIds directive

    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

    ConnectByDeviceIdsSucceeded event

    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 event

    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

    ConnectByProfile directive

    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

    ConnectByProfileSucceeded event

    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 event

    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

    DisconnectDevices directive

    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

    DisconnectDevicesSucceeded event

    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 event

    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

    Manage Bluetooth streaming state

    Send these events to AVS when Bluetooth streaming starts or ends.

    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.

    StreamingStarted event

    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 event

    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

    Media controls directives

    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

    Play directive

    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

    MediaControlPlaySucceeded event

    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 event

    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

    Stop directive

    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

    MediaControlStopSucceeded event

    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 event

    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

    Next directive

    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

    MediaControlNextSucceeded event

    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 event

    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

    Previous directive

    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

    MediaControlPreviousSucceeded event

    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 event

    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
    Warning: Version 1.0 is not the current version of the Bluetooth interface.

    The Bluetooth interface exposes directives and events for establishing and managing connections with external Bluetooth devices, such as Alexa-enabled gadgets or Bluetooth-enabled speakers.

      Overview

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

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

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

      Supported use cases:

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

      Sequence Diagrams

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

      This set of sequence diagrams illustrate interactions initiated via voice.

      Pair a Bluetooth device using voice

      Click to enlarge

      Capability Assertion

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

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

      Sample Object

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

      Bluetooth Context

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

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

      Sample Context

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

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

      Payload Parameters

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

      Streaming State

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

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

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

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

      Manage a Bluetooth Connection

      These directives and events are used to manage a Bluetooth connection between an Alexa Built-in product and peer Bluetooth devices.

      ScanDevices Directive

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

      Sample Message

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

      Header Parameters

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

      Payload Parameters

      This directive has an empty payload.

      ScanDevicesUpdated Event

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

      Sample Message

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

      Context

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

      Header Parameters

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

      Payload Parameters

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

      ScanDevicesFailed Event

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

      Sample Message

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

      Context

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

      Header Parameters

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

      Payload Parameters

      An empty payload is sent.

      EnterDiscoverableMode Directive

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

      Sample Message

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

      Header Parameters

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

      Payload Parameters

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

      EnterDiscoverableModeSucceeded Event

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

      Sample Message

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

      Context

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

      Header Parameters

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

      Payload Parameters

      An empty payload is sent.

      EnterDiscoverableModeFailed Event

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

      Sample Message

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

      Context

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

      Header Parameters

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

      Payload Parameters

      An empty payload is sent.

      ExitDiscoverableMode Directive

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

      Sample Message

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

      Header Parameters

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

      Payload Parameters

      This directive has an empty payload.

      PairDevice Directive

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

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

      Sample Message

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

      Header Parameters

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

      Payload Parameters

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

      PairDeviceSucceeded Event

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

      Sample Message

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

      Context

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

      Header Parameters

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

      Payload Parameters

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

      PairDeviceFailed Event

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

      Sample Message

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

      Context

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

      Header Parameters

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

      Payload Parameters

      An empty payload is sent.

      UnpairDevice Directive

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

      Sample Message

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

      Header Parameters

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

      Payload Parameters

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

      UnpairDeviceSucceeded Event

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

      Sample Message

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

      Context

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

      Header Parameters

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

      Payload Parameters

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

      UnpairDeviceFailed Event

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

      Sample Message

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

      Context

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

      Header Parameters

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

      Payload Parameters

      An empty payload is sent.

      ConnectByDeviceId Directive

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

      Sample Message

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

      Header Parameters

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

      Payload Parameters

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

      ConnectByDeviceIdSucceeded Event

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

      Sample Message

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

      Context

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

      Header Parameters

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

      Payload Parameters

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

      ConnectByDeviceIdFailed Event

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

      Sample Message

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

      Context

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

      Header Parameters

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

      Payload Parameters

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

      ConnectByProfile Directive

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

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

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

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

      Sample Message

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

      Header Parameters

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

      Payload Parameters

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

      ConnectByProfileSucceeded Event

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

      Sample Message

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

      Context

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

      Header Parameters

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

      Payload Parameters

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

      ConnectByProfileFailed Event

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

      Sample Message

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

      Context

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

      Header Parameters

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

      Payload Parameters

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

      DisconnectDevice Directive

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

      Sample Message

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

      Header Parameters

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

      Payload Parameters

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

      DisconnectDeviceSucceeded Event

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

      Sample Message

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

      Context

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

      Header Parameters

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

      Payload Parameters

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

      DisconnectDeviceFailed Event

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

      Sample Message

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

      Context

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

      Header Parameters

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

      Payload Parameters

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

      Manage Bluetooth Streaming State

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

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

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

      StreamingStarted Event

      This event is sent to Alexa when:

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

      Payload Parameters

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

      StreamingEnded Event

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

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

      Media Controls via Bluetooth

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

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

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

      Play Directive

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

      Sample Message

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

      Header Parameters

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

      Payload Parameters

      This directive has an empty payload.

      MediaControlPlaySucceeded Event

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

      Sample Message

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

      Context

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

      Header Parameters

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

      Payload Parameters

      An empty payload is sent.

      MediaControlPlayFailed Event

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

      Sample Message

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

      Context

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

      Header Parameters

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

      Payload Parameters

      An empty payload is sent.

      Stop Directive

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

      Sample Message

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

      Header Parameters

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

      Payload Parameters

      This directive has an empty payload.

      MediaControlStopSucceeded Event

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

      Sample Message

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

      Context

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

      Header Parameters

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

      Payload Parameters

      An empty payload is sent.

      MediaControlStopFailed Event

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

      Sample Message

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

      Context

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

      Header Parameters

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

      Payload Parameters

      An empty payload is sent.

      Next Directive

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

      Sample Message

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

      Header Parameters

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

      Payload Parameters

      This directive has an empty payload.

      MediaControlNextSucceeded Event

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

      Sample Message

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

      Context

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

      Header Parameters

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

      Payload Parameters

      An empty payload is sent.

      MediaControlNextFailed Event

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

      Sample Message

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

      Context

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

      Header Parameters

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

      Payload Parameters

      An empty payload is sent.

      Previous Directive

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

      Sample Message

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

      Header Parameters

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

      Payload Parameters

      An empty payload is sent.

      MediaControlPreviousSucceeded Event

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

      Sample Message

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

      Context

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

      Header Parameters

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

      Payload Parameters

      An empty payload is sent.

      MediaControlPreviousFailed Event

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

      Sample Message

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

      Context

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

      Header Parameters

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

      Payload Parameters

      An empty payload is sent.