# Actions and Exact Inputs

> Send structured actions, button selections, barcodes, QR values, and typed codes through SDK clients.

Source: https://docs.thalovant.com/developers/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.

```python
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.

```python
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

  
    Send an action name such as `/next`, `/cancel`, or `/choose`.
  
  
    Send the selected ID, label, and source list as structured action payload.
  
  
    Send the raw scanned value through `send_code` with `kind="barcode"`.
  
  
    Send the exact typed value through `send_code` with a request ID.
  

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