Skip to content

Interactive Q&A

MindRoom agents can present clickable multiple-choice questions to users using Matrix reactions. When an agent's response contains a specially formatted JSON block, MindRoom automatically renders it as a numbered list with emoji reactions that users can click to respond.

How It Works

  1. An agent includes an interactive code block in its response.
  2. MindRoom parses the JSON, formats the options as a numbered list, and adds emoji reactions to the message.
  3. The user clicks a reaction emoji or types the option number.
  4. MindRoom captures the selection and feeds the agent structured selection context containing the question event, thread, question text, and selected option key, label, and value.

The entire flow happens within the thread where the original question was asked.

JSON Format

Agents emit interactive questions by wrapping JSON in an interactive code block:

```interactive
{
    "question": "What approach would you prefer?",
    "options": [
        {"emoji": "🚀", "label": "Fast and automated", "value": "fast"},
        {"emoji": "🔍", "label": "Careful and manual", "value": "careful"}
    ]
}
```

Fields

Field Type Required Description
question string No The question text shown above options. Defaults to "Please choose an option:".
options array Yes List of option objects (max 5).
options[].emoji string No Emoji shown as a reaction button. Defaults to "❓".
options[].label string No Human-readable label for the option. Defaults to "Option".
options[].value string No Value passed back to the agent when selected. Defaults to the label in lowercase.

Use a unique emoji for every option when reaction buttons must distinguish the choices. Duplicate emoji keys, including repeated default ❓ values, collapse in the reaction map; numeric replies remain available as a fallback.

Rendered Output

The JSON block is replaced with a formatted message:

What approach would you prefer?

1. 🚀 Fast and automated
2. 🔍 Careful and manual

React with an emoji or type the number to respond.

The corresponding emoji reactions are added to the message as clickable buttons.

User Response Methods

Users can respond in two ways:

  • Reaction: Click one of the emoji reactions added to the message.
  • Text: Send a message with a single-digit option number (e.g., 1 or 2) in the same thread. Only digits 1–5 are recognized; multi-digit numbers like 10 are ignored.

Both methods trigger the same follow-up behavior: the agent receives the selected value and continues the conversation.

Agent Integration

Agents don't need any special tools or configuration to use interactive questions. Any agent can include an interactive code block in its response text. You can guide agents to use this feature through their instructions or role:

agents:
  assistant:
    display_name: Assistant
    role: A helpful assistant
    instructions:
      - >
        When the user needs to choose between options, present them using
        an interactive code block with JSON containing question and options
        (each with emoji, label, and value fields).

Limitations

  • Maximum of 5 options per question. Additional options are silently truncated.
  • Only one active question per message. The first valid block receives interactive metadata and reaction buttons; later valid blocks render as plain, non-interactive question text.
  • Questions and in-flight selections persist across restarts in the event journal and remain tied to the prompt revision current when the answer is admitted.
  • Interactive metadata over 8,000 bytes is omitted, so the formatted question remains visible without reaction buttons or numeric selection.
  • Interactive blocks are supported in normal agent responses; direct matrix_message sends and edits reject them because those operations have no durable response identity.
  • Only human users can respond; reactions from other agents are ignored.
  • Only the agent that created the question processes reactions to it.