Web Widget

Overview

The Complaintr web widget adds a floating feedback launcher to any website or web application. Visitors can report an issue without leaving the page. The complaint assistant asks focused follow-up questions, creates a useful title and description, and submits the complaint to the application you select.

The distributed widget.js file is the single widget implementation used by embedded products and the Complaintr landing site. It includes Home, Messages, News, Help, and feature requests. Complaint conversations are held only in the browser while the widget is open. Complaintr does not create a chat thread for the widget. Feature requests are stored as complaints with feedbackType: "feature_request" metadata so the application owner can review them.

Before you install

1. Sign in to the Complaintr dashboard.
2. Register the website or product under Applications.
3. Open Integrations > In-app complaint widget > Setup.
4. Select the application that should receive complaints.
5. Customize the widget and select Save customization.

The application name is the widget identity. It is matched case-insensitively, but it must refer to an application that already exists.

Widget appearance is stored separately for every application. Existing installations request the current position, color, title, welcome message, and announcement banner from Complaintr when the script loads and each time a visitor opens the launcher. You do not need to replace the embed code after saving a change.

The Complaintr landing site uses the application named Complaintr. Saving customization for that application updates the landing widget as well.

Install on an HTML site

Paste the generated script once, immediately before the closing </body> tag:

<script
  src="https://app.complaintr.com/widget.js"
  data-app="My Product"
  data-position="bottom-right"
  data-color="#ff2d1c"
  data-title="Hi there."
  data-welcome="How can we help?"
  defer
></script>

The script has no runtime dependencies. It uses Shadow DOM to isolate its layout and styles from the host page. The visual attributes in the generated tag are safe fallback values for temporary configuration service failures. Saved application settings take precedence.

Install in Next.js

Add a small component to the root layout so the script loads once:

import Script from "next/script";

export function ComplaintrWidget() {
  return (
    <Script
      src="https://app.complaintr.com/widget.js"
      data-app="My Product"
      data-position="bottom-right"
      data-color="#ff2d1c"
      data-title="Hi there."
      data-welcome="How can we help?"
      strategy="afterInteractive"
    />
  );
}

Render <ComplaintrWidget /> once in your top-level app/layout.tsx.

Install in React or another SPA

Add the standard HTML script tag to the application shell, usually public/index.html, immediately before </body>. Do not render one script per route. The widget already follows client-side navigation and records the current page URL when a complaint is submitted.

Configuration reference

The API base URL is derived from the src attribute, not from the website embedding the widget. A production script loaded from https://app.complaintr.com/widget.js therefore loads its application settings from https://app.complaintr.com/api/v1/widget/config and sends chat requests to https://app.complaintr.com/api/v1/widget/chat.

Announcement banner

The widget home screen shows a small announcement banner between the quick actions and the navigation. Set it from Integrations > In-app complaint widget > Setup, or pass the data-banner-* attributes directly:

<script
  src="https://app.complaintr.com/widget.js"
  data-app="My Product"
  data-banner-title="We are hiring"
  data-banner-text="Join the team building My Product"
  data-banner-url="https://my-product.com/careers"
  defer
></script>

Rules:

• An empty banner title hides the banner completely.
• The banner opens the link in a new tab when a URL is present.
• An empty URL opens the Complaintr landing page, which keeps the default Powered by Complaintr banner clickable without configuration.
• The banner is stored per application, so saved settings apply to every existing installation without replacing the embed code.

Widget news

The News tab shows announcements for the application embedding the widget. Manage them from Integrations > In-app complaint widget > Setup, in the Widget news section: add a title, category (News or Changelogs), date, optional badge and summary, a banner color from six presets, and the article content (each line becomes a paragraph).

News is stored per application and delivered with the widget configuration, so visitors see it without any code change. When an application has no news items, the tab shows an empty state instead of fallback content.

Widget help

The Help tab shows support articles for the application embedding the widget. Manage them from Integrations > In-app complaint widget > Setup, in the Widget help section: each article has a title, optional summary, category, read time, and an icon (any emoji or symbol), plus one or more sections. A section is a heading, a body, and an optional code block that visitors can copy with one click.

Articles are stored per application and delivered with the widget configuration. When an application has no articles, the tab shows an empty state without the search box.

Launcher button

The floating launcher is a round button whose icon and background are per-application settings. Set them from Integrations > In-app complaint widget > Setup, or pass the attributes directly:

<script
  src="https://app.complaintr.com/widget.js"
  data-app="My Product"
  data-launcher-icon="bug"
  data-launcher-style="white"
  defer
></script>

Icon presets: complaintr (the Complaintr logo), chat, bug, megaphone, and chevron. Background presets: gradient (the application accent color), white, and dark. The complaintr icon renders in dark on the white background and in white otherwise. Unknown values fall back to the defaults.

How complaint submission works

1. The dedicated Report an issue form sends the selected application, description, optional email, and current page URL to the public widget endpoint.
2. Request a feature sends the suggestion and optional email to the same endpoint. Complaintr stores it as a complaint marked with feature-request metadata.
3. Complaintr returns the submitted confirmation used by each success screen.
4. Messages sends up to 30 in-memory conversation messages to the same endpoint. The assistant can answer focused Complaintr support questions or collect missing actual behavior, expected behavior, and reproduction context.
5. When a conversation report is actionable, the assistant calls the server-side submit_complaint tool.
6. Complaintr stores every submission path with the Web widget source. If the application owner enabled Telegram notifications, Complaintr also sends the normal complaint alert.

The interactive preview on the setup page never sends messages, complaints, or feature requests to the API.

Complaint creation always happens on the Complaintr server. The browser never receives database credentials or access to authenticated workspace tools.

Input

The widget accepts text input only. It does not expose voice input, file uploads, or attachment controls.

Verify the installation

1. Deploy the page and confirm the launcher appears in the configured corner.
2. Open Report an issue or Messages.
3. Describe a test problem and answer the assistant's questions.
4. Wait for the submitted confirmation.
5. Open Complaints in Complaintr and find the report with the Web widget source badge.
6. Remove or resolve the test complaint when verification is complete.

Security and limits

• Widget chat accepts cross-origin requests so the script can run on any website.
• Requests are limited to 20 per IP address and 30 per application per minute.
• Each message is limited to 4,000 characters, with at most 30 messages per request.
• The endpoint exposes only one AI tool, submit_complaint.
• The endpoint does not expose workspace search, complaint status changes, or the authenticated Complaintr assistant tools.
• AI usage is recorded against the owner of the selected application.

Troubleshooting

The launcher does not appear

• Confirm the script loads successfully in the browser Network panel.
• Confirm data-app is present and non-empty.
• Make sure the script is installed only once.
• Check the browser console for a [Complaintr] configuration message.

Application not found

The endpoint returns 404 when data-app does not match a registered application. Copy the application name from Applications or regenerate the snippet from the integration setup page.

AI provider is not configured

Messages returns 503 when the Complaintr web deployment has no credentials for its selected AI provider. The dedicated report form does not require the AI provider. Configure OPENROUTER_API_KEY when COMPLAINTR_AI_PROVIDER=openrouter, or BEDROCK_MANTLE_API_KEY when the provider is bedrock.

Too many requests

The endpoint returns 429 after 20 requests from the same IP address or 30 requests for the same application within one minute. Wait for the current window to reset before retrying.

The widget is hidden behind another element

The launcher and panel use a high fixed stacking order. If the host page applies transforms, clipping, or visibility rules to the document root, inspect those global rules. Shadow DOM prevents ordinary component styles from changing the widget itself.

Local development

Load the script from the local web app and use an application registered in the local database:

<script
  src="http://localhost:3000/widget.js"
  data-app="Local Test App"
  data-endpoint="http://localhost:3000/api/v1/widget/chat"
  defer
></script>

The web app must have PostgreSQL and the configured AI provider available.