Skip to main content
An interaction is a pause in execution where the browser 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 can occur during two operations:
  • Opening a connection - authentication requires MFA or additional verification
  • Running a task - the source prompts for verification mid-execution
The pattern is the same for both. 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 status to interaction_required and populates the interaction field on the connection or task run. 
{
  "id": "conn_a1b2c3d4...",
  "object": "connection",
  "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
messageHuman-readable prompt from the source. Display this to your user.
fieldsArray of inputs to collect. Each field has a name, type, and label.

​
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

​
On a connection

POST /v2/connections/{connection_id}/interaction

{
  "inputs": { "code": "123456" }
}

​
On a task run

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

{
  "inputs": { "code": "123456" }
}
The request body wraps field values in an inputs object. Each key inside inputs 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:
  • For connections, the status changes to disconnected and the browser session is closed. You need to open a new connection.
  • For task runs, the 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
connection.interaction_requiredA connection needs user input to complete authentication
task_run.interaction_requiredA task run needs user input to continue execution
The event payload includes the full object 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 (HTTP 400)
Invalid field names or typesReturns interaction_input_invalid (HTTP 400)
TimeoutOperation fails with interaction_timeout (HTTP 408)