Embed API Reference

SupportGPT currently uses a hosted browser script, not an npm SDK.

Load:

<script src="https://supportgpt.app/embed.min.js" async></script>

Then initialize the widget:

window.supportgpt.init({
  chatbotId: "YOUR_AGENT_ID"
});

Methods

`init(options)`

Initializes the widget.

window.supportgpt.init({
  chatbotId: "YOUR_AGENT_ID",
  apiBaseUrl: "https://supportgpt.app"
});

Options:

Name	Required	Description
`chatbotId`	Yes	The agent ID from Deploy -> Embed.
`apiBaseUrl`	No	Defaults to `https://supportgpt.app`.

`identify(data)`

Associates the current browser visitor with a logged-in user.

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

Fields:

Name	Required	Description
`userId`	Yes	Stable unique ID for the logged-in user.
`userHash`	Recommended	HMAC-SHA256 of `userId` generated with the agent secret.
`user_metadata.email`	No	Email shown in inbox details.
`user_metadata.name`	No	Name shown in inbox details.
`user_metadata.*`	No	Custom metadata for your own tracking.

`open()` And `close()`

Controls the widget window.

window.supportgpt.open();
window.supportgpt.close();

`show()` And `hide()`

Shows or hides the bubble button.

window.supportgpt.show();
window.supportgpt.hide();

`setInitialMessages(messages)`

Sends custom initial messages to the iframe when it is loaded.

window.supportgpt.setInitialMessages([
  { role: "agent", text: "Welcome back. Need help with billing?" }
]);

Each message should include:

role: A string such as agent, user, or team.
text: Message text.

`addEventListener(eventName, callback)`

Registers a browser-side widget listener.

window.supportgpt.addEventListener("initialized", (event) => {
  console.log("SupportGPT ready", event);
});

Common events emitted by the script include:

initialized.
identify.
toolsRegistered.
schemasRegistered.
initialMessagesSet.
configUpdated.

`removeEventListener(eventName, callback)`

Removes a listener registered with addEventListener.

window.supportgpt.removeEventListener("initialized", onInitialized);

`updateConfig(updates)`

Updates local widget config at runtime.

window.supportgpt.updateConfig({
  defaultWidth: 420,
  defaultHeight: 640
});

Queued Calls

If your page needs to call SupportGPT before the script is loaded, create a queue first:

<script>
  window.supportgpt = window.supportgpt || [];
  window.supportgpt.q = window.supportgpt.q || [];
  window.supportgpt.q.push(["init", { chatbotId: "YOUR_AGENT_ID" }]);
</script>
<script src="https://supportgpt.app/embed.min.js" async></script>

Visitor Identity Storage

The script stores anonymous and unread-state identifiers in browser cookies and local storage so visitors can continue conversations and see unread counts across reloads.

Do not call dashboard /api/* routes directly from production integrations unless you own that deployment and accept that those routes may change. The stable current integration path is the hosted widget or iframe.