Your Alexa Dashboards Settings

(Developer Preview) Bluetooth Interface

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-SOURCE, A2DP-SINK, and AVRCP.

  • A2DP-SOURCE - Originates content, such as streaming audio.
  • A2DP-SINK - Receives content, such as streaming audio.
  • AVRCP - 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 paired 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 paired 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 expand

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.

Bluetooth.BluetoothState

Sample Context

{
  "header": {
    "namespace": "Bluetooth",
    "name": "BluetoothState"
  },
  "payload": {
    "alexaDevice": {
      "friendlyName": "{{STRING}}",
    },
    "pairedDevices": [
      {
        "uniqueDeviceId": "{{STRING}}",
        "friendlyName": "{{STRING}}",
        "supportedProfiles": [
          {
            "name": "{{STRING}}",
            "version": "{{STRING}}"
          },
          {
            ...
          }
        ],
      },
      {
        ...
        ...
      }
    ],  
    "activeDevice": {
      "uniqueDeviceId": "{{STRING}}",
      "friendlyName": "{{STRING}}",
      "supportedProfiles": [
        {
          "name": "{{STRING}}",
          "version": "{{STRING}}"
        },
        {
          ...
        }
      ],
      "streaming": "{{STRING}}"
    }
  }
}

{
    "header": {
        "namespace": "Bluetooth",
        "name": "BluetoothState",
    },
    "payload": {
        "alexaDevice": {
            "friendlyName": "Echo-0ST",
        },
        "pairedDevices": [
            {
                // This identifies Kelly's Phone as a paired device
                // that supports two profiles.
                "uniqueDeviceID": "353088131600891",
                "friendlyName": "Kelly's Phone",
                "supportedProfile":[
                    {
                        "name" : "A2DP-SOURCE",
                        "version" : "1.3"
                    },
                    {
                        "name" : "AVRCP",
                        "version" : "1.0"
                    }
                ],
            },
        ],
        // This identifies the connected device and its supported
        // profiles.
        "activeDevice": {
           "uniqueDeviceID": "367388087352897",
           "friendlyName": "AVS Device 1",
           "supportedProfile":[
                {
                    "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 Provides the device 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. A device is not active if paired but not connected. 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 Provides the device 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 paired, but before any content has been streamed.
ACTIVE This is the streaming state of an activeDevice that is playing audio to/from a paired Bluetooth device.
PAUSED This is the streaming state when audio playback to/from a paired 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 “Alexa, play music by Artist.” / “Alexa, play music from my phone.” Stream content ACTIVE
ACTIVE “Alexa, pause.” / “Alexa, pause music from my phone.” PAUSED  
PAUSED “Alexa, resume.” / “Alexa, resume music from my phone.” ACTIVE  

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 Provides the device 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

Media Control via Bluetooth

These directives and events are used to navigate playback when a paired Bluetooth device is set as A2DP-SOURCE and Alexa-enabled product is A2DP-SINK. For example, a smart phone. When a paired Bluetooth device is set as A2DP-SINK, your client will receive directives from the AudioPlayer interface.

User Request Streaming State / Behavior SOURCE SINK
“Alexa, play.” INACTIVE or PAUSED Bluetooth.Play 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. Bluetooth.Next AudioPlayer.Play
“Alexa, previous.” If ACTIVE, two Bluetooth.Previous directives are sent. If INACTIVE or PAUSED, then two Bluetooth.Next directives are sent, followed by Bluetooth.Play. Bluetooth.Previous AudioPlayer.Play

Play Directive

This directive instructs the A2DP-SOURCE to initiate playback on the paired 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 paired 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 paired 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 paired 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.