Embed Script Quickstart

Use this guide to add SupportGPT to a website.

1. Copy Your Agent ID

Open the dashboard:

Go to your workspace.
Open the agent.
Go to Deploy -> Embed.
Copy the generated snippet.

The dashboard fills in your real chatbotId.

2. Install The Chat Bubble

Paste this snippet before the closing </body> tag, or in the site-wide template for your app.

<script>
  (async function () {
    const s = document.createElement("script");
    s.src = "https://supportgpt.app/embed.min.js";
    s.async = true;
    s.onload = function () {
      window.supportgpt.init({
        chatbotId: "YOUR_AGENT_ID"
      });
    };
    const firstScript = document.getElementsByTagName("script")[0];
    firstScript.parentNode.insertBefore(s, firstScript);
  })();
</script>

The chat bubble uses the agent's chat interface settings for theme, colors, display name, suggested messages, feedback controls, and bubble position.

3. Install In Next.js

Add the script to a layout or page with next/script.

import Script from "next/script";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script id="supportgpt-widget" strategy="afterInteractive">
          {`
            (async function () {
              const s = document.createElement("script");
              s.src = "https://supportgpt.app/embed.min.js";
              s.async = true;
              s.onload = function () {
                window.supportgpt.init({
                  chatbotId: "YOUR_AGENT_ID"
                });
              };
              const firstScript = document.getElementsByTagName("script")[0];
              firstScript.parentNode.insertBefore(s, firstScript);
            })();
          `}
        </Script>
      </body>
    </html>
  );
}

4. Use The Iframe

Use an iframe when you want the full chat inside a page area instead of a floating bubble.

<iframe
  src="https://supportgpt.app/chatbot-iframe/YOUR_AGENT_ID"
  width="100%"
  style="height: 100%; min-height: 700px"
  frameborder="0"
></iframe>

5. Identify Logged-In Visitors

If your site has logged-in users, generate an HMAC on your server and pass the visitor data to the widget.

Server-side Node example:

const crypto = require("crypto");

const secret = process.env.SUPPORTGPT_VERIFICATION_SECRET;
const userId = currentUser.id;
const hash = crypto.createHmac("sha256", secret).update(userId).digest("hex");

Browser-side example after the widget is initialized:

window.supportgpt.identify({
  userId: "user-123",
  userHash: hashFromYourServer,
  user_metadata: {
    email: "john@example.com",
    name: "John Doe"
  }
});

Identified visitor fields are used for conversation tracking and for Human Handoff rules that require visitor data.

6. Test The Install

After installing:

Open the site in a private browser session.
Confirm the bubble appears in the configured position.
Start a chat and confirm it appears in Activity and Analytics.
If handoff is enabled, test the "Talk to Human" button and Live Inbox flow.
If using identify(), confirm the visitor name or email appears in the inbox details.

Do not expose the identity verification secret in client-side JavaScript. Generate userHash on your server.