# Simple Commenter Documentation
The complete Simple Commenter documentation, concatenated for AI use.
---
# AI Assistant
The AI Assistant is a chat panel built into the dashboard. Ask it questions about your feedback, get reports, and let it draft status changes or replies for you to approve. Open it from the **AI Assistant** button (the sparkles icon) in the sidebar.
To use ChatGPT, Claude, Cursor, or another external AI tool, open the separate
**MCP** item directly in the project sidebar. [MCP & AI
connections](https://www.simplecommenter.com/docs/integrations/ai-agent) has the hosted server URL, browser
authorization, and local API tokens. The built-in AI Assistant needs no MCP
connection or token.
The assistant is included on every plan, including the trial, at no additional
charge, and is available to every role: workspace admins, team leads, and
clients. It only sees the projects and statuses the signed-in person can see.
## What It Can Do
| Capability | What it does |
| --- | --- |
| Answer product questions | Searches these docs and answers with links to the relevant page. |
| Query your feedback | Lists projects and comments, counts them, and summarizes recent activity. |
| Generate reports | Builds a feedback report (for example, 'what was done last week') you can download as Markdown or PDF. |
| Propose actions | Drafts a status change or a reply, shown as a confirmation card you approve before anything happens. |
## Asking About Your Feedback
Ask in plain language. For example:
- "How many open comments are on my marketing site?"
- "What did clients report this week?"
- "Show me high-priority feedback across all projects."
The assistant only ever sees the projects and statuses **you** are allowed to see, so its answers are scoped to your access. If you have more than one project, name the project or it will ask which one you mean.
## Reports
Ask for a summary or digest and the assistant gathers the data, then renders a report card. The card includes **Download as Markdown** and **Download as PDF** buttons, so you can share it with your team or a client.
For a spreadsheet of individual website comments, use **Comments** or **Board
→ Export CSV**. For cross-project exports including assets or archived feedback,
use the external [MCP export tools](https://www.simplecommenter.com/docs/integrations/ai-agent#filters-and-complete-results).
## Actions and Confirmation
The assistant never changes your data on its own. When you ask it to update a status or reply to a comment, it proposes the change as a **confirmation card**. Nothing happens until you click confirm, and replies are attributed to you.
If the assistant says it did something, it did so only after you approved the
card. Every confirmed action is recorded in an audit log.
## Who Can Use It
The AI Assistant is available to everyone, with access scoped to each role:
| Role | What they get |
| --- | --- |
| Workspace Admin | All projects and statuses, plus custom instructions and saved preferences. |
| Team Lead | Only assigned projects, with their role-visible statuses. No preferences. |
| Client | Only invited projects, with their reduced statuses. No account, billing, or integration help. |
## Custom Instructions and Preferences
Workspace admins can give the assistant durable, account-level guidance, for example a preferred report format or tone. The assistant also learns standing rules when you clearly state them. These preferences apply across every chat.
Preferences are account-level and available to workspace admins only. Team
leads and clients do not see this feature.
## Privacy
The assistant's tools scope every result to what your account and role may see. It will not surface other accounts' data, and it has no access to passwords, tokens, or payment details. For billing questions it points you to **Workspace settings → Billing**.
## Next Steps
- [Connect an external AI agent with MCP](https://www.simplecommenter.com/docs/integrations/ai-agent)
- [Browse and manage comments](https://www.simplecommenter.com/docs/dashboard/comments)
- [Set up integrations](https://www.simplecommenter.com/docs/integrations/slack)
---
# Asset Commenting
Collect visual feedback on design files, mockups, and documents. Upload images or PDFs to your project, share a link with clients, and receive pinpoint feedback directly on the file.
## Overview
Asset commenting lets you:
- **Upload design files** - Images and PDFs for visual review
- **Share with clients** - Send a link, no login required
- **Collect precise feedback** - Comments pinned to exact locations
- **Track in dashboard** - All feedback in one place
This is perfect for design reviews, mockup feedback, and document annotations without installing any code on a website.
## Getting Started
### 1. Upload Files
1. Go to your project dashboard
2. Click **Assets** in the sidebar
3. Drag and drop files or click to upload
### 2. Share with Clients
1. Click on any uploaded file to open it
2. Click **Copy Link** in the toolbar
3. Send the link to your client
### 3. Collect Feedback
Clients can view the file and leave comments directly on it. Comments appear in your dashboard alongside website feedback.
## Uploading Files
### Supported Formats
| Type | Formats |
| --- | --- |
| Images | PNG, JPG, GIF, WebP, SVG |
| Documents | PDF |
### Upload Methods
- **Drag and drop** - Drop files directly onto the Files page
- **Click to upload** - Click the upload area to select files
- **Multiple files** - Upload several files at once (plan limits apply)
File size and storage limits vary by plan. See [storage limits](https://www.simplecommenter.com/docs/asset-commenting#storage-limits) below.
## File Viewer
Click any file to open the full-screen viewer with these controls:
### Toolbar Options
- **Copy Link** - Copy shareable URL to clipboard
- **Download** - Download the original file
- **Zoom** - Fit to width, fit to height, or custom zoom
- **Full Screen** - Expand to full screen mode
### PDF Navigation
For PDF files, use the page controls to navigate:
- Previous/Next page buttons
- Current page indicator
- Comments are tied to specific pages
## Commenting on Files
### Adding Comments
1. Open a file in the viewer
2. The comment widget appears on the right
3. Leave feedback - comments are associated with the current view
4. For PDFs, comments track which page you're on
### Comment Features
- **Text feedback** - Describe issues or suggestions
- **Attachments** - Add screenshots or reference files
- **Status tracking** - Mark as To Do, In Progress, Done
- **Replies** - Discuss feedback in threads
PDF comments include the page number, so you always know which page the feedback refers to.
## Sharing with Clients
### Enable Public Sharing
To let clients view and comment without logging in:
1. Go to **Project Settings > Widget > Features**
2. Enable **Public Share Links**
3. Copy the file link and share it
### Sharing Options
| Level | Description |
| --- | --- |
| Per-file | Enable sharing for individual files |
| All files | Enable sharing for all files in the project |
### How Shared Links Work
- Links use secure, time-limited URLs (auto-refresh)
- Clients can view and comment without an account
- You control access through project settings
## Managing Files
### Views
- **Grid view** - Visual cards with thumbnails
- **List view** - Table layout with details
### Filtering & Sorting
Filter by:
- All files
- Images only
- PDFs only
Sort by:
- Last uploaded
- Name (A-Z)
- File size
- Most comments
### Deleting Files
- Hover over a file and click the trash icon
- Or select multiple files in list view for bulk delete
Deleting a file also removes all comments on that file. This cannot be undone.
## Storage Limits
| Plan | Max File Size | Total Storage |
| --- | --- | --- |
| Trial/Pro | 5 MB | 100 MB |
| Unlimited | 25 MB | 1 GB |
| Business | 25 MB | 5 GB |
| Enterprise | 100 MB | 50 GB |
## Use Cases
### Design Review
Upload mockups from Figma, Sketch, or Adobe XD. Share with stakeholders to collect feedback before development.
### Client Approvals
Share design concepts with clients. They can comment directly on the design without needing any special tools.
### Document Feedback
Upload contracts, proposals, or documentation. Collect page-specific feedback on PDFs.
### Internal Review
Share work-in-progress with your team. Track feedback and revisions in one place.
## Next Steps
- [Manage your files](https://www.simplecommenter.com/docs/dashboard/files)
- [Configure sharing settings](https://www.simplecommenter.com/docs/dashboard/functionalities)
- [Set up notifications](https://www.simplecommenter.com/docs/dashboard/notifications)
- [Creative Asset Feedback page](https://www.simplecommenter.com/creative-asset-feedback)
- [Image Feedback page](https://www.simplecommenter.com/image-feedback)
- [PDF Feedback page](https://www.simplecommenter.com/pdf-feedback)
---
# Chrome Extension
Leave feedback on any website directly from your browser. No script installation required on the site you're reviewing — install the extension once and start commenting anywhere.
Install the Extension
---
## Key Features
### Comment on Any Website
Review client sites, staging environments, competitor pages, or your own live site — the extension works on any URL without touching the site's code.
### Automatic Screenshots
Every comment you leave captures an automatic screenshot of the page at that moment. No need to manually attach images — context is always preserved.
### Works Hand-in-Hand with the Script
If a site already has the Simple Commenter widget installed, the extension detects it and logs you in automatically. Your comments flow into the same project dashboard — no duplicate setup needed.
**Website admin?** The extension is the fastest way to review any site. Install it once, pin it to your toolbar, and you're ready to annotate anything in Chrome.
---
## How to Install
1. Click **Add to Chrome** on the Chrome Web Store page
2. Pin the extension to your toolbar for quick access
3. Navigate to any website you want to review
4. Click the Simple Commenter icon and start leaving comments
All comments sync back to your [dashboard](https://www.simplecommenter.com/app) automatically.
Add to Chrome
---
## Onboard Clients via the Extension
You can invite clients to leave feedback through the extension — they don't need a script on their site or any technical setup.
1. Go to your project in the dashboard and open the **Clients** page
2. Click **Invite Client** and enter their email address
3. Set the invite channel to **Extension**
4. The client receives an email with a link to install the extension and get started
Once they install and log in, their feedback appears in your project alongside all other comments.
Clients invited via the Extension channel only see comments for the projects you've added them to. They don't get access to your full dashboard.
---
## Next Steps
---
# Access Settings
Configure who can access and use the commenting widget on your website. These settings control widget visibility, authentication requirements, and client access modes.
## Widget Visibility
### Parameter-Based Activation
When enabled, the widget only appears when a specific URL parameter is present.
**How it works:**
- Add `?feedback=true` to any page URL to show the widget
- Without the parameter, the widget is hidden from visitors
- Useful for internal review or staging environments
**Turning the widget off again:**
Once activated, the widget stays visible on every page of the site (the
activation is remembered in the visitor's browser). To hide it:
- Add `?feedback=false` to any page URL, or
- Open the widget drawer, go to the **Profile** tab, and click **Exit**
This is useful when you want to collect feedback on a live site without exposing the widget to regular visitors.
**Already using `?simple-commenter=true`?** That older parameter still works
everywhere `?feedback=true` does, so existing links and bookmarks keep
functioning. New links generated by Simple Commenter use `?feedback=true`.
### Always Visible
When parameter-based activation is disabled, the widget appears on all pages where the script is installed.
## Authentication
### Require Sign-In
When enabled, users must sign in before they can leave comments.
**Benefits:**
- Track who left each comment
- Enable email notifications to commenters
- Prevent anonymous spam
**When disabled:**
- Anyone can leave comments anonymously
- Name and email fields are optional
## Client Access Modes
Control how external clients can access and use the widget:
### Open Access
Anyone can sign up and start commenting immediately without approval.
### Request Access
Clients can request access, but must be approved by an admin before they can comment.
**Workflow:**
1. Client clicks "Request Access" in the widget
2. Request appears in your [Clients](https://www.simplecommenter.com/docs/dashboard/clients) dashboard
3. Admin approves or rejects the request
4. Client receives email notification of decision
### Invite Only
Only clients you explicitly invite can access the widget.
**Workflow:**
1. Go to [Clients](https://www.simplecommenter.com/docs/dashboard/clients) in the dashboard
2. Click **Invite Client**
3. Enter their email address
4. They receive an invitation email with access link
Manage your client list in the [Clients](https://www.simplecommenter.com/docs/dashboard/clients) section.
## Saving Changes
After adjusting settings, click **Save** in the bottom bar to apply changes. Click **Discard** to revert to the last saved state.
## Next Steps
- [Manage clients](https://www.simplecommenter.com/docs/dashboard/clients)
- [Configure what clients can do](https://www.simplecommenter.com/docs/dashboard/functionalities)
- [Set up default access settings](https://www.simplecommenter.com/docs/dashboard/default-settings)
- [Log your own users in automatically with the JS API](https://www.simplecommenter.com/docs/js-api) (skip the widget login for people already signed into your app)
---
# Billing
Manage your SimpleCommenter subscription, view billing history, and update payment details.
## Current Subscription
View your active subscription details:
- **Plan** - Your current tier (Trial, Pro, Unlimited, Agency, Enterprise) and plan type (Trial, Subscription, Lifetime Deal, or Free)
- **Status** - Active, Canceled, or Past Due
- **Renewal Date** - When your subscription renews
- **Price** - Monthly or annual billing amount
## Managing Your Subscription
### Upgrade Plan
To upgrade to a higher tier:
1. Click **Upgrade** or visit the [pricing page](https://www.simplecommenter.com/pricing)
2. Select your new plan
3. Complete payment
4. New features are available immediately
### Change Billing Cycle
Switch between monthly and annual billing:
1. Click **Manage Subscription**
2. Select monthly or annual billing
3. Changes take effect at your next renewal
Annual billing saves up to 20% compared to monthly billing.
## Billing Portal
Click **Manage Billing** to access the Stripe billing portal where you can:
- Update payment method (credit card)
- View and download invoices
- Update billing address
- Manage subscription details
## Billing History
View past invoices and payment history:
- Invoice date
- Amount charged
- Payment status
- Download PDF invoice
## Invoice Emails
If your accounting team wants invoices delivered automatically, set an
invoice email under **Account → Billing → Invoice emails**. After every
successful subscription payment, the same invoice you can download from
Billing History is emailed there as a PDF.
- Leave the field empty to turn invoice emails off. Invoices stay available
in Billing History either way.
- Only workspace admins can set the invoice email.
- Company details added on an invoice (name, address) are included on the
emailed PDF.
- One-off purchases such as lifetime deals are not emailed. Download those
from Billing History.
## Cancel Subscription
To cancel your subscription:
1. Click **Cancel Subscription**
2. Review what you'll lose access to
3. Confirm cancellation
Canceling removes access to paid features at the end of your billing period. Your data is retained for 30 days.
## Lifetime Deals (AppSumo)
If you redeemed an AppSumo code or another one-off purchase, the Billing page
shows your plan type as **Lifetime Deal** next to your tier (AppSumo codes put
the account on the **Unlimited** tier).
- The deal never renews and never expires. There is nothing to pay and no subscription to manage.
- You keep the features and limits of your lifetime tier, including the AI Agent integration.
- You do not need to upgrade unless you want features that only Agency or Enterprise include, such as whitelabel branding, a custom portal domain, or unlimited team members. Those are added by subscribing from **Account → Billing → Upgrade**.
If you are unsure how a subscription would combine with your lifetime deal,
contact support via the chat bubble before upgrading.
## Trial Period
New accounts start with a 14-day free trial with full access to all features. During the trial:
- No credit card required
- Full access to all features
- Trial banner shows days remaining
### Does my trial automatically convert to a paid subscription?
**No. The standard 14-day free trial does not automatically convert to a paid subscription, and you will not be charged when it ends.** No credit card is required, and there is no subscription to cancel. To continue using paid features, choose a plan under **Account → Billing → Upgrade** and complete checkout yourself. If you do not subscribe, the feedback widget pauses when the trial expires.
**Exception: if you accepted the optional 14-day trial extension by adding a payment card and completing subscription checkout, billing starts automatically when that extension ends unless you cancel beforehand.** You can manage or cancel that subscription under **Account → Billing**.
## Next Steps
- [View available plans](https://www.simplecommenter.com/pricing)
- [Manage team members](https://www.simplecommenter.com/docs/dashboard/team)
- [Configure your profile](https://www.simplecommenter.com/docs/dashboard/profile)
---
# Branding & White-label
Make Simple Commenter look like your own product. White-label branding applies your logo and brand name to the feedback widget, client invite emails, and the client login and portal pages, and can serve them from your own domain.
Find it under **Account > Branding**.
White-label branding and custom domains are available on the **Business**,
**Unlimited**, and **Enterprise** plans. Only workspace admins can manage
branding.
## Logo & Brand
- **Logo**: the logo shown on the widget, client emails, and client login pages.
- **Brand name**: the name used in place of "Simple Commenter" across client-facing surfaces.
- **Hide Simple Commenter branding**: remove "Powered by Simple Commenter" from client-facing pages.
## Custom Domain
Serve the branded client experience (login and portal) from a subdomain you own, for example feedback.youragency.com.
1. Enter the domain you want to use.
2. Simple Commenter shows the DNS record to add at your registrar.
3. Add the record, then click verify. Status moves from **Pending** to **Verified** once DNS propagates.
DNS changes can take some time to propagate. If verification fails, double
check the host and value against what the dashboard shows, then try again.
## Email Sender Domain
Send client emails from your own domain instead of the default Simple Commenter sender. Configure:
| Field | Purpose |
| --- | --- |
| Sender domain | The domain emails are sent from (requires DNS verification). |
| From email | The address clients see in the From line. |
| From name | The display name on outgoing emails. |
| Reply-to | Where client replies are routed. |
Until a sender domain is verified, emails continue to send from the default
Simple Commenter address so nothing breaks while you set it up.
## What Clients See
With branding configured, invited clients get a fully branded experience:
- The **feedback widget** shows your logo and brand name.
- **Invite and notification emails** come from your brand (and your sender domain, if set).
- The **client login and portal** pages, served on your custom domain, carry your logo.
See [Clients](https://www.simplecommenter.com/docs/dashboard/clients) for how to invite and manage clients.
## Next Steps
- [Invite and manage clients](https://www.simplecommenter.com/docs/dashboard/clients)
- [Control who can access the widget](https://www.simplecommenter.com/docs/dashboard/access)
- [Configure notifications](https://www.simplecommenter.com/docs/dashboard/notifications)
---
# Clients
Manage external clients who can access and leave feedback on your project. View pending requests, approve new clients, and remove access when needed.
## Client List
The clients page shows two sections:
### Pending Approval
Clients who have requested access (when using Request Access mode). For each pending client you can:
- **Approve** - Grant access to the project
- **Reject** - Deny and remove the request
### Active Clients
Approved clients who can access the widget. Shows:
- Client name
- Email address
- Approval status
## Inviting Clients
To invite a new client:
1. Click **Invite Client**
2. Enter their email address
3. Optionally add their name
4. Click **Add Client**
The client is immediately added with approved status. They can sign in using their email.
Invited clients receive access immediately. Send them the website URL where they can start leaving feedback.
## Removing Clients
To remove a client's access:
1. Find the client in the Active Clients list
2. Click the **Remove** button
3. Confirm the action
Removing a client revokes their access immediately. They will no longer be able to sign in or leave comments.
## Client Access Modes
How clients can access your project depends on the [Access Settings](https://www.simplecommenter.com/docs/dashboard/access):
| Mode | Description |
| --- | --- |
| Open | Anyone can sign up and comment |
| Request Access | Clients request access, you approve |
| Invite Only | Only clients you invite can access |
## Saving Changes
Click **Save Changes** after making modifications to apply them.
## Next Steps
- [Configure access modes](https://www.simplecommenter.com/docs/dashboard/access)
- [Manage team members](https://www.simplecommenter.com/docs/dashboard/team)
- [View client comments](https://www.simplecommenter.com/docs/dashboard/comments)
- [Create clients from your backend with the REST API](https://www.simplecommenter.com/docs/rest-api/members-and-clients), or let the [JS API](https://www.simplecommenter.com/docs/js-api) create them automatically on first login
---
# Managing Comments
Use the comments workspace to review feedback page by page, keep work moving
with statuses, and reply from the dashboard.
## Comments Workspace
The website comments view is organized around the pages on your site that
already have feedback. Select a page to see its thread and work through the
comments for that page.
### Comment Information
Each comment can include:
- **Visitor info** - Name and email when provided
- **Message** - The feedback content
- **Page path** - Where the feedback was submitted
- **Timestamp** - When it was submitted
- **Screenshot or attachments** - Supporting context from the visitor
- **Browser info** - Browser and OS details when available
## Adding a Comment from the Dashboard
Most feedback arrives through the widget, where someone clicks an element on
your site. When you already know what needs saying, you can skip that trip. The
**Add comment** button sits in the header of both the comments view and the
board, and opens a form where you choose the page, write the feedback, and set
priority, status, tags, tagged teammates, and attachments.
Pick the page from the list of pages that already have feedback, or type any
path (`/pricing`) for a page that doesn't yet.
A comment added this way belongs to the page rather than to an element on it,
so the widget lists it as a **page comment** instead of showing a pin. If you
later want it pinned, open it in the widget on your site and choose **Pin to
element**.
## Statuses
Organize your workflow with statuses:
| Status | Description |
| --- | --- |
| To Do | New feedback, not yet started |
| In Progress | Actively being worked on |
| Review | Ready for review or awaiting approval |
| Rework | Needs changes based on feedback |
| On Hold | Paused, waiting for external input |
| Blocked | Cannot proceed due to a dependency or issue |
| Done | Completed and resolved |
| Cancelled | No longer relevant or intentionally dismissed |
### Changing Status
- Open a comment in the thread for the current page
- Click the status control on the comment
- Choose the next status for that item
### Configuring Available Statuses
You can customize which statuses are available for your project in
[Status Management](https://www.simplecommenter.com/docs/dashboard/statuses):
1. Open the project you want to configure
2. Go to **Workflow** in the project settings and select the **Statuses** tab
3. Choose which statuses are enabled and which roles can use them
## Filtering and Sorting
Use the comments sidebar to narrow the current page view:
- **Status filters** - Focus on the work that matters right now
- **Sort options** - View comments by newest, oldest, or priority
- **Page list** - Jump between pages that already have feedback
The dashboard starts by focusing on active work first, so open and in-review
items are easier to triage.
These filters only affect the dashboard. To hide comments by status on the
website itself (for example, hide **Done** comments on the page), use the
status filter inside the widget's comment sidebar - see
[Filtering Comments on the Page](https://www.simplecommenter.com/docs/widget/basic-setup#filtering-comments-on-the-page).
## Replying to Comments
Keep the discussion in one place by replying directly inside a comment thread:
1. Open the comment you want to respond to
2. Click **Reply**
3. Write your response
4. Send it to add the reply to the thread
## Priority
Use the priority control on a comment to mark it as low, normal, or high
priority. You can then sort the current page by priority when you need to focus
on the most urgent items first.
## Screenshots and Attachments
Comments can include screenshots and supporting files. Open the relevant
comment to review the attached context without leaving the thread.
## Export Comments to CSV
In **Comments** or **Board**, click **Export CSV** beside **Add comment**:
- **All website feedback** downloads every accessible website comment across
all statuses, regardless of the current filters.
- **Current filters** downloads the complete matching set, including comments
below the fold or beyond the visible page. On Board, this becomes available
after all statuses finish loading; reload if loading failed.
Both choices exclude archived comments and asset feedback. The dashboard CSV
includes comment text, status, priority, tags, page, author, dates, the reply
thread, and available screenshot and attachment URLs. File URLs can expire;
refresh the feedback and export again to obtain current links. Workspace
owners and assigned team members can export their accessible feedback; client
accounts do not see this control.
For exports across projects, or to include assets and archived comments, open
the separate **MCP** item in the project sidebar and connect an external AI
tool. Ask it to use `export_comments` with the projects and filters you need.
See [MCP exports and filters](https://www.simplecommenter.com/docs/integrations/ai-agent#filters-and-complete-results).
## Deleting Comments
If a comment is spam, duplicated, or no longer needed, open the comment actions
menu and delete it from the thread.
## Next Steps
- [Manage team access](https://www.simplecommenter.com/docs/dashboard/team)
- [Configure statuses](https://www.simplecommenter.com/docs/dashboard/statuses)
- [Set up integrations](https://www.simplecommenter.com/docs/integrations/slack)
---
# Company login
Company login lets workspace owners and staff sign in with their company's
SAML identity provider. Open **Workspace settings → Company login** to
configure the connection, approve staff, test login, and manage the policy.
Agency offers SSO for **€150 per workspace per month**, in addition to Agency
and applicable tax. It covers one identity provider and all staff; Agency
already includes unlimited team members. Pro can configure and test before
upgrading to Agency. Enterprise activation is arranged through sales.
## Account creation and first login
The owner first creates a workspace through normal signup. Staff do not need
to create a separate workspace, complete registration, or set a Simple
Commenter password when their membership already exists.
1. Add the employee under **Members** or use the
[member-creation API](https://www.simplecommenter.com/docs/rest-api/members-and-clients#company-login-and-api-provisioning).
Use the work email their identity provider supplies and assign their role
and project access.
2. Under **Company login → Approve and test**, the owner approves that member
for SSO. The owner must test the connection before activating it.
3. Once SSO is active, the employee opens the workspace's company-login link
or selects **Sign in with SSO** and enters the workspace code.
4. The identity provider authenticates them. On first login, we match its
signed email to an approved member in the selected workspace. Subsequent
logins use the linked provider identity.
The person keeps their existing membership and permissions. The identity
provider determines who is signing in; the app does not let someone select
another staff member's identity. Having the company's email domain alone
does not grant access.
| Situation | What happens |
| --- | --- |
| Approved member who has never logged in | Can use SSO without separate signup once the connection is active. |
| Existing approved member | Signs into their existing membership with its current permissions. |
| Unknown or unapproved person | Access is refused; the workspace owner must add and approve them. |
| Same email in several workspaces | The company-login link chooses the workspace. Accounts are not merged. |
| Switching to another workspace that requires SSO | That workspace's company login is required. |
| External client | Uses the existing project invitation or client login flow. |
SSO does not create unknown members automatically. Automatic creation on
first login and SCIM directory synchronization are not implemented.
## Onboarding 100 employees through the API
Your IT team can use the existing `POST /api/external/members` endpoint in an
automation. It accepts one member per request, so a script can create 100
members without someone entering them one at a time in the dashboard.
Agency's SSO price remains €150 per month for that workspace.
Creation and SSO approval are separate. After the automation runs, the owner
refreshes **Company login** and approves members under **Approve and test**.
The API does not have an SSO-approval parameter. Share the workspace's
company-login link with the approved staff.
See the [member API guide](https://www.simplecommenter.com/docs/rest-api/members-and-clients#company-login-and-api-provisioning)
for authentication, request examples, duplicate handling, and project
assignment. API provisioning lives in the developer documentation; the
workspace login policy lives under **Company login**.
## Optional and required SSO
Optional SSO lets approved staff use company login while other supported
login methods remain available. Requiring SSO is a separate owner action
after activation, a recent successful owner test, and saving recovery codes.
Password, Google, and email-link login then direct staff to company login
before they can access the workspace.
**Current API limitation:** required SSO blocks integration tokens, including
member creation, listing, assignment, and removal through the REST API. Keep
SSO optional if your workflow depends on API provisioning. With required
SSO, the owner can manage membership in the dashboard after signing in with
SSO. The extension, MCP, and other connected apps without SSO support also
become unavailable.
## Removing access and owner recovery
Removing a workspace member or revoking their SSO approval prevents that
member's SSO sessions from continuing to access the workspace. Disabling
someone at the identity provider does not by itself immediately revoke an
existing Simple Commenter session; SSO sessions last up to eight hours.
For immediate removal, remove their membership or SSO approval in Simple
Commenter. The owner can also revoke all SSO sessions from Company login.
If the identity provider becomes unavailable, the owner can sign in with
their existing owner account and use a saved one-time recovery code.
Recovery makes SSO optional and revokes the workspace's SSO sessions.
---
# Project Template
The project template holds default configurations that are automatically
applied to new projects. Save time by configuring your preferences once
instead of setting them up for each project.
## How the Template Works
When you create a new project:
1. The template's settings are stamped onto the new project
2. The project starts with all your configured defaults
3. You can override any setting at the project level
Changing the template only affects new projects. Existing projects keep
their current settings.
## What You Can Configure
The template mirrors the project settings structure, so you learn it once:
### Access
Set default widget access configuration:
- Parameter-based activation
- Authentication requirements
- Client access mode (Open, Request Access, Invite Only)
[Learn more about Access settings](https://www.simplecommenter.com/docs/dashboard/access)
### Workflow
Set default statuses and tags for organizing comments:
- Enabled statuses and role visibility
- Comment tags
[Learn more about Statuses](https://www.simplecommenter.com/docs/dashboard/statuses)
### Notifications
Configure default email notification preferences:
- New comment notifications
- Reply notifications
- Status change notifications
[Learn more about Notifications](https://www.simplecommenter.com/docs/dashboard/notifications)
### Widget
Configure how the widget looks and behaves, split into three tabs:
- **Appearance** - Primary color, background colors, modal alignment
([Theme](https://www.simplecommenter.com/docs/dashboard/theme))
- **Features** - Drawing annotations, screenshots, file uploads, metadata
collection, tutorial ([Functionalities](https://www.simplecommenter.com/docs/dashboard/functionalities))
- **Language** - Custom labels and translations
([Localization](https://www.simplecommenter.com/docs/dashboard/localization))
### Integrations
Configure default integrations:
- Slack
- Trello
- Webhooks
[Learn more about Integrations](https://www.simplecommenter.com/docs/integrations/slack)
### Advanced
Advanced default options for new projects.
## Accessing the Project Template
1. In the workspace sidebar (outside a project), click **Project template**
2. Choose the setting section to configure
3. Save your changes
The project template is only visible to workspace admins.
## Overriding Defaults
To customize settings for a specific project:
1. Go to your project
2. Open the relevant settings page
3. Make your changes
4. Save
Project-level settings always override defaults.
## Next Steps
- [Configure access defaults](https://www.simplecommenter.com/docs/dashboard/access)
- [Set up theme defaults](https://www.simplecommenter.com/docs/dashboard/theme)
- [Configure integration defaults](https://www.simplecommenter.com/docs/integrations/slack)
---
# Assets
The **Assets** section of a project allows you to upload images and PDFs to collect feedback through visual annotations. Upload design mockups, screenshots, or documents and let your team and clients add comments directly on them.
New to asset commenting? See the [Asset Commenting guide](https://www.simplecommenter.com/docs/asset-commenting) for a complete walkthrough of uploading files, sharing with clients, and collecting feedback.
If you are comparing workflows, see [Creative Asset Feedback](https://www.simplecommenter.com/creative-asset-feedback), [Image Feedback](https://www.simplecommenter.com/image-feedback), and [PDF Feedback](https://www.simplecommenter.com/pdf-feedback).
## Uploading Files
### Drag and Drop
Drag files directly onto the page to upload them instantly.
### Upload Button
Click **Upload Files** and select images or PDFs from your computer.
### Supported Formats
- **Images**: PNG, JPG, GIF, WebP, SVG
- **PDFs**: Standard PDF documents
## Viewing Files
### Grid View
The default view displays files as visual cards with thumbnails, file names, and metadata.
### List View
Switch to list view for a table layout showing:
- File type
- File name
- Comment count
- Upload date
- File size
Click the view toggle in the top-right to switch between views.
## Sorting & Filtering
### Sort Options
- **Last uploaded** - Most recent first
- **Name (A-Z)** - Alphabetical order
- **Size (largest)** - Largest files first
- **Most comments** - Files with most feedback first
### Filter by Type
- **All files** - Show everything
- **Images** - Only image files
- **PDFs** - Only PDF documents
## File Actions
### View & Annotate
Click any file to open it and view/add comments directly on the image or PDF.
### Delete Files
Hover over a file card and click the trash icon to delete it. You can also select multiple files in list view for bulk deletion.
Deleting a file also removes all comments attached to it. This action cannot be undone.
## Storage Limits
File storage limits vary by plan:
| Plan | Max File Size | Total Storage |
| --- | --- | --- |
| Trial/Pro | 5 MB | 100 MB |
| Unlimited | 25 MB | 1 GB |
| Business | 25 MB | 5 GB |
| Enterprise | 100 MB | 50 GB |
## Next Steps
- [Manage comments](https://www.simplecommenter.com/docs/dashboard/comments)
- [Configure file upload settings](https://www.simplecommenter.com/docs/dashboard/functionalities)
- [Upgrade your plan](https://www.simplecommenter.com/pricing)
---
# Functionalities
Control which features are available in the commenting widget. Enable or disable capabilities based on your project needs.
You'll find these options in your project settings under **Widget**, in the
**Features** tab.
## Feature Toggles
### Drawing Annotations
Allow users to draw on screenshots when leaving feedback.
- **Enabled**: Users can annotate screenshots with freehand drawing
- **Disabled**: Screenshot capture only, no drawing tools
### Screenshots
Enable automatic screenshot capture when users leave comments.
- Captures the current viewport
- Includes any visible content
- Useful for visual bug reports
Two switches control capture, and both must be on:
- **Features → Screenshots** (this page) allows or prevents screenshot capture on your website.
- **Project settings → Screenshots** turns capture on or off for this project. It defaults to your account-wide setting under **Default settings → Screenshots**, and you can override it per project. The same page has the **Chrome extension auto-capture** switch and shows whether the script or the Chrome extension is connected.
Screenshots are on by default and included on all current plans, including the
trial. If the Screenshots page says screenshots are not available on your plan,
you are on a legacy plan; upgrade from **Account → Billing**.
#### How capture works, and why it can be slow
The web widget renders the screenshot inside the visitor's browser at the moment
the comment is submitted. Pages with large images, many fonts, or embedded
videos take longer to render, so the comment can take a few seconds to go
through. There are no quality, resolution, or compression settings to tune.
- If speed matters more than screenshots on a project, turn capture off on the project's **Screenshots** page.
- The [Chrome extension](https://www.simplecommenter.com/docs/chrome-extension) captures the screen locally, which is faster and works on pages the widget cannot render.
#### Screenshots are not being captured?
1. Check both switches above are on for the project.
2. Open the project's **Screenshots** page and confirm the script or the Chrome extension shows as connected. Capture needs one of them.
3. Embedded iframes and images served from other domains without CORS headers can appear blank in the capture. This is a browser restriction, not a setting.
4. If the page still says screenshots are unavailable on your plan, see above.
### File Uploads
Allow users to attach files to their comments.
- Images, documents, and other files
- Subject to [storage limits](https://www.simplecommenter.com/docs/dashboard/files) based on your plan
### Public Share Links
Generate shareable links for comments that can be viewed without logging in.
- Useful for sharing feedback with external stakeholders
- Links are read-only
### Comment Title
Require users to add a title to each comment.
- Helps organize and categorize feedback
- Makes comments easier to scan in the dashboard
### Mentions / Tagging
Let people @mention team members and clients in comments and replies.
- Tagged users are notified about the comment
- Works alongside [Mentions](https://www.simplecommenter.com/docs/widget/mentions) in the widget
- Disable it to hide the tagging UI entirely
### Metadata Collection
Collect browser and device information with each comment.
- Browser name and version
- Operating system
- Screen resolution
- Page URL
Metadata helps debug issues and understand context without asking users for details.
### Tutorial
Show an onboarding tutorial for new users.
- Explains how to use the widget
- Walks through leaving feedback
- Can be skipped by users
### Hidden Comments
Allow comments to be hidden from the main feed.
- Hidden comments are still accessible via filters
- Useful for archiving resolved feedback
### Comment Mode Banner
Show a banner when the widget is in comment mode.
- Reminds users they're in feedback mode
- Can be hidden for a cleaner experience
## Saving Changes
After adjusting settings, click **Save** in the bottom bar to apply changes. Click **Discard** to revert to the last saved state.
## Next Steps
- [Configure access settings](https://www.simplecommenter.com/docs/dashboard/access)
- [Customize widget appearance](https://www.simplecommenter.com/docs/dashboard/theme)
- [Set default functionalities for all projects](https://www.simplecommenter.com/docs/dashboard/default-settings)
---
# General Settings
The General Settings page lets you configure your project, control the widget status, and manage installation.
## Widget Status
### Active Toggle
Control whether the commenting widget is active on your website:
- **Enabled**: Widget appears on your website (based on access settings)
- **Disabled**: Widget is completely hidden
Disabling the widget hides it from all users but preserves your existing
comments and settings.
## Feedback Round
Run feedback as a time-boxed round with a clear end date. This is useful for review cycles where clients should give input by a deadline.
### End Date
Pick the date the round ends. Feedback closes at the end of that day (UTC). After it closes:
- **Clients can no longer leave comments** on the project
- **You and your team can still comment** as usual
Clear the date at any time to reopen the round.
### Warn Before the End
When an end date is set, the widget can show a "feedback ending soon" message to visitors a set number of days before the deadline. Choose 1, 2, 3, 5, 7, or 14 days.
### Email Notifications
Turn this on to email you and your team when the round is ending soon and again when it has ended.
- **Also notify clients**: when enabled, clients on the project receive the same emails. Add clients first, or there is no one to notify.
The round-end emails are separate from your regular new-comment notifications.
See [Notifications](https://www.simplecommenter.com/docs/dashboard/notifications) for those.
## Project Configuration
### Project Name & Domain
Update your project's name and associated domain:
1. Click **Configure**
2. Update the project name
3. Update the domain URL
4. Click **Save**
The project name appears in the dashboard navigation. The domain determines where the widget script will function.
Only workspace admins can change the project name or domain. Team leads see a
notice in place of these controls. See [Roles &
Permissions](https://www.simplecommenter.com/docs/dashboard/team#roles--permissions).
### Export Feedback (CSV)
Download website feedback as a spreadsheet directly from the project:
1. Open **Comments** or **Board**.
2. Click **Export CSV** beside **Add comment**.
3. Choose **All website feedback** or **Current filters**.
All website feedback includes every visible status and all matching records, including comments below the fold. Current filters exports the complete filtered set; on Board, this option becomes available after background loading finishes. Both options exclude archived comments and asset feedback. The all-feedback export is also available in **General → Export Feedback**.
The file downloads immediately and includes one row per comment with: comment ID and number, status and when it last changed, priority, tags, title, text, page URL, created date, author name and email, assignee, reply count, the full reply thread, attachment count and available attachment links, whether a screenshot exists and its available URL, and the task link for connected integrations (Asana, ClickUp, Trello, and others).
Team leads can export feedback from the projects they are assigned to.
Screenshot and attachment URLs may expire. Refresh the project data and export
again when you need current links. To include asset feedback, archived comments,
or several projects, use [MCP exports](https://www.simplecommenter.com/docs/integrations/ai-agent#export-csv-from-the-dashboard).
Open **MCP** directly in the project sidebar to set up the external connection.
There is no PDF export of feedback yet. For a shareable summary, ask the [AI
Assistant](https://www.simplecommenter.com/docs/ai-assistant) for a report and download it as PDF.
### Archive Project
Archiving is the way to hide a finished project without deleting anything. Archive a project when the work is done but you want to keep the feedback:
1. Click **Archive Project**
2. Confirm in the dialog
The project leaves your project list and the project switcher. Comments, settings, clients, and integrations are all kept.
Archived projects live in the **Archive**. Open it from the **Archived projects** link at the bottom of your project list, or go to `/app/archive`. Each row shows the project name, domain, comment count, and the date it was archived.
To bring a project back, click **Unarchive** in the Archive, or open the project's General Settings and click **Unarchive**. An archived project's settings pages stay reachable by direct link.
Archiving does not switch the widget off. The widget keeps loading on your
website and visitors can still leave feedback. To stop collecting feedback,
turn off the **Active** toggle under Widget Status before you archive.
Only workspace admins can archive or unarchive a project. Team leads do not
see these controls. Archived projects are hidden from team leads and clients
too.
### Delete Project
Remove a project and all its data:
1. Click **Delete Project**
2. Type the project name to confirm
3. Click **Delete**
Deleting a project permanently removes all comments, files, and settings. This
action cannot be undone.
Only workspace admins can delete a project. Team leads do not see the Delete
Project button; ask a workspace admin to delete it for you.
## Installation Script
### Adding to Your Website
Copy the script snippet and paste it into your website's `` section:
1. Find the script in the "Add to your website" section
2. Click **Copy** to copy to clipboard
3. Paste into your website's HTML `` tag
### Script Loading Options
Choose how the widget loads:
| Option | Description |
| --- | --- |
| Param-based | Widget loads when ?feedback=true is in the URL |
| Always | Widget loads on every page |
Param-based loading is useful for staging environments or internal review.
## Saving Changes
After adjusting settings, click **Save** in the bottom bar to apply changes. Click **Discard** to revert to the last saved state.
## Next Steps
- [Configure access settings](https://www.simplecommenter.com/docs/dashboard/access)
- [Customize widget appearance](https://www.simplecommenter.com/docs/dashboard/theme)
- [Set up integrations](https://www.simplecommenter.com/docs/integrations/slack)
---
# Localization
Translate or customize all text in the commenting widget. Support multiple languages or simply adjust the wording to match your brand voice.
## Overview
The localization settings allow you to customize every piece of text displayed in the widget, organized by category:
- **Comment Form** - Text for creating comments
- **Replies** - Reply-related text
- **Comment List** - Comment viewing interface
- **Statuses** - Status labels
- **Priorities** - Priority labels
- **User Identity** - Name and email fields
- **Authentication** - Login and registration
- **Attachments** - File upload text
- **Filters & Sorting** - Filter options
- **Settings** - User settings
- **Alerts** - Success and error messages
- **Help** - Help content
- **Tutorial** - Onboarding steps
- **Time** - Time-ago labels
## How to Customize Text
1. In your project settings, go to **Widget** and select the **Language** tab
2. Browse categories using the tabs
3. Check the box next to any text you want to customize
4. Enter your translation or custom text
5. Click **Save** to apply changes
Only checked items will override the default text. Unchecked items use the built-in defaults.
## Copy from Other Projects
Speed up localization by copying translations from another project:
1. Use the **Pick translations from other domains** dropdown
2. Select **Default Localization** or another project
3. Translations are copied to the current project
4. Customize as needed and save
## Link Placeholders
Some text includes links (like Terms of Service). When customizing these:
1. Keep the placeholder format: `[Terms of Service]`
2. Enter the translated link text
3. The link URL is preserved automatically
## Auto-Save
Changes auto-save every 60 seconds when you have unsaved modifications. A save bar appears at the bottom when there are pending changes.
## Restore Defaults
Click **Restore Default** to clear all customizations and return to the built-in text.
Restoring defaults removes all your translations for this project. This cannot be undone.
## Next Steps
- [Set default localization for new projects](https://www.simplecommenter.com/docs/dashboard/default-settings)
- [Configure widget appearance](https://www.simplecommenter.com/docs/dashboard/theme)
- [Customize widget features](https://www.simplecommenter.com/docs/dashboard/functionalities)
---
# Email Notifications
SimpleCommenter sends email notifications to keep all stakeholders informed about comment activity on your projects. This guide explains how the notification system works, who receives emails, and how to customize your preferences.
## How Email Notifications Work
Email notifications are sent as digest summaries based on your configured frequency. Rather than sending an email for every single comment, SimpleCommenter batches notifications together to prevent inbox overload.
### Notification Types
SimpleCommenter tracks several types of activity and notifies the appropriate recipients:
| Type | Description | Recipients |
| --- | --- | --- |
| New Comment | A new comment was posted on a page | Admins, Team Members |
| New Reply | Someone replied to an existing comment thread | Admins, Team Members |
| Status Change | A comment was marked as 'Done' or 'Review' | Original commenter (Client) |
| Reply to Your Comment | Someone replied to a comment you made | Original commenter |
| Feedback Round Ending / Ended | A project's feedback round is about to close or has closed | Admins, Team; clients if enabled |
Feedback round emails are configured per project on the **General** tab, not
here. See [Feedback Round](https://www.simplecommenter.com/docs/dashboard/general#feedback-round) to set an
end date and turn on round reminders.
## Who Receives Notifications
### Admins & Team Members
Workspace admins and team members receive notifications for project activity:
- **New Comments** - All new comments on domains they manage (excluding their own comments if "Notify on Own Comments" is disabled)
- **New Replies** - Replies added to any comment thread
- **Thread Participation** - Replies to threads where they've previously commented
Admins and team members can disable notifications for specific domains while
still receiving updates for others.
### Clients
Clients receive a more focused set of notifications:
- **Status Changes** - When their comment is marked as "Done" or "Review", letting them know their feedback was addressed
- **Replies to Their Comments** - When someone replies to a comment they submitted
Clients must be signed in to the widget and have opted in to email
notifications to receive emails.
## Configuring Notification Settings
### Team Settings (per project)
Each project has team-wide notification settings. They apply to everyone on the project, including clients. To configure:
1. Go to your **Project** in the dashboard
2. Click the **Notifications** tab
3. Configure the following options under **Team Notifications**:
| Setting | Description | Default |
| --- | --- | --- |
| Email Notifications | Enable or disable all email notifications for this project, for everyone | Off |
| Email Frequency | How often notification digests are sent | Daily |
| Notify on Own Comments | Include your own comments in notification emails | Off |
### Just for You (per project)
Below the team settings, the **Your Notifications** section has a single switch, **Email me about this project**. Turning it off mutes the project for you only. Team members and clients keep receiving emails as configured above.
This is the setting to use when you want clients to keep getting updates but
don't want the emails yourself.
### Email Frequency Options
Control how often you receive notification digests:
| Frequency | When Emails Are Sent | Best For |
| --- | --- | --- |
| Every Minute | Near real-time (for testing) | Development/testing only |
| 15 Minutes | Every 15 minutes | High-priority projects |
| Hourly | Once per hour | Active projects |
| Daily | Once per day | Most projects (recommended) |
| Weekly | Once per week | Low-activity projects |
| Monthly | Once per month | Archived or maintenance projects |
The "Every Minute" frequency is intended for testing purposes. For production
use, we recommend "Hourly" or "Daily" to avoid email fatigue.
## Managing Your Personal Preferences
### For Admins & Team Members
You can manage your notification preferences in **Account Settings**:
1. Leave the project view (click **Projects** in the sidebar)
2. Go to **Notifications** in the workspace sidebar
3. Configure your preferences:
**Global Opt-Out**: Disable all email notifications across all domains.
**Per-Domain Opt-Out**: Disable notifications for specific domains while continuing to receive updates for others. This is the same switch as **Email me about this project** on each project's Notifications tab, shown for all projects at once. This is useful if you:
- Are only actively working on certain projects
- Want to reduce email volume without missing critical updates
- Have delegated certain domains to other team members
### For Clients
Clients can manage their notification preferences directly in the widget:
1. Click the **Settings** icon in the widget
2. Toggle **Email Notifications** on or off
Alternatively, clients can click the **Unsubscribe** link at the bottom of any notification email.
## Email Content
### What's Included in Notification Emails
Each notification email includes:
- **Domain Name** - Which project the activity is from
- **Comment Details** - The comment text, commenter name, and timestamp
- **Status Badge** - Visual indicator of comment status (Done, Review, etc.)
- **Replies** - Any replies in the thread, with new replies highlighted
- **Attachments** - List of attached files (if any)
- **Quick Links** - Direct links to the dashboard and the live domain
### Email Preview Example
Notification emails show up to 2 items per email to keep them scannable. If there are more updates, you'll see a "...and more comments not shown" message with a link to view all activity in the dashboard.
### Magic Links
Notification emails include **magic links** that automatically sign you in:
- **Dashboard Link** - Takes admins/team members directly to the dashboard
- **Domain Link** - Takes clients directly to the live website with the widget open
Magic links expire after 30 days for security. If a link has expired, you'll
be prompted to sign in normally.
## Troubleshooting
### Not Receiving Emails?
If you're not receiving notification emails, check the following:
1. **Notifications Enabled** - Verify email notifications are enabled for the domain (Settings > Notifications)
2. **Notifications Enabled Date** - Only comments created after notifications were enabled will trigger emails
3. **Frequency Timing** - Emails are batched based on your frequency setting; wait for the next scheduled send
4. **Spam/Junk Folder** - Check your spam folder and add `noreply@simplecommenter.com` to your contacts
5. **Personal Opt-Out** - Ensure you haven't opted out in Account Settings
6. **Domain Opt-Out** - Check if the specific domain is in your disabled notifications list
7. **Valid Email** - Ensure your account has a valid email address
### Clients Not Receiving Emails?
For clients to receive emails:
1. They must be **signed in** to the widget (not anonymous)
2. They must have **opted in** to notifications when signing up
3. They must not have **unsubscribed** via the email link
4. Their email must be a **valid format**
### Too Many Emails?
If you're receiving too many emails:
1. **Increase frequency** - Change from "Hourly" to "Daily" or "Weekly"
2. **Disable specific domains** - Opt out of low-priority domains in Account Settings
3. **Disable "Notify on Own Comments"** - Avoid notifications for your own activity
## Technical Details
### Email Delivery
- Emails are sent via **SendGrid**
- Sender address: `noreply@simplecommenter.com`
- All emails are logged for troubleshooting
### When Emails Are Triggered
The notification system runs on a schedule and checks:
1. Which domains have `emailNotifications: true` and `hasPendingNotification: true`
2. Whether enough time has passed since the last email (based on frequency)
3. Which comments/replies haven't been marked as `notified` yet
After sending, comments are marked as notified to prevent duplicate emails.
## Next Steps
- [Configure domain settings](https://www.simplecommenter.com/docs/dashboard/general)
- [Set up Slack notifications](https://www.simplecommenter.com/docs/integrations/slack) for real-time team alerts
- [Manage team members](https://www.simplecommenter.com/docs/dashboard/team)
---
# Dashboard Overview
The SimpleCommenter dashboard is your central place for managing feedback,
projects, members, and project settings.
## Navigation
The sidebar changes depending on where you are.
### Workspace View
Outside a project, the sidebar shows workspace-level areas:
- **Projects** - All your websites and domains
- **Project template** - Default settings stamped onto new projects at
creation (workspace admins only)
- **Members** - Invite teammates and manage workspace access (workspace
admins only)
- **Billing** - Subscription and payment details (workspace admins only)
- **Branding** - White-label and branding options (workspace admins only)
- **Notifications** - Your personal notification preferences
- **MCP & AI connections** - Hosted ChatGPT/Claude setup, local API tokens,
and connected app access
**Workspace settings** remains visible while you are inside a project, so you
can reach these account controls without leaving the project first. Client
accounts do not see workspace settings.
### Project View
Inside a project, the sidebar shows the project's work areas:
- **Comments** - Review and respond to feedback, page by page
- **Preview** - Open your live website inside the dashboard to leave and
review comments ([Site Preview](https://www.simplecommenter.com/docs/dashboard/preview))
- **Board** - Kanban view of comments grouped by status
- **Assets** - Files and designs shared for feedback
- **MCP** - A separate, direct item for external AI connections; it is not
nested under project settings or integrations
Workspace owners authorize external connections. Team members can find the
setup page and ask the owner to connect; client accounts do not see MCP. The
sidebar's **AI Assistant** button opens the built-in dashboard chat and needs
no MCP token. See [MCP setup](https://www.simplecommenter.com/docs/integrations/ai-agent) or
[AI Assistant](https://www.simplecommenter.com/docs/ai-assistant) for the relevant workflow.
## Projects
Each project represents a website or domain where you have installed the
widget.
### Creating a Project
1. Click **+ New Project** in the dashboard
2. Enter your domain
3. Copy the installation code
4. Add it to your website
### Project Settings
Each project has a flat settings list in the sidebar:
- **General** - Project name, domain, and the installation snippet
- **Access** - Visibility, sign-in requirements, and client access
- **Workflow** - Statuses and tags used to organize comments
- **Notifications** - How your team is alerted to new feedback
- **Widget** - Theme, functionalities, screenshots, and localization
- **Clients** - External stakeholders invited to leave feedback
- **Integrations** - Slack, Trello, webhooks, and other connected tools
- **Developers** - JavaScript API and REST API setup
- **Advanced** - Advanced project options
You can have multiple projects on a single account. Each project tracks
feedback for one website or domain.
### Archiving a Project
Workspace admins can archive a project that is finished. The project leaves the
project list but keeps its comments and settings, and you can restore it at any
time from the **Archived projects** link at the bottom of the list. See
[Archive Project](https://www.simplecommenter.com/docs/dashboard/general#archive-project).
## Comments Workspace
The comments workspace is designed for day-to-day review work:
- **Page-by-page review** - Open a page and see the feedback collected there
- **Status filters** - Narrow the current view to the statuses you care about
- **Sorting** - Order comments by newest, oldest, or priority
- **Thread actions** - Reply, change status, update priority, or delete a
comment
- **Attachments** - Review screenshots and other files attached to the thread
- **Export CSV** - Download all website feedback or the complete current
filtered set from Comments or Board; both exclude archived and asset feedback
## Mobile Access
The dashboard is responsive, which makes it practical to:
- Review new feedback on the go
- Reply to urgent comments
- Check project settings away from your desk
## Next Steps
- [Managing comments](https://www.simplecommenter.com/docs/dashboard/comments)
- [Team collaboration](https://www.simplecommenter.com/docs/dashboard/team)
- [Project settings](https://www.simplecommenter.com/docs/dashboard/general)
---
# Site Preview
Site Preview opens your live website inside the SimpleCommenter dashboard so
you and your team can leave and review comments without installing anything on
the site. Open a project and click **Preview** in the sidebar.
## How It Works
The preview does not load your site directly. SimpleCommenter's preview
servers fetch the page for you, add the commenting tools, and display the
result inside the dashboard. This is why the preview can work on sites that
don't have the widget installed.
Because the request comes from our servers instead of your browser, a few
things behave differently than a normal visit:
- Pages behind a login on your website cannot be previewed
- Sites on private networks (localhost, internal tools) cannot be reached
- Firewalls and bot protection on your site may block the preview servers
## Requirements
- The project must have the **Public Website** setting enabled in its project
settings
- The website must be publicly reachable over http:// or https://
## Troubleshooting
When a page fails to load, the preview shows an error card explaining what
went wrong and how to fix it. The most common cases are below.
### Access Forbidden (403)
The preview shows **"Access Forbidden - The website denied access to this
page"** even though the site opens fine in a normal browser tab.
This means your website's firewall or bot protection is blocking requests from
SimpleCommenter's preview servers. The block is not caused by SimpleCommenter;
the site's security layer treats the preview request as automated traffic and
rejects it.
Common sources of the block:
- **Cloudflare** or another WAF with bot protection enabled
- **Hosting firewalls** (many managed WordPress hosts block datacenter
traffic by default)
- **WordPress security plugins** such as Wordfence, Sucuri, or Solid Security
- **IP allowlists or password protection** on staging environments
**How to fix it:** every preview request includes the HTTP header
`X-SimpleCommenter-Proxy: 1` so you can safely allow it through:
1. **Cloudflare**: create a WAF custom rule that skips bot protection when the
request contains the header `X-SimpleCommenter-Proxy` with value `1`
2. **WordPress security plugins**: add an allowlist/bypass rule for requests
with that header, or temporarily disable the firewall to confirm it is the
cause
3. **Other firewalls**: ask whoever manages the site's security to allow
requests carrying this header
If you can't change the site's security settings, you don't need the
preview: install the widget snippet (or the WordPress plugin) on the site,
or use the Chrome extension. Both run directly in your browser, so the
site's firewall never sees a proxy request.
### Other Common Errors
| Error | What it means | What to do |
| --- | --- | --- |
| Website Requires Login (401) | The page is behind a login on your website | Login-protected pages can't be previewed. Use the widget or Chrome extension instead. |
| Page Not Found (404) | The path doesn't exist on your website | Check the URL for typos in the preview address bar. |
| Enable Public Website | The project isn't marked as a public website | Open project settings, enable Public Website, and retry. |
| Secure Session Expired | Preview sessions are short-lived for security | Refresh the preview page to start a new session. |
| Private Network Blocked | The URL points to localhost or an internal network | Only public websites can be previewed. Use the widget snippet for local development. |
| Connection Refused / Domain Not Found | The site is down or DNS is misconfigured | Open the site directly in a new tab to check it is online. |
| Iframe Embedding Blocked | The site has strict anti-framing protections | View the site directly and use the widget or Chrome extension for commenting. |
Preview limitations only affect the Site Preview feature. The embedded
widget and the Chrome extension work independently of the preview servers.
---
# Profile Settings
Update your personal information and account settings. These settings apply to your user account across all workspaces.
## Workspace settings
**Workspace settings** is visible in the sidebar, including while you are inside a project. It contains members, billing, branding, notification preferences, and **MCP & AI connections**. Membership, billing, and branding controls require a workspace admin; client accounts do not see workspace settings.
To connect an external AI tool or generate an API token, click the separate **MCP** item directly in the project sidebar or [open MCP settings](https://www.simplecommenter.com/app/account/ai-agent). Workspace owners authorize these connections.
In MCP settings, **Connected apps** shows hosted OAuth connections and lets you
review their projects, permissions, and last use, or disconnect them. **Local
API tokens** creates and revokes account-wide tokens for npm and REST clients.
Hosted browser setup uses sign-in and project selection; you do not need to
generate a local token for it. Follow the [MCP setup guide](https://www.simplecommenter.com/docs/integrations/ai-agent)
and check hosted availability before connecting.
## Personal Information
### Name
Your display name shown throughout the dashboard and in comments.
### Company
Your organization or company name. This is displayed in the workspace header.
## Account Settings
### Change Password
Update your account password:
1. Enter your current password
2. Enter your new password
3. Confirm the new password
4. Click **Save**
Password must be at least 8 characters. Use a mix of letters, numbers, and
symbols for better security.
## Account Information
View details about your account:
- **Created** - When your account was created
- **Current Plan** - Your subscription tier
- **Usage** - Current usage statistics
## Next Steps
- [Manage your subscription](https://www.simplecommenter.com/docs/dashboard/billing)
- [Configure notification preferences](https://www.simplecommenter.com/docs/dashboard/notifications)
- [Manage team members](https://www.simplecommenter.com/docs/dashboard/team)
---
# Status Management
Customize which statuses are available for comments and control who can use them based on their role.
You'll find these options in your project settings under **Workflow**, in the
**Statuses** tab.
## Available Statuses
Select which statuses are available in your project:
| Status | Description |
| --- | --- |
| To Do | New comments that need attention (required) |
| In Progress | Actively being worked on |
| Review | Ready for review or approval |
| Rework | Needs changes based on feedback |
| On Hold | Paused, waiting for external input |
| Blocked | Cannot proceed due to a dependency |
| Done | Completed and resolved |
| Cancelled | No longer relevant |
**To Do** is a required status and cannot be disabled. Every other status,
including Done, can be turned off per role.
## Default Active Statuses
Configure which statuses are shown by default when viewing comments.
This controls the initial filter when opening the comments page. Users can always change the filter to see other statuses.
**Common configurations:**
- Show only **To Do** and **Review** to focus on actionable items
- Show all statuses for a complete overview
- Hide **Cancelled** to reduce noise
## Role-Based Permissions
Control which statuses each role can set on comments:
### Workspace Admin
Full access to all enabled statuses. Can change any comment to any status.
### Team Lead
Configure which statuses team leads can set. Useful for limiting them to certain workflow stages.
### Client
Restrict clients to a subset of statuses. Typically clients might only be able to set:
- **To Do** - Report new issues
- **Review** - Mark something ready for review
- **Done** - Confirm a fix works
Role permissions only affect what users can set. All users can still view
comments in any status.
## Workflow Example
A typical client feedback workflow:
1. **Client** creates comment → Status: **To Do**
2. **Team Member** starts work → Status: **In Progress**
3. **Team Member** completes work → Status: **Review**
4. **Client** confirms fix → Status: **Done**
## Saving Changes
After adjusting settings, click **Save** in the bottom bar to apply changes.
## Next Steps
- [Filter comments by status](https://www.simplecommenter.com/docs/dashboard/comments)
- [Configure client access](https://www.simplecommenter.com/docs/dashboard/access)
---
# Team Collaboration
Work together with your team by inviting members into the workspace and giving
the right people access to each project.
## Inviting Team Members
### How to Invite
1. Go to **Members**
2. Click **Invite Members**
3. Enter their email address
4. Select their workspace role
5. Send the invite
The invitee receives an email with a link to join your workspace.
Team member limits depend on your plan. See [pricing](https://www.simplecommenter.com/pricing) for details.
## Roles & Permissions
The Members page currently supports these assignable workspace roles:
| Role | What it covers |
| --- | --- |
| Workspace Admin | Full workspace access, including members, projects, billing, and settings. |
| Team Lead | Can add projects and manage day-to-day feedback on the projects they are assigned to: comments, replies, statuses, tags, widget settings, and CSV export. |
Team leads cannot:
- Delete a project, or change its name or domain
- Manage billing or the subscription
- Invite or remove members
- Change account-level settings
These actions are reserved for workspace admins. When a team lead opens a
project's General settings, the configure and delete controls are replaced by a
notice pointing to a workspace admin.
Workspace owners appear separately in the members list and retain full
workspace access.
## Managing Members
Use the **Members** page to review who is in your workspace, see how many seats
are in use, and keep member access up to date as your team changes.
For larger teams, your backend can [create members through the REST API](https://www.simplecommenter.com/docs/rest-api/members-and-clients).
An automation can send one request per employee, so you do not need to enter
everyone manually. API-created members still need the owner's approval under
**Workspace settings → Company login** before using SSO. See
[Company login](https://www.simplecommenter.com/docs/dashboard/company-login) for account matching, first
login, and the current restriction on API access when SSO is required.
## Project-Level Access
Control access at the project level from the project's
[Access Settings](https://www.simplecommenter.com/docs/dashboard/access):
1. Open the project you want to manage
2. Go to **Access**
3. Use the **Team Members** section to assign or remove project access
This is useful when:
- Different teams manage different websites
- Clients should only see their own project
- Contractors need a limited project scope
## Collaboration Tips
### For Agencies
- Create separate projects per client
- Use project-level access to keep client work isolated
- Configure notifications per project so the right team gets alerted
### For Product Teams
- Use statuses to reflect your review workflow
- Connect Slack or webhooks for faster follow-up
- Restrict project access when outside collaborators are involved
### For Support Teams
- Use priorities and statuses to triage incoming feedback
- Keep replies inside comment threads so context stays together
- Review project access regularly as responsibilities change
## Next Steps
- [Access settings](https://www.simplecommenter.com/docs/dashboard/access)
- [Configure statuses](https://www.simplecommenter.com/docs/dashboard/statuses)
- [Slack integration](https://www.simplecommenter.com/docs/integrations/slack)
---
# Theme Configuration
Customize how the SimpleCommenter widget looks on your website. Match your brand colors and choose the layout that works best for your users.
## Where to Configure Theme
Theme settings are available in two locations:
### Default Theme (Account-wide)
Set default theme settings that apply to all new projects:
1. Go to **Project template** in the sidebar
2. Click **Widget**
3. Select the **Appearance** tab
All new projects will inherit these defaults. Existing projects are not affected.
### Project-Specific Theme
Override the default theme for individual projects:
1. Go to **Projects** in the sidebar
2. Select your project
3. Go to **Widget** in the project settings and select the **Appearance** tab
Project-level settings take priority over account defaults.
If a project has no custom theme configured, it automatically uses your
default theme settings.
## Color Settings
### Active Color (Primary)
The primary accent color used throughout the widget:
- Feedback button background
- Active state indicators
- Submit buttons and CTAs
- Comment markers on the page
Click the **Active** color swatch to open the color picker. Choose any color that matches your brand.
| Default | Hex Code |
| --- | --- |
| Yellow | #F7D070 |
### Overlay Color
The highlight color used for page overlays when users are selecting elements to comment on:
- Selection overlay background
- Element highlight indicators
Click the **Overlay** color swatch to customize this color.
| Default | Hex Code |
| --- | --- |
| Blue | #4098D7 |
Choose an overlay color that contrasts well with your website's content.
Semi-transparent overlays work best.
## Widget Position
Control where the widget appears on the page:
| Position | Description |
| --- | --- |
| Bottom left | Widget appears in the lower-left corner |
| Bottom center | Widget appears centered along the bottom edge |
| Bottom right | Widget appears in the lower-right corner |
| Side right | Widget docks vertically on the right edge |
| Side left | Widget docks vertically on the left edge |
Select your preferred position using the theme controls in the dashboard.
## Compact Modal
Enable a smaller, less intrusive feedback widget:
| Mode | Description |
| --- | --- |
| Standard | Full-size modal with three-button interface (disable, view, comment) |
| Compact | Minimized single-button design for a cleaner look |
Toggle **Compact Modal** on or off based on your preference:
- **Standard mode** — Shows a three-button interface letting users toggle between disabled, view-only, and comment modes
- **Compact mode** — Shows a single floating button that's less visually intrusive
Compact mode works well for websites where you want feedback collection
without distracting from the main content.
## Live Preview
As you adjust theme settings, the **Modal Preview** section shows a real-time preview of how your widget will appear:
- See your color choices applied instantly
- Preview the widget position
- Toggle between standard and compact modes to compare
## Saving Changes
After making changes:
1. The **Save All Settings** button appears when you have unsaved changes
2. Click to save your theme configuration
3. Changes apply to the widget immediately
### Restore Defaults
Click **Restore Default** to reset all theme settings to the original values:
- Active color: `#F7D070` (yellow)
- Overlay color: `#4098D7` (blue)
- Position: Bottom right
- Compact mode: Off
## Theme Properties Reference
Preferred widget position. Options: `bottom-right`, `bottom-center`,
`bottom-left`, `side-right`, `side-left`. Default: `bottom-right`
Hex color code for the primary/active color. Default: `#F7D070`
Hex color code for the selection overlay. Default: `#4098D7`
Hex color code for text. Default: `#000000`
Hex color code for borders. Default: `#000000`
Hex color code for backgrounds. Default: `#FFFFFF`
Legacy numeric alignment fallback: `0` (bottom-right), `1`
(bottom-center), `2` (bottom-left), `3` (side-right), `4` (side-left).
Default: `0`
Enable compact modal mode. Default: `false`
## Theme Inheritance
SimpleCommenter uses a cascade system for themes:
```
Project Theme → Default Theme → System Defaults
```
1. **Project Theme** — If set, this is used
2. **Default Theme** — Falls back to your account defaults
3. **System Defaults** — Uses SimpleCommenter's built-in theme
This allows you to set once and apply everywhere, while still customizing individual projects when needed.
The embed script identifies which project to load. The widget's color and
placement come from the saved project theme and are not overridden by script
tag attributes.
## Next Steps
- [Widget Customization](https://www.simplecommenter.com/docs/widget/customization) — Learn how widget appearance is managed from the dashboard
- [Project Settings](https://www.simplecommenter.com/docs/dashboard/general) — Other project configuration options
- [Installation Guide](https://www.simplecommenter.com/docs/installation) — Add the widget to your website
---
# Dev Briefs
A client writes "this looks weird on mobile". A few seconds later, under their words, a short brief appears that a developer, a Jira card, or a coding agent can act on: a one-line title, two sentences naming the element and the likely cause, an optional fix, and the facts the widget captured. The client's words are never rewritten, and clients never see the brief.
Dev briefs are on by default for every project. Turn them off, or tune
them, per project under **Workflow → Dev briefs**.
## What a Brief Contains
| Part | Example |
| --- | --- |
| Title | Hero heading overflows its container at 375px |
| Summary | The `.hero h1` is a fixed 48px, so on phone widths the last word wraps under the CTA button. |
| Likely fix | `font-size: clamp(28px, 7vw, 48px)` on the heading, or let the container wrap. |
| Facts | The element selector, viewport, browser, and page, taken from the comment itself. |
| Kind | layout, copy, link, visual, behavior, or other |
| Confidence | high when the captured data confirms the problem, medium when it is consistent with it, low when inferred mostly from the words |
## Where It Comes From
When someone clicks an element and leaves a comment, the widget already records the element (tag, id, classes, text), how it was rendered at that moment (computed style, its box and its parent's box), the device (viewport, screen, pixel ratio, browser, OS, language), the page, and a screenshot. The brief is written from that data plus the comment text.
Nothing else goes to the model. Names, emails, replies, and other comments are never sent.
## Console Errors
When a visitor leaves a comment, the widget also saves the JavaScript errors that happened on that page before the click: `console.error` calls, uncaught exceptions, and unhandled promise rejections. Never `console.log` or warnings. The last 10 errors are kept, each with its message, the script it came from with line and column, and how long after page load it happened.
Developers see them under **Technical info** on the dashboard card, on the board, in the widget drawer, and in the WordPress plugin inbox, as a count that opens the full list with a **Copy all** button. The brief reads the five most recent and, for a behaviour report ("the button does nothing"), names the one error most likely behind it with its file and line instead of guessing at a cause.
Before anything leaves the page, query strings and hashes are stripped from script URLs and anything that looks like a key, token or email address in the message is replaced with `[redacted]`. Errors from browser extensions and from the widget itself are dropped. Like briefs, console errors are for your team only: clients never receive them anywhere, including the REST API and MCP.
The Chrome extension only sees errors from the moment it loads on a page, not the ones before.
Turn capture off, or keep the errors out of the brief, per project under
**Workflow → Dev briefs**. When capture is off the widget installs no hooks
and nothing is collected.
## When a Brief Is Skipped
Not every comment is a task. Approvals ("looks good"), thanks, questions aimed at a person, and comments too unclear to turn into work get no brief and show nothing. There is no empty box: if a comment has no brief, the card looks exactly as it did before.
## Who Sees It
Briefs are for the people doing the work. Workspace admins and team leads see them on the dashboard, on the board, and in the widget. Clients never see a brief anywhere, including the REST API when called with a client scope, and MCP tools.
## Reading and Editing a Brief
On the dashboard, the brief sits directly under the comment text. From there you can:
- **Copy** the brief, with the element facts, for a ticket or a chat message.
- **Rate** it helpful or not right. Ratings feed the quality review, nothing else.
- **Edit** the title, summary, or fix. Once a person edits a brief the model never overwrites it, and the label shows who edited it.
- **Write again** to regenerate an unedited brief, or **Remove** it.
- **Write dev brief** from the card menu for a comment that has none, for example one posted before the setting was on.
In the widget, the brief is a toggle beside **Tech info**. Right after you post a comment it opens on its own and fills in as the brief is written. It adds **Highlight element**, which pulses the element the brief is talking about on the live page, and the same helpful / not right thumbs as the dashboard.
If your project is connected through the WordPress plugin, or runs on Shopify, the brief knows that and points fixes at the theme, block, or plugin setting where they live rather than at raw CSS.
## Settings
Under **Workflow → Dev briefs** on a project:
| Setting | What it does |
| --- | --- |
| Write a dev brief for new comments | The master switch. On by default. |
| Include a suggested fix | Adds a likely CSS or copy change. Turn off if you'd rather the brief only describe the problem. |
| Use the screenshot | Sends the comment's screenshot along with the element data. Better briefs for visual issues, a little slower. |
| Capture console errors | Saves the page's last 10 JavaScript errors with each new comment and shows them under Technical info. On by default, and works even when briefs are off. |
| Use them in the brief | Sends those errors to the model so the brief can cite the one behind the report. Turn off to keep errors visible to developers but out of the AI input. |
| Brief language | Free text. Type the language or style your team reads, for example "English", "Estonian", or "German, formal". Clients can keep writing in any language. |
| Use the brief title in integrations | Once the brief is written, connected tools retitle their card with it (see below). |
The same settings live under **Default settings → Workflow → Dev briefs** for what new projects start with.
## Integrations
The card or message for a new comment goes out immediately, as before. A few seconds later, when the brief is ready, the integration updates what it already created:
| Integration | What happens |
| --- | --- |
| Slack, Discord | A threaded reply with the brief under the original message. The original headline is updated to the brief title. |
| Jira, Linear, GitHub, Trello, ClickUp, Asana | The card or issue is retitled and a "Dev brief" section is added to its description. |
| Monday | The item is renamed and an update with the brief is posted. |
| Webhooks | A second `comment` payload with `event: "brief_ready"` and a `brief` object, so your receiver can update by `commentId`. |
| Email | Unchanged. The new-comment email is sent before the brief exists. |
Turn off **Use the brief title in integrations** to keep the original headline and only add the brief to the description.
Console errors travel with the new-comment card itself, not the brief update: Jira, Linear, GitHub, ClickUp, Trello, Asana and Monday get a short "Console errors" block (at most three entries, oldest first), Slack and Discord get one line naming the count and the latest error, the email integration gets the same lines under the comment text, and webhook payloads carry the full list under `metadata.consoleErrors`.
## API and AI Agents
Comments returned by the [REST API](https://www.simplecommenter.com/docs/rest-api) carry a `brief` object once one exists:
```json
{
"brief": {
"status": "ready",
"title": "Hero heading overflows its container at 375px",
"summary": "The .hero h1 is a fixed 48px, so on phone widths the last word wraps under the CTA button.",
"suggestedFix": "font-size: clamp(28px, 7vw, 48px) on .hero h1",
"kind": "layout",
"confidence": "medium",
"generatedAt": "2026-09-02T09:41:12Z"
}
}
```
`status` is `pending` while the brief is being written, `ready` when it exists, `paused` when the account's allowance is used up, and `skipped` or `failed` otherwise. `editedBy` and `editedAt` appear when a person changed it.
The [AI Agent (MCP)](https://www.simplecommenter.com/docs/integrations/ai-agent) tools return the same object: `list_comments` includes the brief title and kind, and `get_comment` the full brief. An agent should read the brief first, since it already names the element and the likely change. The dashboard [AI Assistant](https://www.simplecommenter.com/docs/ai-assistant) also sees briefs when answering questions about your feedback.
Console errors come along the same way. The REST API returns `metadata.consoleErrors` with `include=metadata_full` (and `metadata.consoleErrorCount` always), `get_comment` includes the full list, and `list_comments` items carry `consoleErrorCount` so an agent knows which comments are worth opening:
```json
{
"metadata": {
"consoleErrors": [
{
"kind": "uncaught",
"message": "TypeError: Cannot read properties of undefined (reading 'variantId')",
"source": "https://example.com/assets/cart.js",
"line": 120,
"col": 14,
"at": 4213
}
]
}
}
```
`kind` is `console`, `uncaught` or `rejection`; `at` is milliseconds since the page started loading.
## Plans and Allowance
Briefs are included on every paid plan with no limit. Trials include 20 briefs. When the 20th is written, later comments show a small paused line with an upgrade link, and one email goes out. Briefs paused during the last week of a trial are written automatically once the account is on a plan.
Only briefs that are actually written count. Skipped comments cost nothing.
Briefs are written by Claude and can be wrong. Treat them as a strong first
read of the comment, not as a verified diagnosis, and correct them where it
matters. Every brief keeps the original comment intact right above it.
---
# Bubble Installation
Add Simple Commenter to your Bubble.io application using the SEO/metatags settings or an HTML element.
## Method 1: SEO/Metatags Settings (Recommended)
This adds the script to all pages in your app.
### 1. Open App Settings
1. Open your Bubble app editor
2. Go to **Settings** in the left sidebar
3. Click the **SEO/metatags** tab
### 2. Add the Script
1. Scroll to the **Script/meta tags in header** section
2. Paste this code:
```html
```
3. Click outside the field to save
Replace `sc_your_project_key` with your project's public key from the Simple
Commenter dashboard.
## Method 2: HTML Element
For more control over where the script loads:
1. Add an **HTML** element to your page
2. Paste the script code
3. Position it at the bottom of your page (it won't be visible)
4. Preview or deploy
## Method 3: Page-Level Script
To add to specific pages only:
1. Open the page in the editor
2. Click on the page background
3. In the property editor, find **SEO/metatags**
4. Add the script in the header tags section
## Verifying Installation
1. Preview your app or deploy to live
2. Visit the live URL (not the editor)
3. Look for the feedback widget button
4. Check browser Developer Tools (F12) for errors
## Troubleshooting
### Widget not appearing in editor
The widget won't appear in the Bubble editor. Use Preview mode or view the deployed app.
### Widget not appearing on deployed app
- Check you deployed after adding the code
- Verify you're viewing the correct version (development vs live)
- Ensure the public key matches your dashboard settings
- Clear your browser cache
### Same key for dev and live
The same public key works across both your development and production environments, so you only need one script tag:
```html
```
### Single-page app behavior
Bubble apps are SPAs. The widget loads once and persists across page navigation within the app.
Need help? [Contact support](https://www.simplecommenter.com/support).
---
# Django Installation
Add Simple Commenter to your Django application by adding the script to your base template.
**Important:** The public key in your script must match a project in your [Simple Commenter dashboard](https://www.simplecommenter.com/app). If it doesn't match, the widget won't load.
## Basic Installation
Add the script to your base template that other templates extend:
```html
{% block title %}My Django App{% endblock %}
{% block extra_head %}{% endblock %}
{% block content %}{% endblock %}
```
Replace `sc_your_public_key` with your project's public key from the Simple Commenter dashboard.
## Using Django Settings
Store the public key in your settings for easier management:
```python
# settings.py
SIMPLE_COMMENTER_KEY = "sc_your_public_key"
```
Create a context processor:
```python
# myapp/context_processors.py
from django.conf import settings
def simple_commenter(request):
return {
'simple_commenter_key': getattr(settings, 'SIMPLE_COMMENTER_KEY', '')
}
```
Add to settings:
```python
# settings.py
TEMPLATES = [
{
'OPTIONS': {
'context_processors': [
# ... other processors
'myapp.context_processors.simple_commenter',
],
},
},
]
```
Use in template:
```html
{% if simple_commenter_key %}
{% endif %}
```
## Environment-Based Configuration
Use environment variables for different environments:
```python
# settings.py
import os
SIMPLE_COMMENTER_KEY = os.environ.get('SIMPLE_COMMENTER_KEY', '')
```
```bash
# .env or environment
SIMPLE_COMMENTER_KEY=sc_your_public_key
```
## Conditional Loading
Only load on certain views or conditions:
```html
{% if show_feedback_widget %}
{% endif %}
```
In your view:
```python
# views.py
def my_view(request):
return render(request, 'my_template.html', {
'show_feedback_widget': True # or some condition
})
```
## Page-Specific Widget
To only add to specific pages, use template blocks:
```html
{% block extra_scripts %}{% endblock %}
```
```html
{% extends "base.html" %}
{% block extra_scripts %}
{% endblock %}
```
## Django REST Framework / API-Only
If your Django app is API-only with a separate frontend, add the script to your frontend instead. See the [React](https://www.simplecommenter.com/docs/installation/react), [Vue](https://www.simplecommenter.com/docs/installation/vue), or [General Installation](https://www.simplecommenter.com/docs/installation) guides.
## Verifying Installation
1. Run your development server (`python manage.py runserver`)
2. Open your app in the browser
3. Look for the feedback widget button
4. Check browser console (F12) for errors
5. Verify across different pages
## Troubleshooting
### Widget not appearing
- Check that your template extends the base template correctly
- Verify the public key matches your dashboard settings
- Inspect the page source to confirm the script tag is present
- Look for JavaScript errors in browser console
### Template inheritance issues
- Ensure `{% extends "base.html" %}` is at the top of child templates
- Check that the script is outside any blocks that might be overridden
### Static files / Production
In production:
- The script is hosted externally, so Django's static files settings don't affect it
- Ensure your production domain is registered in your dashboard
- Consider using different domains for staging vs production
### Admin panel
The widget will appear in the Django admin by default if using the same base template. To exclude:
```html
{% if not request.path|slice:":7" == "/admin/" %}
{% endif %}
```
Need help? [Contact support](https://www.simplecommenter.com/support).
---
# Flask Installation
Add Simple Commenter to your Flask application by adding the script to your Jinja templates.
**Important:** The public key in your script must match a project in your [Simple Commenter dashboard](https://www.simplecommenter.com/app). If it doesn't match, the widget won't load.
## Basic Installation
Add the script to your base template:
```html
{% block title %}My Flask App{% endblock %}
{% block content %}{% endblock %}
```
Your other templates extend this:
```html
{% extends "base.html" %}
{% block title %}Home{% endblock %}
{% block content %}
Welcome
{% endblock %}
```
Replace `sc_your_public_key` with your project's public key from the Simple Commenter dashboard.
## Using Flask Config
Store the public key in your Flask configuration:
```python
# config.py or app.py
class Config:
SIMPLE_COMMENTER_KEY = "sc_your_public_key"
```
Make it available to templates:
```python
# app.py
from flask import Flask
app = Flask(__name__)
app.config.from_object('config.Config')
@app.context_processor
def inject_simple_commenter():
return dict(
simple_commenter_key=app.config.get('SIMPLE_COMMENTER_KEY', '')
)
```
Use in template:
```html
{% if simple_commenter_key %}
{% endif %}
```
## Environment Variables
Use environment variables for different environments:
```python
# app.py
import os
app.config['SIMPLE_COMMENTER_KEY'] = os.environ.get(
'SIMPLE_COMMENTER_KEY',
''
)
```
```bash
# .env or environment
SIMPLE_COMMENTER_KEY=sc_your_public_key
```
With python-dotenv:
```python
# app.py
from dotenv import load_dotenv
load_dotenv()
app.config['SIMPLE_COMMENTER_KEY'] = os.getenv('SIMPLE_COMMENTER_KEY')
```
## Conditional Loading
Only load on certain routes:
```python
# app.py
@app.context_processor
def inject_simple_commenter():
from flask import request
# Don't show on admin routes
show_widget = not request.path.startswith('/admin')
return dict(
show_feedback_widget=show_widget,
simple_commenter_key=app.config.get('SIMPLE_COMMENTER_KEY', '')
)
```
```html
{% if show_feedback_widget and simple_commenter_key %}
{% endif %}
```
## Page-Specific Widget
Use template blocks:
```html
{% block extra_scripts %}{% endblock %}
```
```html
{% extends "base.html" %}
{% block extra_scripts %}
{% endblock %}
```
## Flask Blueprints
If using blueprints, the context processor works across all blueprints when registered on the app:
```python
# app.py
app = Flask(__name__)
@app.context_processor
def inject_simple_commenter():
return dict(simple_commenter_key='sc_your_public_key')
# Register blueprints
from views import main_bp
app.register_blueprint(main_bp)
```
## Verifying Installation
1. Run your development server (`flask run`)
2. Open your app in the browser
3. Look for the feedback widget button
4. Check browser console (F12) for errors
5. Navigate to different routes
## Troubleshooting
### Widget not appearing
- Check that your template extends base.html correctly
- Verify the public key matches your dashboard settings
- View page source to confirm the script is present
- Look for JavaScript errors in browser console
### Template not extending correctly
- Ensure `{% extends "base.html" %}` is at the top
- Check the template file is in the correct directory
- Verify Flask's template folder configuration
### Blueprint-specific issues
- Context processors on the app work for all blueprints
- Blueprint-specific context processors only work for that blueprint
- Register app-wide for consistent behavior
### Production deployment
- Ensure your production domain is registered in the dashboard
- The script is hosted externally, unaffected by Flask's static file handling
- Works with Gunicorn, uWSGI, etc.
Need help? [Contact support](https://www.simplecommenter.com/support).
---
# Framer Installation
Add Simple Commenter to your Framer site using the custom code settings.
## Step-by-Step Installation
### 1. Open Site Settings
1. Open your project in Framer
2. Click the gear icon or go to **Site Settings**
3. Navigate to the **General** tab
### 2. Add Custom Code
1. Scroll down to **Custom Code**
2. In the **End of `` tag** section, paste:
```html
```
3. Click **Save** or close the settings panel
Replace `sc_your_project_key` with your project's public key from the Simple
Commenter dashboard.
### 3. Publish Your Site
1. Click **Publish** in the top right
2. Your changes will go live
## Using a Code Component (Alternative)
You can also create a code component:
1. Click the **+** button to add a new component
2. Select **Code** component
3. Add this code:
```jsx
export default function SimpleCommenter() {
React.useEffect(() => {
const script = document.createElement("script");
script.src = "https://simplecommenter.com/js/comments.min.js";
script.dataset.id = "sc_your_project_key";
script.defer = true;
document.body.appendChild(script);
return () => {
document.body.removeChild(script);
};
}, []);
return null;
}
```
4. Add the component to your page
5. Publish
The Site Settings method is recommended as it applies to all pages
automatically.
## Verifying Installation
1. Publish your site
2. Visit the live site (not the editor preview)
3. Look for the feedback widget button
4. Check browser Developer Tools (F12) for errors
## Troubleshooting
### Widget not appearing in editor
The widget won't appear in the Framer editor. You must view the published site.
### Widget not appearing on published site
- Ensure you published after adding the code
- Check the code is in the "End of body" section
- Verify the public key matches your dashboard settings
- Clear your browser cache
### Staging vs Production
The same public key works across both staging and production sites.
Need help? [Contact support](https://www.simplecommenter.com/support).
---
# Ghost Installation
Add Simple Commenter to your Ghost blog using the built-in Code Injection feature.
## Step-by-Step Installation
### 1. Open Code Injection
1. Go to your Ghost Admin panel
2. Click **Settings** (gear icon) in the left sidebar
3. Scroll down and click **Code injection**
### 2. Add the Script
1. In the **Site Footer** section, paste:
```html
```
2. Click **Save**
Replace `sc_your_project_key` with your project's public key from the Simple
Commenter dashboard.
## Ghost(Pro) vs Self-Hosted
Both Ghost(Pro) and self-hosted Ghost installations support code injection. The process is the same, and the same public key works for either.
## Theme Integration (Advanced)
For more control, edit your theme directly:
1. Download your theme from **Settings > Design > Change theme > Advanced**
2. Edit `default.hbs`
3. Add the script before ``
4. Zip and re-upload the theme
```handlebars
{{! In default.hbs, before }}