Context

Context communicates the state of the device client components to AVS. It should reflect the state of client components just before the event it accompanies is sent. For example, if the device is playing an audio stream and a user interrupts that stream to make a speech request, when the Recognize event is sent to AVS, the included context should reflect that that an audio stream was playing by sending the PlaybackState context entry with the appropriate playerActivity value.

Note: Reportable state properties are a special type of context entry that are subject to a specialized set of mechanics. They are not required to be reported as device client component states synchronous with voice requests, unless otherwise noted.

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

If support for any of the following interfaces is asserted through Alexa.Discovery, state information must be reported to Alexa with each event that defines accompanying context:

JSON Format Alternatives

context Field

The context JSON field that accompanies events may be represented in one of two ways:

{
  "context": [
    // all context entries
    // including any reportable state properties
  ],
  "event": {
    ...
  }
}

This represents the historical context format defined by the v20160207 envelope.

{
  "context": {
    "properties": [
      // all context entries
      // including any reportable state properties
    ]
  },
  "event": {
    ...
  }
}

This represents the newer approach to reporting context. Note that generic context entries are included in the properties list, even though they are not reportable state properties. This alternative is provided to developers for convenience.

In both variants, the individual event documentation will specify

  • whether generic context entries must be included, in which case all interfaces with generic context entries must contribute their states
  • whether and which reportable state properties are required or permitted

Context Entries

Any generic context entries may use either of two JSON formats, in either the context or properties lists defined above:

{
  "header": {
    "namespace": "{{STRING}}",
    "name": "{{STRING}}"
  },
  "payload": {
    ...
  }
}

This represents the generic context entry format defined by the capability interfaces.

Reportable state properties may not use this format.

{
  "namespace": "{{STRING}}",
  "name": "{{STRING}}",
  "value": {
    ...
  },
  "timeOfSample": "{{STRING}}",
  "uncertaintyInMilliseconds": {{LONG}}
}

This 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. This alternative is provided to developers for convenience.

Reportable state properties must always use this format.