Interaction flow
The interaction object
When an interaction is required, Deck sets the task run status tointeraction_required and populates the interaction field.
Field object
Interaction types
mfa
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
stringfield:{ "name": "code", "type": "string", "label": "Verification code" } -
Method selection — choose where to send the code; a
selectfield: -
Push approval — the user approves on their phone and you acknowledge; a
booleanfield:{ "name": "confirmed", "type": "boolean", "label": "I've completed the action on my phone" } -
Email link — the user pastes a confirmation URL; a
stringfield:{ "name": "confirmation_url", "type": "string", "label": "Confirmation link" }
security_question
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.account_selection
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.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
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 tofailed with an interaction_timeout error in the errors array. The run is not retried automatically, so you’ll need to start a new run.
Suppressing interactions
Some runs have no user present to answer, such as scheduled or background runs. Setinteractions_suppressed to true when you start the run, and Deck never sends an MFA code or security question to your user.
interaction_suppressed error instead of entering interaction_required. The credential stays valid, so you can run it again later with your user present.
The setting belongs to the run, not the credential, so the same credential can still be used for live runs where your user can answer. It defaults to false. Runs created with it include interactions_suppressed: true; otherwise the field is omitted.
On a workflow run, interactions_suppressed applies to every step.
Events
Subscribe to these events to react to interactions in real time:
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 separateinteraction_required event with a new interaction object. Handle them sequentially. Each submission may lead to another prompt or to completion.