Skip to main content
Documentation

Feedback Widget Guide

Minolith's feedback widget is a lightweight, embeddable form that collects user feedback directly from your website or app. Submissions land in your project's feedback inbox where you can triage, tag, and track them — or let your AI agent review them for you.

Embedding the Widget

Add this script tag to your HTML, before the closing </body> tag:

<script src="https://api.minolith.io/widget/feedback.js"
        data-project="your-project-slug"
        data-position="bottom-left">
</script>

Replace your-project-slug with your project's slug (visible in your project settings).

That's it. The widget renders a floating button that opens a feedback form when clicked.

Configuration

Customise the widget with data- attributes on the script tag:

Attribute Required Default Description
data-project Yes — Your project slug
data-position No bottom-left Button position: bottom-left, bottom-right, top-left, top-right
data-color No #6366F1 Brand colour as hex — used for the button and accents
data-user-email No — Pre-fill the email field (removes the email input from the form)
data-user-id No — External user ID passed through with each submission

Example with all options

<script src="https://api.minolith.io/widget/feedback.js"
        data-project="my-app"
        data-position="bottom-right"
        data-color="#00d4aa"
        data-user-email="user@example.com"
        data-user-id="usr_12345">
</script>

When data-user-email is set, the email field is hidden from the form — useful when you already know who the user is (e.g. they're logged into your app).

Enabling the widget

The widget must be enabled in your dashboard before it will render:

  1. Go to your project → Feedback → Settings
  2. Toggle the Feedback Widget on
  3. Copy the embed code shown on the settings page

If the widget is disabled, the script loads silently without rendering anything.

How It Works

What the user sees

  1. A floating circular button appears in the corner of the page
  2. Clicking the button slides open a compact feedback panel
  3. The form has three fields:
    • Type — dropdown: Feedback, Bug, Idea, Question, or Praise
    • Message — free-text body (required)
    • Email — optional (hidden if data-user-email is set)
  4. On submit, a success message appears briefly, then the form resets

What gets captured

Every submission automatically collects:

Field Source
Message body User input (required)
Type User selection (defaults to "feedback")
Email User input or data-user-email attribute
External user ID data-user-id attribute
Page URL Captured automatically
User agent Captured automatically
Screen resolution Captured automatically
Viewport size Captured automatically
Source Set to widget
Status Set to new

Rate limiting

The widget is rate-limited to 10 submissions per IP address per hour per project. This prevents spam without requiring authentication.

Domain restrictions

By default, the widget works on any domain. To restrict which sites can embed it:

  1. Go to Feedback → Settings
  2. Enter your Allowed Domains (one per line)
  3. Wildcard subdomains are supported: *.example.com

This setting is shared with the changelog widget — updating it in either place applies to both.

Feedback Types

Users choose a type when submitting. Each type has a distinct colour in the inbox:

Type Colour When to use
Feedback Purple General comments and observations
Bug Red Something is broken
Idea Amber Feature suggestions
Question Blue Asking for help or clarification
Praise Green Positive feedback

The type helps you filter and prioritise in the inbox.

Managing Feedback in the Dashboard

The Inbox

Go to your project → Feedback to see all submissions. The inbox shows a table with type, message preview, status, priority, user, and date.

Filtering: Use the dropdowns at the top to filter by:

  • Status — new, acknowledged, planned, in_progress, resolved, closed
  • Type — feedback, bug, idea, question, praise
  • Priority — high, normal, low

Viewing and Triaging Items

Click any item to see its full details:

  • The submission — full message body, type badge, status, priority
  • Context — page URL, browser, screen size (captured automatically by the widget)
  • User info — email, name, external ID (if provided)
  • Management — update status, priority, and tags
  • Internal notes — add notes for your team (never visible to the person who submitted)
  • Metadata — item ID, source, timestamps

Status Workflow

Move items through the workflow as you triage and address them:

new → acknowledged → planned → in_progress → resolved → closed
Status Meaning
New Just received, not yet reviewed
Acknowledged Reviewed, will be addressed
Planned Added to your roadmap
In Progress Actively being worked on
Resolved Fixed or addressed (sets a resolved timestamp)
Closed Done — no further action needed

Tags

Add tags to categorise items for filtering and patterns (e.g. onboarding, mobile, billing, ux). Tags are lowercase, alphanumeric with hyphens, max 20 per item.

Internal Notes

Add notes to record investigation findings, link to issues or PRs, or leave context for teammates. Notes are internal only — they are never visible to the person who submitted the feedback.

Working with Your Agent

The feedback inbox is fully accessible through MCP tools. This makes it easy to review and triage feedback as part of your development workflow.

Reviewing feedback

Ask your agent to pull items for review:

"Pull the high-priority feedback items and let's review them."

Your agent will call list_feedback with priority: "high" and present what it finds:

Here are the 3 high-priority feedback items:

1. [Bug] "Login page shows a blank screen on Safari 17"
   — from user@example.com, submitted 2 hours ago
   — Status: new

2. [Bug] "CSV export includes deleted records"
   — from admin@company.com, submitted yesterday
   — Status: acknowledged

3. [Idea] "Add keyboard shortcuts for common actions"
   — from power-user@example.com, submitted 3 days ago
   — Status: planned

Would you like me to look into any of these?

Other useful prompts

See what's new:

"Show me all new feedback items since yesterday."

Filter by type:

"List all bug reports that are still unresolved."

Triage an item:

"Mark the Safari login bug as in_progress and add a note that we're investigating the WebKit rendering issue."

Resolve after fixing:

"The CSV export bug is fixed. Mark it as resolved and add a note with the commit hash."

Check for patterns:

"Are there any common themes in the recent feedback?"

Available MCP tools

Tool What it does Cost
submit_feedback Create a new feedback item 1 credit
list_feedback List items with filters (status, type, priority, tags) Free
get_feedback_item Get full item details including notes Free
update_feedback_status Change status, priority, or tags Free
add_feedback_note Add an internal note to an item Free

Submitting Feedback via API

You can also submit feedback programmatically using the REST API — useful for custom forms, server-side integrations, or automated bug reporting.

curl -X POST https://api.minolith.io/v1/feedback/items \
  -H "Authorization: Bearer mlth_yourkey" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Login page blank on Safari 17",
    "body": "When opening the login page in Safari 17.2 on macOS, the entire page is blank. DevTools shows a JavaScript error in the auth bundle.",
    "type": "bug",
    "user_email": "user@example.com",
    "tags": ["safari", "login", "critical"]
  }'

The API accepts all the same fields as the widget plus title and tags. Items submitted via the API have their source set to api.

Pricing

  • Submitting feedback costs 1 credit ($0.01) per item — whether from the widget, API, or MCP
  • All reads, status updates, notes, and deletes are free
  • The widget itself is free to embed on as many pages as you like

Last updated: 6 Apr 2026