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.

Which Helper

Helper	Best for
send_action	String payloads for UI actions, menu selections, and tool commands.
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. send_action takes one string payload, plus optional title and context. Use the exact payload returned by a choice or expected by the receiving skill; it does not accept a separate action name and dictionary.

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

This example assumes the skill understands /choose followed by JSON. The SDK sends that string as an utterance and records action metadata in the request context. Use emit for a skill that expects a named event with an object payload instead.

Code Payloads

Use codes to avoid speech transcription changing a scanned or typed value. send_code trims leading and trailing whitespace and sends the remaining string with input.exact: true; it does not parse numbers or remove leading zeroes. Do not turn the value into a sentence unless the skill expects that.

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

Both helpers send an event without waiting for the skill’s answer. Connect the client and install any response listener before sending when your app needs a reply. Use ask for the built-in request-and-reply flow. MCP exposes the same string inputs as thalovant_send_action.payload and thalovant_send_code.value.

Design Rules

1. Use utterances for language. Natural-language input should go through ask or send_utterance.
2. Use actions for known commands. Buttons and choices should send stable action names.
3. Use codes for scanned or typed values. Preserve leading zeroes and account for the helper’s whitespace trimming.
4. Include session context. Actions and codes often belong to a visible workflow.
5. 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".

PIN

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

Caution

Do not send payment card numbers, passwords, or other sensitive secrets as exact inputs.