Context
Context communicates the state of the device client components to the Alexa Voice Service (AVS). A context object reflects the state of client components immediately before its associated event is sent.
For example, consider a scenario where the device is playing an audio stream, and a user interrupts that stream to make a speech request. When the client sends the Recognize
event to AVS, the included context should reflect that an audio stream was playing by sending the PlaybackState
context entry with the appropriate playerActivity
value.
Example
The following example illustrates SpeechRecognizer's Recognize
event with attached context
:
{ "context": [ { "header": { "namespace": "AudioPlayer", "name": "PlaybackState" }, "payload": { "token": "{{STRING}}", "offsetInMilliseconds": {{LONG}}, "playerActivity": "{{STRING}}" } }, { "header": { "namespace": "SpeechRecognizer", "name": "RecognizerState" }, "payload": { "wakeword": "ALEXA" } }, { "header": { "namespace": "Notifications", "name": "IndicatorState" }, "payload": { "isEnabled": {{BOOLEAN}}, "isVisualIndicatorPersisted": {{BOOLEAN}} } }, { "header": { "namespace": "Alerts", "name": "AlertsState" }, "payload": { "allAlerts": [ { "token": "{{STRING}}", "type": "{{STRING}}", "scheduledTime": "{{STRING}}" } ], "activeAlerts": [ { "token": "{{STRING}}", "type": "{{STRING}}", "scheduledTime": "{{STRING}}" } ] } }, { "header": { "namespace": "Speaker", "name": "VolumeState" }, "payload": { "volume": {{LONG}}, "muted": {{BOOLEAN}} } }, { "header": { "namespace": "SpeechSynthesizer", "name": "SpeechState" }, "payload": { "token": "{{STRING}}", "offsetInMilliseconds": {{LONG}}, "playerActivity": "{{STRING}}" } } ], "event": { "header": { "namespace": "SpeechRecognizer", "name": "Recognize", "messageId": "{{STRING}}", "dialogRequestId": "{{STRING}}" }, "payload": { "profile": "{{STRING}}", "format": "{{STRING}}", "initiator": { "type": "{{STRING}}", "payload": { "wakeWordIndices": { "startIndexInSamples": {{LONG}}, "endIndexInSamples": {{LONG}} } } } } } }
Interfaces with Context Objects
The following Alexa interfaces require context
objects to report state information to AVS for every event:
- Alerts
- Alexa.Display.Window
- Alexa.Presentation.APL
- AudioActivityTracker
- AudioPlayer
- Bluetooth
- EqualizerController
- Notifications
- Speaker
- SpeechRecognizer
- SpeechSynthesizer
- VisualActivityTracker
JSON format alternatives
context
field
Use either a list or an object format for the context
JSON field that accompanies events.
The following example represents the historical context
format defined by the v20160207
envelope.
{ "context": [ // all context entries // including any reportable state properties ], "event": { ... } }
The following example represents the newer approach to reporting context
. Note that the properties
list includes generic context entries, even though they are not reportable state properties. Amazon provides this alternative format to developers for convenience.
{ "context": { "properties": [ // all context entries // including any reportable state properties ] }, "event": { ... } }
In both variants, the individual event documentation specifies the following information:
- Whether to include generic context entries, in which case all interfaces with generic context entries must contribute their states.
- The required or permitted reportable state properties.
Context entries
For generic context entries, use either a header
/payload
or a reportable state property JSON format, in either the context
or properties
lists defined by context.
The following example represents the generic context entry format defined by the capability interfaces. Don't use the header
/payload
format for Reportable state properties.
{ "header": { "namespace": "{{STRING}}", "name": "{{STRING}}" }, "payload": { ... } }
The following approach adapts the header
/payload
structure to conform to the format defined by reportable state properties. The value
object is equivalent to the payload
object of the header
/payload
variant. Amazon provides this alternative format to developers for convenience.
Reportable state properties must use the following format.
{ "namespace": "{{STRING}}", "name": "{{STRING}}", "value": { ... }, "timeOfSample": "{{STRING}}", "uncertaintyInMilliseconds": {{LONG}} }