Thank you for your visit. This page is only available in English at this time.

Alexa.ApiGateway Interface (v1.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.

Capabilities API

To use version 1.0 of the Alexa.ApiGateway interface, it must be declared in your call to the Capabilities API.

Sample Object

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

VerifyGateway Event

The device must send the VerifyGateway event to Alexa immediately after a successful call to the Capabilities API, before sending any other events of other interfaces. 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

SetGateway Directive

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