Handling interactions

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

The interaction object

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

{
  "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

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:

{
  "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" }

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.

{
  "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?" }
    ]
  }
}

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.

{
  "interaction": {
    "type": "account_selection",
    "message": "Select an account",
    "fields": [{
      "name": "account_id",
      "type": "select",
      "label": "Account",
      "options": [
        { "value": "acct_123", "label": "Checking ****1234" },
        { "value": "acct_456", "label": "Savings ****5678" }
      ]
    }]
  }
}

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

POST /v2/task-runs/{run_id}/interaction

{
  "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`

​Interaction flow

​The interaction object

​Field object

​Interaction types

​Submitting a response

​Timeouts

​Events

​Multiple interactions

​Error handling