Alexa.ApiGateway 1.0

The Alexa.ApiGateway interface allows the device and cloud to coordinate on the correct URI endpoint for the device to connect to. For example, this may be required for the device to match the user's regional settings.

This interface replaces the SetEndpoint functionality that was removed from the System interface in version 2.0.

Capability assertion

The Alexa.ApiGateway capability may only be implemented by the device maintaining the HTTP/2 connection to AVS on its own behalf. The capability interface cannot be implemented on behalf of connected endpoints.

Sample Object

{
  "type": "AlexaInterface",
  "interface": "Alexa.ApiGateway",
  "version": "1.0"
}

Events

VerifyGateway

The device must send the VerifyGateway event to Alexa immediately after establishing an HTTP/2 connection for the first time, before sending an AddOrUpdateReport capability assertion or any other events of other interfaces. The AddOrUpdateReport event documentation details other circumstances under which the VerifyGateway event must be sent. This event functions as a request to Alexa to validate whether the connected-to URI endpoint is correct.

If Alexa detects that the connected-to URI endpoint is incorrect, the device will receive a SetGateway directive with the updated endpoint.

If no change is required, the device will receive an empty HTTP 204 on the event stream.

Sample Message

{
  "directive": {
    "header": {
      "namespace": "Alexa.ApiGateway",
      "name": "VerifyGateway",
      "messageId": "{{STRING}}"
    },
    "payload": {
    }
  }
}

Header Parameters

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

Directives

SetGateway

The SetGateway directive will be sent by Alexa to the device in response to the VerifyGateway event to instruct it to update what URI endpoint it is connected to, if necessary.

Sample Message

{
  "directive": {
    "header": {
      "namespace": "Alexa.ApiGateway",
      "name": "SetGateway",
      "messageId": "{{STRING}}"
    },
    "payload": {
      "gateway": "{{STRING}}"
    }
  }
}

Header Parameters

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

Payload Parameters

Parameter Description Type
gateway The URI endpoint the device must connect to for sending events to Alexa.

Possible Values: those in the "Base URLs" list

Example Value: https://alexa.na.gateway.devices.a2z.com 		URI string