System 1

The System interface exposes directives and events to enable the inter-process communication (IPC) client to control basic system level operations of the Alexa client, usually those implemented with the System AVS API.

{
    "namespace": "System",
    "version": 1
}

Directives

Outbound messages about the changes at the system level of the Alexa client.

completeAuthorization

Provides the IPC client with information to implement Code-Based Linking (CBL) authorization flows like the examples in Devices with screens/code-based linking.

Example message

{
    "header": {
        "version": 1
        "namespace": "System",
        "name": "completeAuthorization"
    },
    "payload": {
        "url": "{{STRING}}",
        "code": "{{STRING}}"
        "clientId": "{{STRING}}"
    }
}
 

Payload parameters

Parameter Description Type
url URL for the customer to use to complete CBL Login With Amazon (LWA) authorization. string
code CBL code to use to complete authorization. string
clientId AVS Client Id. string

setAlexaState

Informs the IPC client of changes in the state of the Alexa client connection. This directive is useful for implementation of an Alexa Attention System.

Example message

{
    "header": {
        "version": 1
        "namespace": "System",
        "name": "setAlexaState"
    },
    "payload": {
        "state": "{{STRING}}"
    }
}
 

Payload parameters

Parameter Description Type
state Enumerated state of the Alexa client. Valid values:
UNKNOWN
DISCONNECTED
CONNECTING
CONNECTED
IDLE
LISTENING
EXPECTING
THINKING
SPEAKING

setAuthorizationState

Informs the IPC client of changes in Alexa authorization state.

Example message

{
    "header": {
        "version": 1
        "namespace": "System",
        "name": "setAuthorizationState"
    },
    "payload": {
        "state": "{{STRING}}"
    }
}
 

Payload parameters

Parameter Description Type
state Enumerated authorization state. Valid Values:
UNINITIALIZED
REFRESHED
EXPIRED
ERROR
AUTHORIZING

setLocales

Informs the IPC client of the supported locales for the Alexa client.

Example message

{
    "header": {
        "version": 1
        "namespace": "System",
        "name": "setLocales"
    },
    "payload": {
        "locales": [
            "{{STRING}}",
            ...
        ]
    }
}
 

Payload parameters

Parameter Description Type
locales The locale(s) for the client. In single-locale mode, it contains one locale string. In multi-locale mode, the first string indicates the primary locale, and any other strings correspond to secondary locales. array
locales[0] primary locale. BCP-47 string
locales[i] For i > 0, it indicates the secondary locale(s) for the client, which informs the client which secondary locales Alexa is listening for in user utterances. BCP-47 string

Events

Inbound messages from the IPC client about system operations.

alexaStateRequest

Send this event to request the native client to return the Alexa state through the setAlexaState directive.

Example message

{
    "header": {
        "version": 1
        "namespace": "System",
        "name": "alexaStateRequest"
    },
    "payload": {}
}

Payload parameters

The payload is an empty object.

authorizationInfoRequest

Send this event to request the native client to return the authorization information through the completeAuthorization directive.

Example message

{
    "header": {
        "version": 1
        "namespace": "System",
        "name": "authorizationInfoRequest"
    },
    "payload": {}
}

authorizationStateRequest

Send this event to request the native client to return the authorization state through the setAuthorizationState directive.

Example message

{
    "header": {
        "version": 1
        "namespace": "System",
        "name": "authorizationStateRequest"
    },
    "payload": {}
}

Payload parameters

The payload is an empty object.

localesRequest

Send this event to request the native client to return the supported locales through the setLocales directive.

Example message

{
    "header": {
        "version": 1
        "namespace": "System",
        "name": "localesRequest"
    },
    "payload": {}
}

Payload parameters

The payload is an empty object.