Skip to content

Handler interaction API

The Handler is the application-facing runtime boundary. The Handler version documented here registers the route interact/{offer_id} (with an empty Functions route prefix). It does not register a legacy interact route. The production client contract uses the TDM interaction request envelope.

Request envelope

The request is JSON with a version, session, and request operation. For example, a session-start request has this shape:

{
  "version": "3.4",
  "session": {},
  "request": {
    "start_session": {}
  }
}

Natural-language input is represented under request.natural_language_input; semantic input is represented under request.semantic_input. The request operation and the session are distinct: requests carry the current user event, while the client returns session state received from the preceding response. The Handler protocol also defines passivity as a request operation.

TDM represents text and speech input differently. Text uses a natural-language input with modality: "text" and utterance; speech uses modality: "speech" and a hypotheses array containing utterance and confidence values. However, the Pipeline version documented here reads hypotheses in its normal neural path for natural-language input, so the text shape is not verified end-to-end for that revision. Handler tests that mock the Pipeline do not establish otherwise. Verify text integration against the coordinated deployed revisions.

The offer_id in the route identifies the offer for a new session. An existing session.offer_id takes precedence over the route value. On session start, the Handler associates the selected offer with the session if no offer ID is already present. Start a new conversation with a fresh session object; do not reuse a session to switch offers. Continue a session by returning its response session with the next request. The Pipeline initializes session history and IDs, while TDM initializes the information state.

The optional non_neural query parameter is passed as a request modifier. If the session does not already specify neural, a truthy parameter value sets session.neural to false; otherwise the Handler defaults it to true. Do not send the string false expecting it to be interpreted as Boolean false.

Response and turn-taking

The response carries output, session, and, where relevant, context. output.moves describes the dialogue moves; output.utterance carries realized text when present. output.expected_passivity tells the client when to send a passivity request. The Handler may adjust passivity and speech completion timing, so client behavior should follow the response fields rather than hard-code a timeout; expected_passivity may be null when passivity timing is disabled.

The Handler adds a request ID when one is absent and propagates it through the request/session. Preserve the returned session as an opaque state object; applications should not edit DME-owned session fields.

Session privacy

The documented Handler implementation encrypts non-whitelisted session fields into session.encrypted_data on ordinary session-bearing responses. The SESSION_ENCRYPTION_KEY setting is required; there is no plaintext fallback when it is missing. encrypted_data is a dictionary mapping each session field name to an encrypted JSON value, not one encrypted session blob. Keep the same key available while clients may resume sessions created with it. The Handler decrypts these values on the next request and merges them back into the session. Plaintext values take precedence if the same key appears in both places. Clients must round-trip session.encrypted_data unchanged and must not log or expose session contents. This mechanism does not authenticate the plaintext fields as a whole session object.

Pipeline hand-off and service calls

The Handler forwards interaction requests to the Pipeline. The Pipeline can return a service-call request instead of a final output; the Handler invokes the requested HTTP service, attaches its result, and calls the Pipeline again. However, the Handler/Pipeline/TDM versions cited in Architecture do not establish a working end-to-end continuation contract for every operation: Handler action and validator results are placed in request.query_results, while TDM's schema defines separate action_results and validation_results; Pipeline also expects a service-result event marker that Handler does not add. Verify and align all three revisions before relying on action or validator continuation. The generic round-trip description is not proof of compatibility between deployments.

Response variants and compatibility

Wakeword handling occurs within the registered interaction route and can produce a no_content response without output or session. Other legitimate response variants include output.actions such as EndSession and structured HTTP errors. Handler error responses use an error array with fields such as id, status, title, and detail (and may include code). Clients should handle these separately from a normal completed turn. Confirm details against the deployed Handler version.