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
capabilities
when they are asserted.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 |