Handler interaction API¶

The Handler is the application-facing runtime boundary. Its Azure Function route is interact/{offer_id}; it also contains a legacy interact route for compatibility. 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.

The offer_id in the route identifies the offer for the interaction. On session start, the Handler associates that offer with the session if no offer ID is already present. Continue a session by returning its response session with the next request.

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.

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 Handler encrypts non-whitelisted session fields into session.encrypted_data when session encryption is configured. It decrypts those 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 the session contents.

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. This loop continues until the Pipeline returns a user-facing response or an error.

Compatibility note¶

The Handler also contains wakeword paths, including requests synthesized from wakeword activation, and an older interact route. Confirm behavior against the deployed Handler version before making either part of a new client integration.