questions-form

name

questions-form

description

Present multiple clarifying questions as an interactive Telegram form using inline buttons. Use when the agent needs to ask the user 2 or more clarifying questions before proceeding with a task, and wants to present them all at once in a structured form layout with selectable options and an "Other" free-text escape hatch. Triggers when: gathering multi-faceted requirements, onboarding flows, preference collection, or any scenario requiring structured multi-question input from the user via Telegram.

Questions Form

Present multiple clarifying questions as a Telegram inline-button form. All questions appear at once; the user answers in any order, then submits.

When to Use

• You need 2 or more clarifying questions answered before proceeding
• Questions have enumerable options (with optional free-text fallback)
• The channel is Telegram

Do not use this pattern for a single yes/no question — just send one message with buttons for that.

Form Protocol

Step 1: Compose the Form

Define each question internally as an object:

{ id: "type",     text: "What type of project?", options: ["Web App", "Mobile", "API"] }
{ id: "timeline", text: "What is your timeline?", options: ["This week", "This month", "No rush"] }
{ id: "budget",   text: "Budget range?",          options: ["< $1k", "$1k-5k", "$5k-10k", "> $10k"] }

Initialize internal tracking state:

form_state = { type: null, timeline: null, budget: null }
awaiting_freetext = null
form_submitted = false

Step 2: Send the Header

Send a plain message (no buttons) as the form introduction:

{
  "action": "send",
  "channel"