Actions and Exact Inputs

Some clients need to send exact input rather than a natural-language sentence.

Use SDK action and code helpers for selections, button presses, scans, serial numbers, confirmation codes, and other exact values.

At a Glance

Helper	Best for
`send_action`	UI actions, menu selections, tool commands, and structured choices.
`send_code`	Barcodes, QR values, serial numbers, PINs, and typed exact values.
`ask`	Natural-language requests that should return a normalized reply.
`send_utterance`	Lower-level utterance events when the app already owns response handling.

Action Payloads

Use actions when the client already knows what happened. Keep the payload small, structured, and easy for the receiving skill to parse.

client.send_action(
    "/choose",
    payload={"id": "42", "label": "Use saved address"},
    title="Choose saved address",
    session_id="checkout-session",
)

Code Payloads

Use codes when the input value must remain exact. Do not turn a scanned value into a sentence unless the skill expects that.

client.send_code(
    "SN-001-XYZ",
    kind="barcode",
    label="device serial",
    session_id="maintenance-session",
)

Design Rules

Use utterances for language. Natural-language input should go through ask or send_utterance.
Use actions for known commands. Buttons and choices should send stable action names.
Use codes for exact values. Scans and typed codes should preserve the original value.
Include session context. Actions and codes often belong to a visible workflow.
Log request IDs. Exact inputs are easier to debug when every send has a trace key.

Common Inputs

Button

Send an action name such as /next, /cancel, or /choose.

Selection

Send the selected ID, label, and source list as structured action payload.

Barcode

Send the raw scanned value through send_code with kind="barcode".

Send the exact typed value through send_code with a request ID.