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:

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:

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}}
}