Widget SDK Reference

Categories

choice_card

A set of labeled options the user can choose from. Supports single or multi-select via allowMultiple.

action_list

A list of items with action buttons (approve, reject, custom actions).

info_card

Read-only structured data card. Displays information without user actions.

payment_prompt

Basic transactional widget with price and payment action. Consider checkout_card for richer experiences.

audio_player

Embedded audio player with play/pause, scrub bar, duration display, and per-track actions.

{
  "type": "audio_player",
  "title": "Preview Tracks",
  "items": [
    {
      "id": "track-1",
      "title": "Midnight Run",
      "subtitle": "3:42",
      "imageUrl": "https://i.ytimg.com/vi/8KFP-oT5v2o/hq720.jpg?sqp=-oaymwEhCK4FEIIDSFryq4qpAxMIARUAAAAAGAElAADIQj0AgKJD&rs=AOn4CLA75Hy7XSNbfOIlUw2o2EQlUD5HGA",
      "metadata": {
        "url": "https://example.com/track.mp3",
        "duration": 222
      },
      "actions": [{ "label": "License", "type": "primary", "action": "purchase", "price": 29.99 }]
    }
  ]
}

image_carousel

Swipeable image gallery with navigation arrows, thumbnail strip, and optional zoom overlay.

{
  "type": "image_carousel",
  "title": "Property Photos",
  "items": [
    {
      "id": "img-1",
      "title": "Living Room",
      "imageUrl": "https://i.ytimg.com/vi/h0OeUk-QmHs/hq720.jpg?sqp=-oaymwEhCK4FEIIDSFryq4qpAxMIARUAAAAAGAElAADIQj0AgKJD&rs=AOn4CLBJGYdqLz8nsMh0eRtEtsLs3PBFig",
      "description": "Spacious open-plan living area",
      "actions": []
    }
  ]
}

video_player

Embedded video player with native controls, poster image, and multi-video selector.

{
  "type": "video_player",
  "title": "Demo Videos",
  "items": [
    {
      "id": "vid-1",
      "title": "Product Walkthrough",
      "imageUrl": "https://upload.wikimedia.org/wikipedia/en/thumb/3/3c/PanzerDragoon_JeanGiraud.jpg/250px-PanzerDragoon_JeanGiraud.jpg",
      "metadata": { "url": "https://example.com/demo.mp4" },
      "actions": []
    }
  ]
}

checkout_card

Product card with image, description, variant picker, quantity selector, and price calculation.

{
  "type": "checkout_card",
  "title": "Complete Your License",
  "items": [
    {
      "id": "lic-1",
      "title": "Standard License",
      "description": "Commercial use, up to 10k streams",
      "imageUrl": "https://i.etsystatic.com/6124911/r/il/d2b1dc/6492960673/il_fullxfull.6492960673_e86r.jpg",
      "metadata": {
        "variants": [
          { "label": "MP3", "value": "mp3" },
          { "label": "WAV", "value": "wav" }
        ]
      },
      "actions": [
        { "label": "Buy", "type": "primary", "action": "purchase", "price": 49.99, "currency": "$" }
      ]
    }
  ]
}

cart_builder

Running total across multiple items. Cart state persists in the browser session. Items can be added incrementally across messages. Emits checkout action on completion.

calendar_picker

Date/time slot picker. Slots are grouped by date with a grid layout. Emits select_slot action.

{
  "type": "calendar_picker",
  "title": "Choose a Time",
  "metadata": { "timezone": "America/Chicago" },
  "items": [
    {
      "id": "slot-1",
      "title": "10:00 AM",
      "metadata": { "date": "2026-06-01", "startTime": "10:00", "endTime": "10:30" },
      "actions": [{ "label": "Book", "type": "primary", "action": "select_slot" }]
    }
  ]
}

form_wizard

Multi-step form with progress bar. Each item is one step. Supports text, textarea, select, radio, and checkbox field types. Emits submit with all collected values on completion.

{
  "type": "form_wizard",
  "title": "License Application",
  "items": [
    {
      "id": "step-1",
      "title": "Project Name",
      "description": "What is this license for?",
      "metadata": {
        "fieldType": "text",
        "placeholder": "My Project",
        "required": true
      },
      "actions": []
    },
    {
      "id": "step-2",
      "title": "Usage Type",
      "metadata": {
        "fieldType": "select",
        "options": ["Commercial", "Personal", "Educational"],
        "required": true
      },
      "actions": []
    }
  ]
}

file_upload

Drag-and-drop file upload zone. Supports type restrictions and size limits. Emits upload action with base64-encoded file data.

{
  "type": "file_upload",
  "title": "Upload Reference Track",
  "metadata": {
    "accept": ".mp3,.wav,.flac",
    "maxSizeMB": 50,
    "multiple": false
  },
  "items": []
}

data_table

Sortable, filterable table with optional row selection. Columns can be explicitly defined or auto-derived from item metadata keys.

{
  "type": "data_table",
  "title": "Search Results",
  "metadata": {
    "columns": [
      { "key": "title", "label": "Track", "sortable": true },
      { "key": "artist", "label": "Artist" },
      { "key": "bpm", "label": "BPM", "sortable": true }
    ]
  },
  "items": [
    {
      "id": "row-1",
      "title": "Midnight Run",
      "metadata": { "artist": "Apex", "bpm": 128 },
      "actions": [{ "label": "Select", "type": "primary", "action": "select" }]
    }
  ]
}

comparison_table

Side-by-side cards with feature checkmarks and optional winner badge. Each item represents one option to compare.

{
  "type": "comparison_table",
  "title": "Compare Plans",
  "items": [
    {
      "id": "plan-a",
      "title": "Basic",
      "subtitle": "$9/mo",
      "metadata": {
        "features": [
          { "label": "10 downloads", "included": true },
          { "label": "Commercial use", "included": false }
        ],
        "highlighted": false
      },
      "actions": [{ "label": "Choose", "type": "secondary", "action": "select" }]
    }
  ]
}

star_rating

Clickable 1-5 star rating with optional text comment field. Most reused widget for post-task feedback.

{
  "type": "star_rating",
  "title": "Rate this response",
  "metadata": { "maxStars": 5, "showComment": true },
  "items": [
    { "id": "rating-1", "title": "How helpful was this analysis?", "actions": [] }
  ]
}

Submit action returns {"rating": 4, "comment": "Very thorough"}

nps_slider

0-10 horizontal scale with color gradient (red to green). Returns a Net Promoter Score.

{
  "type": "nps_slider",
  "title": "Quick Pulse Check",
  "items": [
    { "id": "nps-1", "title": "How likely are you to recommend this agent?", "actions": [] }
  ]
}

Submit action returns {"score": 8}. Scores 0-6 = Detractor, 7-8 = Passive, 9-10 = Promoter.

progress_bar_eta

Visual progress bar with percentage, ETA, and optional step labels. Auto-updates when agent sends a new widget via multi-step.

{
  "type": "progress_bar_eta",
  "title": "Processing Report",
  "items": [
    {
      "id": "prog-1",
      "title": "Generating quarterly report",
      "metadata": {
        "percent": 67,
        "eta": "~3 min",
        "steps": ["Analyzing", "Generating", "Formatting"]
      },
      "actions": []
    }
  ]
}

checklist_progress

Multi-item todo list with checkboxes and a progress bar at top. Users toggle items and submit when all are complete.

{
  "type": "checklist_progress",
  "title": "Onboarding Checklist",
  "items": [
    { "id": "c1", "title": "Connect your calendar", "metadata": { "completed": true }, "actions": [] },
    { "id": "c2", "title": "Set your availability", "metadata": { "completed": false }, "actions": [] },
    { "id": "c3", "title": "Invite your team", "metadata": { "completed": false }, "actions": [] }
  ]
}

qr_code_generator

Renders a QR code from a URL or text string with a copy-link button.

{
  "type": "qr_code_generator",
  "title": "Payment QR Code",
  "items": [
    { "id": "qr-1", "title": "Invoice #1234", "subtitle": "Scan to pay", "metadata": { "qrData": "https://lh3.googleusercontent.com/DQL5thuyS_GbtavvFpGlkjGHAtLGo8whf8g1kIWZ_sqyJcl3664sTOXLquF1BfZgcWfv_PgX0zJz-zy1Uds2vca73HA85sjHAv1kauEV0Y2xGshn_ZFcwxRCqZY2P9S_XncwKia7ImGp-Qa1XSGFsek", "size": 200 }, "actions": [] }
  ]
}

markdown_preview

Rendered markdown in a scrollable container with copy-to-clipboard and download buttons. Ideal for content agents returning blog posts, docs, or READMEs.

{
  "type": "markdown_preview",
  "title": "Generated README",
  "items": [
    { "id": "md-1", "title": "README.md", "metadata": { "markdown": "# My Project\n\nA description of the project.\n\n## Features\n\n- AI-powered analysis\n- Real-time collaboration\n\n> Built with care." }, "actions": [] }
  ]
}

confidence_meter

Circular gauge showing agent certainty (0-100%) with optional reasoning text. Helps users decide whether to trust a result.

{
  "type": "confidence_meter",
  "title": "Analysis Confidence",
  "items": [
    { "id": "conf-1", "title": "Market Analysis", "metadata": { "confidence": 85, "reasoning": "Based on 3 verified sources and 2 years of historical data" }, "actions": [] }
  ]
}

source_citations

Expandable footnote list with numbered references, links, and optional excerpt preview. Essential for research and fact-checking agents.

{
  "type": "source_citations",
  "title": "Sources",
  "items": [
    { "id": "src-1", "title": "[1]", "subtitle": "Harvard Business Review", "metadata": { "url": "https://hbr.org/article", "excerpt": "Recent studies show a 40% increase in..." }, "actions": [] },
    { "id": "src-2", "title": "[2]", "subtitle": "McKinsey Quarterly", "metadata": { "url": "https://mckinsey.com/report", "excerpt": "The data suggests that..." }, "actions": [] }
  ]
}

pdf_viewer

Embedded PDF viewer with iframe display, download button, and optional approve action. Ideal for contract review, report viewing, and document approval flows.

{
  "type": "pdf_viewer",
  "title": "Contract Review",
  "metadata": { "url": "https://example.com/contract.pdf", "filename": "Service Agreement Q4.pdf" },
  "items": [
    { "id": "approve", "title": "Approve Document", "actions": [{ "label": "Approve", "type": "approve" }] }
  ]
}

map_with_pins

OpenStreetMap embed with a list of numbered pins. Each pin can be selected to trigger an action. Use for location search results, store locators, and route planning.

{
  "type": "map_with_pins",
  "title": "Office Locations",
  "metadata": { "center_lat": 40.7128, "center_lon": -74.006, "zoom": 12 },
  "items": [
    { "id": "loc-1", "title": "HQ Manhattan", "subtitle": "350 5th Ave", "metadata": { "lat": 40.7484, "lon": -73.9857 }, "actions": [{ "label": "Select", "type": "select" }] }
  ]
}

email_composer

Pre-filled email composition form with To, CC, Subject, and Body fields. Returns the full email payload on send. Use for outreach drafts, follow-up emails, and notification composition.

{
  "type": "email_composer",
  "title": "Follow-Up Email",
  "metadata": { "to": "client@example.com", "cc": "", "subject": "Project Update", "body": "Hi, just following up on..." }
}

live_chart

Dynamic chart rendered via Recharts supporting line, bar, and pie types. Specify series data, labels, and chart configuration in metadata.

{
  "type": "live_chart",
  "title": "Revenue by Quarter",
  "metadata": {
    "chart_type": "bar",
    "x_key": "quarter",
    "series": ["revenue", "expenses"],
    "data": [
      { "quarter": "Q1", "revenue": 120000, "expenses": 85000 },
      { "quarter": "Q2", "revenue": 145000, "expenses": 92000 }
    ]
  }
}

signature_pad

Canvas-based drawing pad for capturing signatures. Returns the signature as a base64-encoded PNG on submit.

{
  "type": "signature_pad",
  "title": "Sign Here",
  "metadata": { "prompt": "Please sign to confirm your agreement" }
}

before_after_slider

Draggable divider comparing two images side by side. Use for before/after edits, design revisions, and A/B visual comparisons.

{
  "type": "before_after_slider",
  "title": "Design Revision",
  "metadata": {
    "before_url": "https://images.squarespace-cdn.com/content/v1/642af15dc8f46735c551b47c/a3af996f-7eee-4742-bd43-82fb96467fd9/Tami+Faulkner+Design%2C+how+to+fix+a+floor+plan+before+and+after%2C+offering+virtual+design+consultations+to+fix+and+improve+floor+plans%2C+US+and+Canada.jpg",
    "after_url": "https://i.ytimg.com/vi/GCI0kAPEqmk/maxresdefault.jpg",
    "before_label": "Original",
    "after_label": "Revised"
  }
}

ab_variant_picker

Side-by-side option cards with letter badges (A, B, C...) for voting and selection. Use for A/B testing, design feedback, and preference surveys.

{
  "type": "ab_variant_picker",
  "title": "Which headline performs better?",
  "items": [
    { "id": "a", "title": "Variant A", "subtitle": "Bold and direct", "metadata": { "content": "Get Started Today" }, "actions": [{ "label": "Vote", "type": "submit" }] },
    { "id": "b", "title": "Variant B", "subtitle": "Benefit-focused", "metadata": { "content": "Save 50% on Your First Month" }, "actions": [{ "label": "Vote", "type": "submit" }] }
  ]
}

document_diff

Line-by-line text diff with inline and side-by-side view modes. Highlights additions and removals with color coding.

{
  "type": "document_diff",
  "title": "Contract Changes",
  "metadata": {
    "before": "Payment due within 30 days.
Late fee: 5%.",
    "after": "Payment due within 15 days.
Late fee: 3%.
Early payment discount: 2%.",
    "before_label": "v1.0",
    "after_label": "v1.1"
  }
}

subscription_selector

Tier-based subscription cards with monthly/annual toggle and feature checklists. Use for pricing pages, plan upgrades, and SaaS onboarding.

{
  "type": "subscription_selector",
  "title": "Choose Your Plan",
  "items": [
    { "id": "starter", "title": "Starter", "metadata": { "monthly_price": 9, "annual_price": 89, "features": ["5 projects", "1 GB storage"], "popular": false }, "actions": [{ "label": "Select", "type": "submit" }] },
    { "id": "pro", "title": "Pro", "metadata": { "monthly_price": 29, "annual_price": 290, "features": ["Unlimited projects", "50 GB storage", "Priority support"], "popular": true }, "actions": [{ "label": "Select", "type": "submit" }] }
  ]
}

social_post_composer

Platform-aware social media post composer with character limit enforcement. Supports Twitter/X (280), LinkedIn (3000), and Instagram (2200).

{
  "type": "social_post_composer",
  "title": "Draft Social Post",
  "metadata": { "platform": "twitter", "draft": "Excited to announce our new feature launch!" }
}

invoice_preview

Formatted invoice with line items table, subtotal, tax calculation, total, and pay/download actions. Use for billing, contractor payments, and invoicing agents.

{
  "type": "invoice_preview",
  "title": "Invoice #1234",
  "metadata": {
    "lineItems": [
      { "description": "Web Development", "quantity": 40, "unitPrice": 150 },
      { "description": "Design Review", "quantity": 8, "unitPrice": 125 }
    ],
    "tax": 8.25,
    "currency": "USD",
    "dueDate": "2026-06-15"
  }
}

code_editor

Code editor with line numbers, language selector, and copy/submit actions. Supports multiple languages. Use for code review, SQL builders, and dev tool agents.

{
  "type": "code_editor",
  "title": "SQL Query",
  "metadata": {
    "language": "sql",
    "code": "SELECT u.name, COUNT(o.id) as orders
FROM users u
LEFT JOIN orders o ON o.user_id = u.id
GROUP BY u.name
ORDER BY orders DESC;",
    "editable": true
  }
}

rich_text_editor

Mini WYSIWYG editor with bold/italic/underline/lists/links toolbar. Returns HTML content on submit. Use for bio writing, blog drafting, and proposal editing agents.

{
  "type": "rich_text_editor",
  "title": "Edit Bio",
  "metadata": {
    "html": "<p>Enter your professional bio here...</p>",
    "placeholder": "Write your bio..."
  }
}

address_autocomplete

Type-ahead address input with OpenStreetMap Nominatim suggestions and optional map preview. Returns address, lat, lng on submit. Use for shipping, delivery, and logistics agents.

{
  "type": "address_autocomplete",
  "title": "Delivery Address",
  "metadata": { "defaultAddress": "350 5th Ave, New York" }
}

time_range_selector

Visual drag-to-paint availability grid across days and time slots. Returns selected time blocks on submit. Use for availability collection and scheduling optimization agents.

{
  "type": "time_range_selector",
  "title": "Set Your Availability",
  "metadata": {
    "days": ["Mon", "Tue", "Wed", "Thu", "Fri"],
    "startHour": 8,
    "endHour": 18,
    "slotMinutes": 30
  }
}

recurring_schedule_builder

Day-of-week toggles with time pickers and repeat options (weekly/biweekly/monthly). Use for meeting scheduling, habit tracking, and content calendar agents.

{
  "type": "recurring_schedule_builder",
  "title": "Set Your Schedule"
}

timezone_multi_poll

Propose multiple time slots for participants to vote on. Supports multi-select and timezone display. Use for group scheduling and Doodle-style polls.

{
  "type": "timezone_multi_poll",
  "title": "Pick Available Times",
  "metadata": { "allowMultiple": true },
  "items": [
    { "id": "t1", "title": "Tue 2:00 PM ET", "metadata": { "datetime": "2026-06-02T14:00:00", "timezone": "America/New_York" }, "actions": [] },
    { "id": "t2", "title": "Wed 10:00 AM PT", "metadata": { "datetime": "2026-06-03T10:00:00", "timezone": "America/Los_Angeles" }, "actions": [] },
    { "id": "t3", "title": "Thu 3:00 PM ET", "metadata": { "datetime": "2026-06-04T15:00:00", "timezone": "America/New_York" }, "actions": [] }
  ]
}

slide_deck_viewer

Swipeable slide deck viewer with slide counter, thumbnail strip, and optional presenter notes. Use for pitch decks, training materials, and presentation agents.

{
  "type": "slide_deck_viewer",
  "title": "Q4 Strategy Deck",
  "items": [
    { "id": "s1", "title": "Introduction", "metadata": { "imageUrl": "https://www.slidekit.com/wp-content/uploads/2024/10/Q1-to-Q4-Quarterly-Roadmap-Template-PPT-and-Google-Slides.jpg", "notes": "Welcome everyone to the Q4 strategy review." }, "actions": [] },
    { "id": "s2", "title": "Market Analysis", "metadata": { "imageUrl": "https://www.slideteam.net/media/catalog/product/cache/1280x720/q/u/quarterly_go_to_market_strategy_roadmap_with_identify_and_sell_slide01.jpg" }, "actions": [] },
    { "id": "s3", "title": "Action Plan", "metadata": { "imageUrl": "https://i.ytimg.com/vi/tXxPJ0qFkUk/maxresdefault.jpg", "notes": "Key initiatives for next quarter." }, "actions": [] }
  ]
}

meeting_notes_template

Structured meeting notes with editable sections for attendees, agenda, discussion, action items, and decisions. Use for meeting summaries, standup recaps, and project kickoff agents.

{
  "type": "meeting_notes_template",
  "title": "Weekly Standup Notes",
  "items": [
    { "id": "att", "title": "Attendees", "metadata": { "section": "attendees", "content": "Sarah, Mike, Priya" } },
    { "id": "agenda", "title": "Agenda", "metadata": { "section": "agenda", "content": "Sprint review
Blockers
Next steps" } },
    { "id": "actions", "title": "Action Items", "metadata": { "section": "actions", "content": "" } }
  ]
}

sms_notification_preview

Phone-frame mockup showing how an SMS or push notification will render on a device. Use for marketing preview, notification design, and A/B testing agents.

{
  "type": "sms_notification_preview",
  "title": "Notification Preview",
  "metadata": {
    "type": "sms",
    "message": "Your order #4521 has been shipped! Track it here: https://track.example.com/4521",
    "sender": "DiviDen"
  }
}

approval_chain

Sequential list of approvers with status badges (pending/approved/rejected). Enforces approval order -- only the current step can be acted on. Use for procurement, hiring, and contract approval workflows.

{
  "type": "approval_chain",
  "title": "Contract Approval",
  "items": [
    { "id": "legal", "title": "Legal Review", "subtitle": "Sarah Chen", "metadata": { "status": "approved", "order": 1 }, "actions": [] },
    { "id": "finance", "title": "Finance Approval", "subtitle": "Mike Torres", "metadata": { "status": "pending", "order": 2 }, "actions": [] },
    { "id": "ceo", "title": "CEO Sign-off", "subtitle": "Priya Patel", "metadata": { "status": "pending", "order": 3 }, "actions": [] }
  ]
}

voice_memo_recorder

Record audio memos via MediaRecorder API. Features record/stop/playback/discard/submit controls with duration timer and progress bar. Optional maxDuration (seconds) limit.

{
  "type": "voice_memo_recorder",
  "title": "Record a voice note",
  "metadata": { "maxDuration": 60 },
  "items": []
}

camera_capture

Capture a photo from device camera using getUserMedia. Supports facingMode (user/environment). Returns base64 PNG on submit.

{
  "type": "camera_capture",
  "title": "Take a photo of the document",
  "metadata": { "facingMode": "environment" },
  "items": []
}

screen_recording

Record screen via getDisplayMedia. Features record/stop/playback/download/submit controls. Handles user-initiated stop via browser share controls.

{
  "type": "screen_recording",
  "title": "Record your screen",
  "metadata": { "maxDuration": 120 },
  "items": []
}

oauth_connect

OAuth-style connect buttons with provider branding and connection status display. Each item represents a service to connect. Status flows: disconnected, connecting, connected, error.

{
  "type": "oauth_connect",
  "title": "Connect your accounts",
  "items": [
    { "id": "google", "title": "Google Workspace", "subtitle": "Calendar, Drive, Gmail", "metadata": { "status": "connected" }, "actions": [] },
    { "id": "slack", "title": "Slack", "subtitle": "Messages and channels", "metadata": { "status": "disconnected" }, "actions": [] }
  ]
}

kyc_verification

Identity verification flow with 4 steps: ID front upload, ID back upload, selfie capture, and review. Returns base64 images on submit.

{
  "type": "kyc_verification",
  "title": "Verify your identity",
  "items": []
}

two_factor_confirm

6-digit (configurable) code entry for two-factor authentication. Supports paste, auto-advance, and backspace navigation. Method label shows delivery channel (sms, email, authenticator).

{
  "type": "two_factor_confirm",
  "title": "Confirm your identity",
  "metadata": { "codeLength": 6, "method": "authenticator" },
  "items": []
}

live_counter

Animated number counters with labels, optional targets and trend indicators. Numbers animate with eased transitions. Grid layout with 2 columns. Display-only.

{
  "type": "live_counter",
  "title": "Dashboard Metrics",
  "items": [
    { "id": "users", "title": "Active Users", "metadata": { "value": 1247, "target": 2000, "trend": "up" }, "actions": [] },
    { "id": "revenue", "title": "Revenue", "metadata": { "value": 48500, "trend": "up" }, "actions": [] },
    { "id": "tickets", "title": "Open Tickets", "metadata": { "value": 23, "trend": "down" }, "actions": [] }
  ]
}

collaborative_canvas

Canvas drawing surface with brush tools, color palette, size options, eraser, undo, and clear. Returns base64 PNG on submit. Supports mouse and touch input.

{
  "type": "collaborative_canvas",
  "title": "Sketch your idea",
  "metadata": { "width": 400, "height": 300 },
  "items": []
}

live_feed

Streaming event feed with auto-scroll, severity-colored dots (info/warning/error/success), and timestamps. Configurable max visible items. Display-only.

{
  "type": "live_feed",
  "title": "Deployment Log",
  "metadata": { "maxItems": 15 },
  "items": [
    { "id": "e1", "title": "Build started", "subtitle": "v2.5.112", "metadata": { "time": "10:30", "severity": "info" }, "actions": [] },
    { "id": "e2", "title": "Tests passed", "metadata": { "time": "10:32", "severity": "success" }, "actions": [] },
    { "id": "e3", "title": "Memory warning", "subtitle": "85% threshold", "metadata": { "time": "10:33", "severity": "warning" }, "actions": [] }
  ]
}

typing_preview

Typewriter-style text reveal simulating live typing. Configurable speed in ms per character. Blinking cursor during reveal. Display-only.

{
  "type": "typing_preview",
  "title": "AI Response Preview",
  "metadata": { "speed": 25 },
  "items": [
    { "id": "p1", "title": "Based on my analysis of the quarterly data, revenue grew 23% year-over-year driven primarily by enterprise expansion.", "actions": [] }
  ]
}

kanban_mini_board

Compact drag-and-drop kanban board. Cards can be dragged between columns. Columns configurable via metadata. Submit returns the final card-to-column mapping.

{
  "type": "kanban_mini_board",
  "title": "Sprint Board",
  "metadata": { "columns": ["Backlog", "In Progress", "Review", "Done"] },
  "items": [
    { "id": "t1", "title": "Fix login bug", "subtitle": "P1", "metadata": { "column": "In Progress" }, "actions": [] },
    { "id": "t2", "title": "Add dark mode", "metadata": { "column": "Backlog" }, "actions": [] },
    { "id": "t3", "title": "Update docs", "metadata": { "column": "Review" }, "actions": [] }
  ]
}

timeline_gantt

Horizontal Gantt-style timeline with colored bars, date axis, and labels. Each item has start/end dates in metadata. Display-only.

{
  "type": "timeline_gantt",
  "title": "Project Timeline",
  "items": [
    { "id": "design", "title": "Design Phase", "metadata": { "start": "2026-06-01", "end": "2026-06-14" }, "actions": [] },
    { "id": "dev", "title": "Development", "metadata": { "start": "2026-06-10", "end": "2026-07-05" }, "actions": [] },
    { "id": "qa", "title": "QA Testing", "metadata": { "start": "2026-06-28", "end": "2026-07-10" }, "actions": [] },
    { "id": "launch", "title": "Launch", "metadata": { "start": "2026-07-10", "end": "2026-07-12" }, "actions": [] }
  ]
}

spreadsheet

Editable grid with column headers and cell editing. Supports basic formulas: =SUM(A1:A3) and =A1+B1. Each item is a row with cells in metadata. Submit returns the full grid.

{
  "type": "spreadsheet",
  "title": "Budget Tracker",
  "metadata": { "columns": ["Category", "Q1", "Q2", "Total"] },
  "items": [
    { "id": "r1", "title": "Row 1", "metadata": { "cells": ["Marketing", "5000", "7000", "=B1+C1"] }, "actions": [] },
    { "id": "r2", "title": "Row 2", "metadata": { "cells": ["Engineering", "12000", "14000", "=B2+C2"] }, "actions": [] },
    { "id": "r3", "title": "Row 3", "metadata": { "cells": ["Total", "=SUM(B1:B2)", "=SUM(C1:C2)", "=SUM(D1:D2)"] }, "actions": [] }
  ]
}

org_chart

Hierarchical organization chart with expand/collapse. Each item has an id and optional parentId in metadata to define the tree. Role shown as subtitle. All nodes expanded by default. Display-only.

{
  "type": "org_chart",
  "title": "Team Structure",
  "items": [
    { "id": "ceo", "title": "Jane Smith", "metadata": { "role": "CEO" }, "actions": [] },
    { "id": "cto", "title": "Alex Kim", "metadata": { "role": "CTO", "parentId": "ceo" }, "actions": [] },
    { "id": "cfo", "title": "Maria Lopez", "metadata": { "role": "CFO", "parentId": "ceo" }, "actions": [] },
    { "id": "eng1", "title": "Dev Lead", "metadata": { "role": "Engineering", "parentId": "cto" }, "actions": [] }
  ]
}

ar_preview

3D model viewer with rotation and zoom controls. Supports multiple models with a selector strip. Uses poster image for preview. Display-only with interactive rotation/zoom.

{
  "type": "ar_preview",
  "title": "Product 3D View",
  "items": [
    { "id": "model1", "title": "Front View", "metadata": { "src": "https://example.com/model.glb", "poster": "https://i.ytimg.com/vi/9DoUmTIIaOM/hq720.jpg?sqp=-oaymwEhCK4FEIIDSFryq4qpAxMIARUAAAAAGAElAADIQj0AgKJD&rs=AOn4CLB1Dm-8dzhqhYaWC1QWVwSjKImXAA" }, "actions": [] }
  ]
}

barcode_scanner

Camera-based barcode and QR code scanner using BarcodeDetector API. Scan line animation overlay. Results can be copied or submitted. Note: requires BarcodeDetector browser support (Chrome on Android/macOS).

{
  "type": "barcode_scanner",
  "title": "Scan product barcode",
  "items": []
}

WidgetPayload

interface WidgetPayload {
  widgets: AgentWidgetData[];       // one or more widgets to render
  widgetResponseUrl?: string;       // callback URL for user interactions
}

interface AgentWidgetData {
  type: string;                     // discriminator -- matches registry key
  title: string;                    // widget heading
  subtitle?: string;                // secondary heading
  agentName?: string;               // "via Synqabl" badge
  agentIcon?: string;               // icon for the agent badge
  items: WidgetItem[];              // content items
  layout?: 'horizontal' | 'vertical' | 'grid';
  allowMultiple?: boolean;          // multi-select for choice_card
  metadata?: Record<string, any>;   // type-specific config (timezone, columns, etc.)
}

WidgetItem

interface WidgetItem {
  id: string;                       // unique identifier
  title: string;                    // primary label
  subtitle?: string;                // secondary label
  description?: string;             // longer text
  imageUrl?: string;                // image or cover art
  icon?: string;                    // fallback icon
  tags?: string[];                  // tag badges
  metadata?: Record<string, any>;   // type-specific data (url, date, features, etc.)
  actions: WidgetItemAction[];      // interactive buttons
}

WidgetItemAction

interface WidgetItemAction {
  label: string;                    // button text
  type: 'primary' | 'secondary' | 'danger';
  action: string;                   // action identifier
  url?: string;                     // for open_url actions
  price?: number;                   // shows price on button
  currency?: string;                // currency symbol (default: $)
  payload?: Record<string, any>;    // additional data sent on click
}

Action Types

Actions are split into terminal (close the relay) and continuing (keep it open for multi-step).

Request (DiviDen to Agent)

POST {widgetResponseUrl}
Content-Type: application/json
X-DiviDen-Event: widget_response

{
  "relayId": "relay_abc123",
  "threadId": "thread_xyz",
  "response": {
    "widgetId": null,
    "itemId": "track-1",
    "action": "select",
    "payload": { "variant": "wav" },
    "respondedAt": "2026-05-29T12:00:00Z",
    "respondedBy": "user_id"
  },
  "allResponses": [  // full history of all responses in this relay
    { "itemId": "step-1", "action": "next", "payload": { "value": "My Project" }, ... },
    { "itemId": "track-1", "action": "select", ... }
  ]
}

Response (Agent to DiviDen) -- Single Step

For single-step flows, return a simple acknowledgment (or any non-widget JSON):

200 OK
{ "status": "ok", "message": "Response recorded" }

Response (Agent to DiviDen) -- Multi-Step

To continue the conversation with a new widget, return a full widget payload. DiviDen will attach it to the relay and render it for the user:

200 OK
{
  "widgets": [
    {
      "type": "checkout_card",
      "title": "Complete Purchase",
      "items": [ ... ]
    }
  ],
  "widgetResponseUrl": "https://agent.example.com/api/step-3"  // optional: override for next step
}

The new widgets replace the previous ones on the relay. The user sees the updated widget and can interact again. This cycle repeats until a terminal action is received.

Example: Music Licensing (4 Steps)

Flow Mechanics

The multi-step system tracks state automatically:

• _stepNumber increments on each round-trip
• _previousWidgets accumulates all prior widget payloads for agent reference
• allResponses in the callback includes the full response history
• Terminal actions (purchase, confirm, etc.) end the flow and close the relay
• Continuing actions (select, submit from form_wizard, etc.) keep it open

Agent Implementation Pattern

// Agent webhook handler (pseudocode)
async function handleWidgetResponse(req) {
  const { response, allResponses } = req.body;

  switch (response.action) {
    case 'submit':  // form_wizard completed
      const tracks = await searchCatalog(response.payload.values);
      return {
        widgets: [{
          type: 'audio_player',
          title: 'Matching Tracks',
          items: tracks.map(toWidgetItem),
        }],
      };

    case 'select':  // user selected a track
      const track = await getTrack(response.itemId);
      return {
        widgets: [{
          type: 'checkout_card',
          title: 'License ' + track.title,
          items: [toCheckoutItem(track)],
        }],
      };

    case 'purchase':  // terminal -- process payment
      await processPayment(response);
      return { status: 'ok' };  // no new widget = flow ends
  }
}

1. Tag Results (Generic Passthrough)

Any tag handler -- built-in or custom -- can return data.widgets in its result object. The platform scans all tag results and merges widget arrays into the message metadata automatically. No special-casing required.

// Tag handler return
return { data: { widgets: [{ type: 'info_card', ... }] } };

2. Marketplace Callbacks

When a marketplace agent completes execution and calls back with output, the system parses the output for embedded widgets. It tries JSON first (parsed.widgets, parsed.widget.widgets), then falls back to [WIDGET:...] regex extraction from plain text. Extracted widgets inject into the comms message metadata.

3. Capability Modules (responseWidgets)

Capabilities can declare static response widgets by adding aresponseWidgets key to their editableFields JSON. The value should be a JSON array of widget payloads. When a user has that capability installed and active, those widgets are appended to every chat response. Use this for persistent UI elements like status monitors, quick-action cards, or context-aware shortcuts.

// editableFields JSON with responseWidgets
{
  "responseWidgets": [
    { "type": "info_card", "title": "Status", ... }
  ],
  "otherField": "value"
}

4. Inline LLM Blocks

The LLM itself can emit [WIDGET:{...}] blocks directly in its response text. The parser extracts the JSON, strips the block from visible text, and merges the widget into metadata. This lets the model spontaneously generate interactive UI without any tag handler involvement.

// LLM response text
Here are your results:
[WIDGET:{"type":"data_table","title":"Results","metadata":{"columns":[...],"rows":[...]}}]
Let me know if you need anything else.

5. Aggressive Agent Extraction (expectsWidgets)

Agents that declare declaredWidgetTypes automatically trigger aggressive widget extraction at callback time. When callbacks arrive for these agents, the system scans nested JSON objects for widget-shaped arrays and always runs the regex pass regardless of initial parse success. This ensures widget delivery even from agents with unconventional output formats.