> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deck.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Handling interactions

> Respond to MFA prompts, security questions, and other mid-flow verification requests.

An interaction is a pause in execution where the agent needs input from your user to continue. This happens when a source requires MFA codes, security questions, account selection, or any other verification that the agent can't resolve on its own.

Interactions occur during task execution when the source prompts for verification mid-run. Deck pauses the agent, tells you what it needs, and waits for you to submit the answer.

## Interaction flow

```mermaid theme={null}
sequenceDiagram
    participant App as Your Application
    participant Deck as Deck API
    participant Agent as Agent
    participant Site as External Website

    Agent->>Site: Attempt action
    Site-->>Agent: Verification prompt
    Agent->>Deck: Pause, interaction required
    Deck-->>App: Event: interaction_required
    App->>App: Collect input from user
    App->>Deck: Submit interaction
    Deck->>Agent: Resume
    Agent->>Site: Submit verification
    Site-->>Agent: Continue
```

## The interaction object

When an interaction is required, Deck sets the task run status to `interaction_required` and populates the `interaction` field.

```json theme={null}
{
  "id": "trun_a1b2c3d4...",
  "object": "task_run",
  "status": "interaction_required",
  "interaction": {
    "type": "mfa",
    "message": "Enter the 6-digit code sent to your phone",
    "fields": [
      {
        "name": "code",
        "type": "string",
        "label": "Verification code"
      }
    ]
  }
}
```

| Field     | Description                                                                                         |
| --------- | --------------------------------------------------------------------------------------------------- |
| `type`    | The kind of challenge the source is presenting: `mfa`, `account_selection`, or `security_question`. |
| `message` | Human-readable prompt from the source. Display this to your user.                                   |
| `fields`  | Array of inputs to collect. Each field has a `name`, `type`, and `label`.                           |

### Field object

| Field     | Type   | Description                                                                                                              |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------ |
| `name`    | string | Field identifier. Use this as the key in the `input` object when submitting.                                             |
| `type`    | string | Input type: `string`, `select`, or `boolean`.                                                                            |
| `label`   | string | Human-readable label for the field.                                                                                      |
| `options` | array  | Present only on `select` fields. The available choices, each `{ "value", "label" }`. Submit the chosen option's `value`. |

## Interaction types

<AccordionGroup>
  <Accordion title="mfa">
    A verification step from an SMS, email, or authenticator challenge. MFA takes several shapes depending on what the source asks for, so always build from `fields` rather than assuming a single `code`:

    * **Code entry** — a `string` field: `{ "name": "code", "type": "string", "label": "Verification code" }`
    * **Method selection** — choose where to send the code; a `select` field:

      ```json theme={null}
      {
        "name": "method",
        "type": "select",
        "label": "Delivery method",
        "options": [
          { "value": "sms", "label": "Text message" },
          { "value": "email", "label": "Email" }
        ]
      }
      ```
    * **Push approval** — the user approves on their phone and you acknowledge; a `boolean` field: `{ "name": "confirmed", "type": "boolean", "label": "I've completed the action on my phone" }`
    * **Email link** — the user pastes a confirmation URL; a `string` field: `{ "name": "confirmation_url", "type": "string", "label": "Confirmation link" }`
  </Accordion>

  <Accordion title="security_question">
    One or more knowledge-based questions set by the user at the source. A single question uses an `answer` field; multiple questions return one field each (`answer_0`, `answer_1`, …) with the question text as the label.

    ```json theme={null}
    {
      "interaction": {
        "type": "security_question",
        "message": "Answer your security questions",
        "fields": [
          { "name": "answer_0", "type": "string", "label": "What is your mother's maiden name?" },
          { "name": "answer_1", "type": "string", "label": "What city were you born in?" }
        ]
      }
    }
    ```
  </Accordion>

  <Accordion title="account_selection">
    The source has multiple accounts and the user needs to pick one. Returned as a `select` field with an `options` array — submit the chosen option's `value`.

    ```json theme={null}
    {
      "interaction": {
        "type": "account_selection",
        "message": "Select an account",
        "fields": [{
          "name": "account_id",
          "type": "select",
          "label": "Account",
          "options": [
            { "value": "acct_123", "label": "Residential ****1234" },
            { "value": "acct_456", "label": "Business ****5678" }
          ]
        }]
      }
    }
    ```
  </Accordion>
</AccordionGroup>

The `fields` array always tells you exactly what to collect. Build your UI from the fields rather than hard-coding for specific types. Sources can introduce new verification methods at any time.

## Submitting a response

```text theme={null}
POST /v2/task-runs/{run_id}/interaction
```

```json theme={null}
{
  "input": { "code": "123456" }
}
```

The request body wraps field values in an `input` object. Each key inside `input` matches a field `name` from the interaction. If the interaction has multiple fields, include all of them in a single request. For a `select` field, submit the chosen option's `value`; for a `boolean` field, submit `true` or `false`.

After you submit, the agent resumes. If the source accepts the input, the operation continues. If the source rejects it (wrong MFA code, for example), Deck may emit another `interaction_required` with the same or updated prompt so the user can retry.

## Timeouts

Each interaction has a fixed window of **5 minutes** to submit a response. If the window closes first, the task run status changes to `failed` with an `interaction_timeout` error in the `errors` array. The run is not retried automatically, so you'll need to start a new run.

## Events

Subscribe to these events to react to interactions in real time:

| Event                           | Fired when                                        |
| ------------------------------- | ------------------------------------------------- |
| `task_run.interaction_required` | A task run needs user input to continue execution |

The event payload includes a summary of the task run with the `interaction` field populated, so your handler has everything it needs to prompt the user without an additional API call.

## Multiple interactions

A single operation can require more than one interaction. For example, a source might ask for an MFA code, then follow up with a security question. Each prompt is a separate `interaction_required` event with a new `interaction` object. Handle them sequentially. Each submission may lead to another prompt or to completion.

## Error handling

| Scenario                                | What happens                                                                                                                             |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Wrong MFA code                          | Deck may emit another `interaction_required` for a retry, or the source may lock the account and the operation fails with `auth_invalid` |
| Interaction submitted when not required | Returns `interaction_not_required`                                                                                                       |
| Invalid field names or types            | Returns `interaction_input_invalid`                                                                                                      |
| Timeout                                 | Operation fails with `interaction_timeout`                                                                                               |