Connection Management

Note: Register now for Alexa Live, Amazon’s annual Alexa developer conference on July 20, 2022.

After establishing an AWS IoT connection, your device must establish a connection with AIA using the connection topic's connection/fromclient and connection/fromservice sub-topics. Only then can your device exchange messages on any other AIA-specific MQTT topic to manifest an Alexa experience for end users.

AIA connections are maintained until closed by either the device or by AIA. While the connection is open, the device must remain subscribed to the directive and connection/fromservice topics, as well as any other topics required by asserted capabilities (for example, the speaker topic, if the Speaker capability is asserted).

Note: Messages sent on the connection/fromclient and connection/fromservice topics are secured through AWS IAM permissions associated with your AWS account. The JSON data exchanged on them does not use AIA encryption, though it is secured through TLS over MQTT. Consequently, it also is not preceded by the common header.

Getting Started
- AIA Envelope
- Topic Management
connection/fromclient Topic
- Connect

Getting Started

AIA Envelope

Connection management is presently compatible with v1 of the AIA envelope.

Topic Management

To support connection messages, the device must participate in the connection/fromclient and connection/fromservice MQTT topics, which are nested under the connection topic.

`connection/fromclient` Topic

Connect

The device sends the Connect message to AIA to establish a connection.

If AIA receives and attempts to process the message, it will reply with the Acknowledge message on the connection/fromservice topic. This applies to both successes and failures.

Sample Message

{
  "header": {
    "name": "Connect",
    "messageId": "{{STRING}}"
  },
  "payload": {
    "awsAccountId": "{{STRING}}",
    "clientId": "{{STRING}}"
    "version": "{{STRING}}"
  }
}

Payload Parameters

{
  "header": {
    "name": "Disconnect",
    "messageId": "{{STRING}}"
  },
  "payload": {
    "code": "{{STRING}}",
    "description": "{{STRING}}"
  }
}

</tr> </table> ### Disconnect {#fromclient-disconnect} The device may choose to disconnect gracefully by sending the `Disconnect` message to AIA. AIA will not respond with any acknowledgement. This only terminates the AIA connection, not the AWS IoT connection. The client ID of the device will be inferred from the fully qualified MQTT topic. **Note**: AIA may also initiate disconnecting a device by sending a [`Disconnect`](#fromservice-disconnect) message on the `connection/fromservice` topic. **Sample Message** **Payload Parameters**

Field Name	Description	Value Type
`awsAccountId`	The AWS account ID that the device is connected to. This must be the same as the `iot.awsAccountId` declared during registration.	string
`clientId`	The AWS IoT `clientId` the device uses to connected to AWS IoT. This must be the same as the `iot.clientId` declared during registration.	string
`version`	Connection request version. Optional. Accepted values are "1.0" or "1.1". Default is "1.0". Use connection request version 1.1 to receive the disconnect code `AUTHENTICATION_ERROR` for expired AVS tokens.	string

Field Name	Description	Value Type
`code`	A code indicating the reason for disconnecting. Accepted Values: `UNEXPECTED_SEQUENCE_NUMBER`: A message with an unexpected sequence number was received. Opening a new connection should resolve this issue. `MESSAGE_TAMPERED`: The unencrypted and decrypted sequence numbers of the common header do not match, indicating a potential replay attack. `ENCRYPTION_ERROR`: There was an error encrypting or decrypting an AIA message using the shared secret. `GOING_OFFLINE`: The device is going offline for any other reason.	string
`description`	The device may optionally provide additional information about the reason for disconnecting for logging and troubleshooting.	string

## `connection/fromservice` Topic ### Acknowledge AIA sends the `Acknowledge` message on the `connection/fromservice` topic in response to a [`Connect`](#connect) message on the `connection/fromclient` topic. **Sample Message**

{
  "header": {
    "name": "Acknowledge",
    "messageId": "{{STRING}}"
  },
  "payload": {
    "connectMessageId": "{{STRING}}",
    "code": "{{STRING}}",
    "description": "{{STRING}}"
  }
}

**Payload Parameters**

Field Name	Description	Value Type
`connectMessageId`	The `messageId` from the `Connect` message, returned verbatim.	string
`code`	A code indicating the success or failure of the connection request. Possible Values: `CONNECTION_ESTABLISHED`: The device has been successfully connected to AIA and may begin exchanging message over other MQTT topics. `INVALID_ACCOUNT_ID`: The `awsAccountId` provided in the `Connect` message is not valid. The device must correct the value before retrying. `INVALID_CLIENT_ID`: The `clientId` provided in the `Connect` message is not valid. The device must correct the value before retrying. `API_VERSION_DEPRECATED`: The API version in the fully qualified MQTT topic on which this message was sent has been deprecated. The device must use a more recent version, consistent with a successful registration. `UNKNOWN_FAILURE`: An unexpected issue occurred that prevented AIA from opening the connection. This may be a server side failure, and the same `Connect` message may be retried.	string
`description`	AIA may optionally provide additional information about the connection attempt for logging and troubleshooting.	string

### Disconnect {#fromservice-disconnect} AIA may choose to disconnect a device gracefully by sending the `Disconnect` message. The device does not respond with any acknowledgement. This only terminates the AIA connection, not the AWS IoT connection. The client ID of the device will be inferred from the fully qualified MQTT topic. **Note**: The device may also initiate disconnecting from AIA by sending a [`Disconnect`](#fromclient-disconnect) message on the `connection/fromclient` topic. **Sample Message**

{
  "header": {
    "name": "Disconnect",
    "messageId": "{{STRING}}"
  },
  "payload": {
    "code": "{{STRING}}",
    "description": "{{STRING}}"
  }
}