Common setup

These steps apply to every Product, hosted or self-hosted. Open a Product from Settings → Products. Its settings have four tabs, General, Widget, Email and Developer. Changing a Product's settings needs an Admin account.

Allowed domains#

The widget only loads on hostnames you list. Open the Product, stay on the General tab and find the Domains card. Enter a hostname under Add domain and choose Add. Saving needs no DNS changes.

Entries match the exact hostname.

• If visitors reach your site on both example.com and www.example.com, allow both. When you add one, the card offers the other as Also allow …. It is ticked by default.
• A pasted URL such as https://Example.com/pricing is reduced to its hostname.
• A subdomain such as app.example.com is its own entry, unless a *. entry covers it.
• A server running in development mode accepts localhost, 127.0.0.1 and ::1 without an entry. A production server, including the hosted service, accepts none of them. Add the hostname you use, such as localhost, to test from a local page. The wizard's Allow localhost for development option adds localhost.

Support email#

Open the Email tab of the Product. Replies to customers are sent from a managed sender named after your Product, such as "Acme Support", so you do not configure outbound mail per Product.

The generated address#

Every Product gets a generated inbound address, shaped like product_xxx@…. This is the default and needs no DNS changes.

1. Copy the address

   Use the Copy address button in the Receive support email card.

2. Forward your support address to it

   In your mail provider, create a forward, rule or redirect from your existing address, such as [email protected], to the generated address. Keep it active, because only mail sent to the generated address arrives. The card has Forwarding help for Gmail and Google Workspace, Microsoft 365 and other providers. Forward the support mailbox only.

3. Send a test email

   The card reads Waiting for the first email… until one arrives. Then it shows a Receiving badge with the time of the last email.

Your public support address#

Optional. Under Support address (optional), enter the address customers write to in Support email and choose Save support address. The chat widget shows it as an alternative contact when you are away. SupportSeal also treats it as your own address and never sends mail to it, so forwarding it into the inbox cannot create a loop.

A custom mail domain#

Optional. A Product can own a dedicated mail domain. Once it is verified, mail to any address at that domain reaches the Product's inbox.

1. Enter the domain

   Enter a dedicated domain or subdomain under Your mail domain and choose Show DNS records.

2. Add the records

   Add the records shown at your DNS provider.

3. Verify

   Choose Verify records. DNS changes can take minutes, and cached records can take longer. Try again later if the check fails. Chat and the generated address keep working in the meantime.

Install the widget#

Open the Widget tab of the Product. The Chat widget embed card shows the install snippet and the Widget key, which starts with pk_, each with a copy button. The key is public. It identifies the Product and works only on the domains you allowed. There is no secret key to manage.

Keep the script URL exactly as the snippet shows it. On the hosted service new snippets load from https://dashboard.supportseal.app/widget.js. Existing snippets that load from https://supportseal.app/widget.js keep working. On a self-hosted installation, the URL is your installation's public URL.

Plain HTML#

Paste the tag directly before </body> on every page that should show the widget. Replace pk_… with your Product's key.

<script
  async
  src="https://dashboard.supportseal.app/widget.js"
  data-key="pk_…"
></script>

Next.js and React#

Use this component instead of the script tag. Save it as SupportWidget.jsx and render <SupportWidget /> once in your root layout, or once in your app shell for plain React. Keep it mounted across route changes.

Replace WIDGET_SERVER_URL with the origin from your install snippet, with no trailing slash. Replace PUBLIC_WIDGET_KEY with your Product's widget key.

"use client";

import { useEffect } from "react";

export default function SupportWidget({ user }) {
  const id = user?.id;
  const email = user?.email;
  const name = user?.name;

  useEffect(() => {
    window.SupportSealWidget = window.SupportSealWidget || { q: [] };
    // Optional: pass your app's signed-in user, not a placeholder user.
    if (id) {
      window.SupportSealWidget.q.push(["identify", { id, email, name }]);
    }

    // Install once, including during React development effect re-runs.
    if (document.getElementById("support-widget-script")) return;
    const script = document.createElement("script");
    script.id = "support-widget-script";
    script.async = true;
    script.src = "WIDGET_SERVER_URL/widget.js";
    script.dataset.key = "PUBLIC_WIDGET_KEY";
    document.body.appendChild(script);
  }, [id, email, name]);

  return null;
}

Identify signed-in users#

Optional. Pass your own signed-in user so the Conversation shows who wrote. In React, render <SupportWidget user={user} /> with string id, email and name fields. Omit the prop for anonymous chat. With plain HTML, queue the identity before the embed tag.

<script>
  window.SupportSealWidget = window.SupportSealWidget || { q: [] };
  window.SupportSealWidget.q.push(["identify", {
    id: "user_123",
    email: "[email protected]",
    name: "Sam Morgan",
  }]);
</script>

Test the widget#

There are two test pages, and they behave differently.

• On the Widget tab, Open test page opens the real chat bubble in preview mode. A Live and Away switch lets you see both states. Messages you send there stay in preview and nothing reaches the inbox.
• In the setup wizard, Open test page (new tab) runs the live widget on a SupportSeal page, with no allowed domain needed. A message you send creates a real Conversation. The link works for 30 minutes. After that the page reads This test link expired. You can generate a new link from the wizard's Install step only until the first Conversation exists. After that, the Install step redirects to Settings → Products. Use Open test page on the Widget tab, which is preview only, or send a chat from your own site.

To test on your own site instead, install the snippet, make sure its hostname is in Allowed domains and send a chat.

Add a second Product#

A second Product uses the same Workspace and the same inbox. Each Product keeps its own domains, widget key, support address and branding. This step needs an Admin account.

1. Open Settings → Products

   Under Add a Product, enter a Product name and a Primary colour. You can list Domains here or add them afterwards.

2. Choose Create Product

   The Product appears in the list and opens its settings. A widget key and an inbound support address are generated for it.

3. Repeat the setup

   Allow its domains, install its snippet and set up its support email, using the sections above.

To retire a Product, open the Archive Product card on its General tab and choose Archive. Mail sent to its support address bounces while it is archived. The card is then headed Unarchive Product, and its Unarchive button reverses the change.

Smoke test#

Run this on your live site, or on a staging site whose hostname you allowed.

• The Product appears under Settings → Products with the right name and colour.
• Every hostname visitors use is listed under Domains, including both the bare domain and www where both resolve.
• The widget bubble appears on the site. If it does not, open the browser console and read the message described under Troubleshooting.
• A chat message from the widget shows up in the inbox for this Product. Your reply reaches the widget.
• An email to the generated address appears in the inbox for this Product. Your reply arrives from the managed sender named after your Product, such as "Acme Support".
• If forwarding is set up, a test to your public support address lands in the inbox.

Troubleshooting#

If the widget does not appear, open the browser console. A rejected page logs an error that begins with [SupportSeal] Widget not loaded:. It names the page origin, meaning its scheme, host and port. It then tells you which bare hostname to add under Domains. The origin and the hostname below are placeholders.

[SupportSeal] Widget not loaded: https://www.example.com:3000 is not in the allowed domains of this product. Add "www.example.com" under Settings > Products > (your product) > Domains: https://dashboard.supportseal.app/settings/products

Add that bare hostname, with no scheme or port, under Domains and reload the page.