> ## 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`, `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 (e.g. `string`).                                                  |
| `label` | string | Human-readable label for the field.                                          |

## Interaction types

<AccordionGroup>
  <Accordion title="mfa">
    A one-time code sent via SMS, email, or authenticator app.

    **Typical fields:** `code`

    ```json theme={null}
    {
      "interaction": {
        "type": "mfa",
        "message": "Enter the 6-digit code sent to your phone",
        "fields": [{ "name": "code", "type": "string", "label": "Verification code" }]
      }
    }
    ```
  </Accordion>

  <Accordion title="security_question">
    A knowledge-based question set by the user at the source.

    **Typical fields:** `answer`

    ```json theme={null}
    {
      "interaction": {
        "type": "security_question",
        "message": "What is your mother's maiden name?",
        "fields": [{ "name": "answer", "type": "string", "label": "Answer" }]
      }
    }
    ```
  </Accordion>

  <Accordion title="account_selection">
    The source has multiple accounts and the user needs to pick one.

    **Typical fields:** `account_id`

    ```json theme={null}
    {
      "interaction": {
        "type": "account_selection",
        "message": "Select an account",
        "fields": [{ "name": "account_id", "type": "string", "label": "Account" }]
      }
    }
    ```
  </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.

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

The timeout window depends on the source and the type of interaction. If no response is submitted before the window closes:

The task run status changes to `failed` with an `interaction_timeout` error in the errors array. You need to submit 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`                                                                                               |