Skip to main content
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"
      }
    ]
  }
}
FieldDescription
typeThe kind of challenge the source is presenting: mfa, account_selection, security_question.
messageHuman-readable prompt from the source. Display this to your user.
fieldsArray of inputs to collect. Each field has a name, type, and label.

​
Field object

FieldTypeDescription
namestringField identifier. Use this as the key in the input object when submitting.
typestringInput type (e.g. string).
labelstringHuman-readable label for the field.

​
Interaction types

A one-time code sent via SMS, email, or authenticator app.Typical fields: code
{
  "interaction": {
    "type": "mfa",
    "message": "Enter the 6-digit code sent to your phone",
    "fields": [{ "name": "code", "type": "string", "label": "Verification code" }]
  }
}
A knowledge-based question set by the user at the source.Typical fields: answer
{
  "interaction": {
    "type": "security_question",
    "message": "What is your mother's maiden name?",
    "fields": [{ "name": "answer", "type": "string", "label": "Answer" }]
  }
}
The source has multiple accounts and the user needs to pick one.Typical fields: account_id
{
  "interaction": {
    "type": "account_selection",
    "message": "Select an account",
    "fields": [{ "name": "account_id", "type": "string", "label": "Account" }]
  }
}
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. 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:
EventFired when
task_run.interaction_requiredA 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

ScenarioWhat happens
Wrong MFA codeDeck 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 requiredReturns interaction_not_required
Invalid field names or typesReturns interaction_input_invalid
TimeoutOperation fails with interaction_timeout