Interactive Input

Interactive Input Blocks

Embed interactive UI components (radio buttons, checkboxes, text fields, toggles) directly in chat responses. Compatible clients render these as native UI elements; other clients show a readable JSON code block as fallback.

When to Use

• Quizzes and exercises (single/multiple choice, fill-in-the-blank)
• Surveys and polls
• Structured data collection (forms)
• Any scenario where the user needs to select from options or provide structured input

How It Works

Wrap a JSON block in a `interactive code fence within your normal markdown response. You can mix regular text and interactive blocks freely in the same message.

Schema Reference

See references/schema.md for the complete schema specification.

Quick Example

When presenting a multiple-choice question, instead of listing options as text:

````markdown Here's your first question:

{
  "id": "q1",
  "card": {
    "body": [
      { "type": "TextBlock", "text": "What is the capital of France?", "weight": "bold" },
      { "type": "Input.ChoiceSet", "id": "answer", "style": "expanded",
        "choices": [
          { "title": "A. London", "value": "london" },
          { "title": "B. Paris", "value": "paris" },
          { "title": "C. Berlin", "value": "berlin" },
          { "title": "D. Madrid", "value": "madrid" }
        ]
      }
    ],
    "actions": [{ "type": "Action.Submit", "title": "Submit" }]
  }
}

````

Rules

1. Every interactive block MUST have a unique id field 2. Every interactive block MUST have at least one element in card.body 3. Include an Action.Submit in card.actions so the user can submit their response 4. Use "style": "expanded" for choice sets to show all options visually (recommended for quizzes) 5. Use "style": "compact" for dropdown selects when there are many options 6. Set "isMultiSelect": true on Input.ChoiceSet for multiple-choice questions 7. The first TextBlock in the body is used as the question label in the submitted response 8. You can include multiple interactive blocks in one message (e.g., a full quiz) 9. Always wrap the JSON in a `interactive code fence — never use `json for interactive blocks 10. Keep the JSON compact and valid — no comments, no trailing commas

Interactive Block Schema (v1)

Root Structure

{
  "id": "unique-block-id",
  "card": {
    "body": [ /* CardElement[] */ ],
    "actions": [ /* CardAction[] */ ]
  }
}

• id (string, required): Unique identifier for this block, used to correlate user responses
• card.body (array, required): List of UI elements to render
• card.actions (array, optional): Action buttons at the bottom of the card

Card Elements

TextBlock

Static text label. Use as question titles or descriptions.

{ "type": "TextBlock", "text": "Your question here", "weight": "bold", "size": "md" }

Input.ChoiceSet

Single or multiple selection from a list of options.

{
  "type": "Input.ChoiceSet",
  "id": "answer",
  "label": "Select your answer",
  "style": "expanded",
  "isMultiSelect": false,
  "choices": [
    { "title": "Option A", "value": "a" },
    { "title": "Option B", "value": "b" }
  ]
}

Input.Text

Free-form text input.

{
  "type": "Input.Text",
  "id": "explanation",
  "label": "Show your work",
  "placeholder": "Type your answer...",
  "isMultiline": true
}

Input.Number

Numeric input.

{
  "type": "Input.Number",
  "id": "result",
  "label": "Final answer",
  "min": 0,
  "max": 100,
  "placeholder": "Enter a number"
}

Input.Toggle

Boolean toggle (checkbox).

{
  "type": "Input.Toggle",
  "id": "confident",
  "label": "I am confident in my answer"
}

Separator

Visual divider between elements.

{ "type": "Separator" }

Card Actions

Action.Submit

Submit button that collects all input values and sends them as a response.

{ "type": "Action.Submit", "title": "Submit Answer" }

Complete Examples

Single Choice Quiz

````markdown

{
  "id": "math-q1",
  "card": {
    "body": [
      { "type": "TextBlock", "text": "What is 2 + 3 × 4?", "weight": "bold" },
      { "type": "Input.ChoiceSet", "id": "answer", "style": "expanded",
        "choices": [
          { "title": "A. 20", "value": "20" },
          { "title": "B. 14", "value": "14" },
          { "title": "C. 24", "value": "24" },
          { "title": "D. 11", "value": "11" }
        ]
      }
    ],
    "actions": [{ "type": "Action.Submit", "title": "Submit" }]
  }
}

````

Multiple Choice

````markdown

{
  "id": "even-numbers",
  "card": {
    "body": [
      { "type": "TextBlock", "text": "Select all even numbers:", "weight": "bold" },
      { "type": "Input.ChoiceSet", "id": "answer", "style": "expanded", "isMultiSelect": true,
        "choices": [
          { "title": "12", "value": "12" },
          { "title": "15", "value": "15" },
          { "title": "28", "value": "28" },
          { "title": "33", "value": "33" }
        ]
      }
    ],
    "actions": [{ "type": "Action.Submit", "title": "Submit" }]
  }
}

````

Mixed Form (Show-your-work)

````markdown

{
  "id": "geometry-q1",
  "card": {
    "body": [
      { "type": "TextBlock", "text": "A rectangle is 8cm long and 5cm wide. Find the perimeter.", "weight": "bold" },
      { "type": "Input.Text", "id": "steps", "label": "Show your work", "isMultiline": true, "placeholder": "Write your steps..." },
      { "type": "Separator" },
      { "type": "Input.Number", "id": "answer", "label": "Final answer (cm)" }
    ],
    "actions": [{ "type": "Action.Submit", "title": "Submit Answer" }]
  }
}

````

Survey / Feedback

````markdown

{
  "id": "feedback",
  "card": {
    "body": [
      { "type": "TextBlock", "text": "How was this lesson?", "weight": "bold" },
      { "type": "Input.ChoiceSet", "id": "rating", "style": "expanded",
        "choices": [
          { "title": "Excellent", "value": "5" },
          { "title": "Good", "value": "4" },
          { "title": "Average", "value": "3" },
          { "title": "Needs improvement", "value": "2" }
        ]
      },
      { "type": "Input.Text", "id": "comment", "label": "Any comments?", "placeholder": "Optional feedback...", "isMultiline": true },
      { "type": "Input.Toggle", "id": "more", "label": "I want more practice on this topic" }
    ],
    "actions": [{ "type": "Action.Submit", "title": "Send Feedback" }]
  }
}

````