Skip to main content
These examples assume a session created through the quickstart. They are independent alternatives: do not send every example for the same question. Choice labels are illustrative; use those of your question.

Open question

Send the person’s actual words.

Choice question

Use the exact labels returned by the pending question. Send one label for single choice, and several only if multiple choices are allowed.

Semi-open question

Choices alone are sufficient. If the person adds an explanation, send it in free_text / freeText. A free-text “other” answer alone is also possible.

No answer or refusal

These outcomes need no text. Do not use them as a substitute for an actual answer.

Context received outside the exchange

apply_events / applyEvents updates state without consuming a turn. The engine may analyze this text. The pending decision is then recomputed: see When the pending question changes.

Already-known data

Use the stable identifier of the information configured in your domain, not an invented ID. Here, available_budget must exist in the published version. Confirmed structured data needs no text analysis.

What the SDK handles

For answer(...), it associates the answer with the pending decision and resolves choice labels. Answering an open question without text is rejected locally, before any network call. It then returns the next decision, not just an acknowledgement. Choices alone and no-answer outcomes need no model call, provided no other text requiring analysis is supplied. Free text is analyzed by the engine: do not routinely copy a choice label into user_text.

When the pending question changes

After apply_events / applyEvents, the pending decision is recomputed on the updated state, with the selection constraints of the call that proposed it. This step calls no model and consumes no turn.
  • If the same candidates remain the most useful, the decision and its decision_id are unchanged.
  • Otherwise, pending_decision carries a new decision with a new decision_id. Supplying the information that the pending question asked for is the common case: that question is withdrawn.
  • If no question is left, the session stops (status: "stopped"). If only the selection constraints of the original call leave no question, pending_decision is null, the session stays active, and the next next() call chooses.
Ask the question of the returned decision. The session handle tracks it, so answer(...) attaches the next reply to it. If your application had already shown the replaced question and the person answers it, do not send that reply with answer(...), which always targets the pending decision: send it as context with apply_events / applyEvents. Through the REST API, a previous_turn that cites the replaced decision_id is accepted once by /next: the reply goes to that question if it is still a candidate; otherwise it is read as context, without recording an answer for the withdrawn question or consuming a turn. See Manage a conversation.