Agent Embed Widget

A JavaScript library for embedding c1 agent widgets into your application. Works with vanilla JavaScript, TypeScript, and any framework.

Installation

npm install agent-embed-widget
# or
yarn add agent-embed-widget
# or
pnpm add agent-embed-widget

Usage

ES Module (Named Import)

import { embedWidget } from "agent-embed-widget";
import "agent-embed-widget/dist/agent-embed-widget.css";

const widget = embedWidget({
  type: "tray", // or 'full-screen'
  url: "https://console.thesys.dev/your-published-agent-url.com",
  theme: "dark", // or 'light'
});

// Control the widget programmatically
widget.open();
widget.close();
widget.destroy();
widget.preload();
widget.sendMessage("Hello!");
widget.sendMessage("Start fresh", { newThread: true });
widget.setInput("Draft a message for the user to review");

CommonJS

const { embedWidget } = require("agent-embed-widget");
require("agent-embed-widget/dist/agent-embed-widget.css");

const widget = embedWidget({
  type: "tray",
  url: "https://console.thesys.dev/app/your-app-id",
  theme: "dark",
});

UMD (Browser)

<link
  rel="stylesheet"
  href="node_modules/agent-embed-widget/dist/agent-embed-widget.css"
/>
<script src="node_modules/agent-embed-widget/dist/agent-embed-widget.umd.js"></script>

<script>
  const { embedWidget } = window.AgentEmbedWidget;

  const widget = embedWidget({
    type: "tray",
    url: "https://console.thesys.dev/app/your-app-id",
    theme: "dark",
  });
</script>

CDN Usage

<link
  rel="stylesheet"
  href="https://unpkg.com/agent-embed-widget/dist/agent-embed-widget.css"
/>
<script src="https://unpkg.com/agent-embed-widget/dist/agent-embed-widget.umd.js"></script>

<script>
  const { embedWidget } = window.AgentEmbedWidget;

  const widget = embedWidget({
    type: "full-screen",
    url: "https://console.thesys.dev/app/your-app-id",
    theme: "light",
  });
</script>

API Reference

embedWidget(options)

Creates and embeds a widget into your application.

Options

• type (optional): 'tray' | 'full-screen' | 'chatbar' - Widget display type. Default: 'tray'
  • 'tray': A compact widget that appears in the bottom-right corner
  • 'full-screen': A widget that covers the entire screen when opened
  • 'chatbar': An inline chat input bar
• url (required): string - The URL of the playground to embed
• theme (optional): 'dark' | 'light' - Widget theme. Default: 'dark'
• hideLogin (optional): boolean - If true, hides the login UI in the embedded agent. Default: false
• identityToken (optional): string - A signed HS256 JWT containing externalUserId for user identity verification (BYOI). See BYOI documentation for details.
• getIdentityToken (optional): () => Promise<string> - Async callback invoked when the current identity token expires. Should return a fresh signed JWT. When provided, the widget automatically requests a new token and retries seamlessly instead of showing an error.
• preload (optional): boolean - If true, the chat iframe loads in the background immediately, so it's ready instantly when opened. Default: false

Returns

A WidgetInstance object with the following methods:

• open(): Opens/shows the widget
• close(): Closes/hides the widget
• destroy(): Removes the widget from the DOM and cleans up resources
• sendMessage(message, options?): Sends a user message to the chat agent programmatically
• setInput(message, options?): Prefills the chat input with a message without sending it, allowing the user to review and edit before submitting
• preload(): Starts loading the chat iframe in the background. Useful if you didn't set preload: true in options but want to trigger it later (e.g., after user scrolls to a section)

Example

const widget = embedWidget({
  type: "tray",
  url: "https://console.thesys.dev/app/your-app-id",
  theme: "dark",
});

// Open the widget after 2 seconds
setTimeout(() => widget.open(), 2000);

// Close it after 5 seconds
setTimeout(() => widget.close(), 5000);

// Clean up when done
// widget.destroy();

widget.sendMessage(message, options?)

Sends a user message to the embedded chat agent. If the widget is closed, it will be opened automatically.

Parameters

• message (required): string - The message text to send
• options (optional): SendMessageOptions
  • newThread (optional): boolean - If true, starts a new conversation thread before sending. Default: false

Example: Trigger messages from buttons

<button id="ask-pricing">Ask about pricing</button>
<button id="new-chat">Start fresh chat</button>

<script type="module">
  import { embedWidget } from "agent-embed-widget";

  const widget = embedWidget({
    type: "tray",
    url: "https://console.thesys.dev/app/your-app-id",
    theme: "light",
  });

  document.getElementById("ask-pricing").addEventListener("click", () => {
    widget.sendMessage("Tell me about pricing");
  });

  document.getElementById("new-chat").addEventListener("click", () => {
    widget.sendMessage("I need help with my order", { newThread: true });
  });
</script>

widget.setInput(message, options?)

Prefills the chat input bar with a message without sending it. The widget opens (if closed) and the user can review, edit, and then submit the message themselves.

Parameters

• message (required): string - The message text to prefill
• options (optional): SetInputOptions
  • newThread (optional): boolean - If true, starts a new conversation thread before prefilling. Default: false

Example: Suggest a message for the user to review

<button id="suggest-msg">Suggest a question</button>

<script type="module">
  import { embedWidget } from "agent-embed-widget";

  const widget = embedWidget({
    type: "tray",
    url: "https://console.thesys.dev/app/your-app-id",
    theme: "light",
  });

  document.getElementById("suggest-msg").addEventListener("click", () => {
    widget.setInput("Can you help me understand my recent invoice?");
  });
</script>

widget.preload()

Starts loading the chat iframe in the background so it's ready instantly when the user opens the widget or when sendMessage() is called.

Example: Preload on page load via option

const widget = embedWidget({
  type: "tray",
  url: "https://console.thesys.dev/app/your-app-id",
  theme: "light",
  preload: true, // iframe starts loading immediately
});

Example: Preload manually after a user action

const widget = embedWidget({
  type: "tray",
  url: "https://console.thesys.dev/app/your-app-id",
  theme: "light",
});

// Preload when user scrolls near the bottom of the page
window.addEventListener(
  "scroll",
  () => {
    if (window.scrollY > document.body.scrollHeight - 1000) {
      widget.preload();
    }
  },
  { once: true }
);

User Identity (BYOI)

Use identityToken and getIdentityToken to give each user isolated conversation history.

import { embedWidget } from "agent-embed-widget";
import "agent-embed-widget/dist/agent-embed-widget.css";

const widget = embedWidget({
  type: "tray",
  url: "https://your-published-agent-url",
  theme: "dark",
  identityToken: currentToken, // initial signed JWT
  getIdentityToken: async () => {
    // Called automatically when the token expires
    const res = await fetch("/api/identity-token");
    const { token } = await res.json();
    return token;
  },
});

For full setup instructions including secret generation and JWT signing, see the BYOI documentation.

TypeScript Support

This package includes TypeScript declarations out of the box. No additional setup required!

import { embedWidget } from "agent-embed-widget";
import type {
  EmbedWidgetOptions,
  WidgetInstance,
  SendMessageOptions,
  SetInputOptions,
} from "agent-embed-widget";

const widget: WidgetInstance = embedWidget({
  type: "tray",
  url: "https://console.thesys.dev/app/your-app-id",
  theme: "dark",
  preload: true,
});

widget.sendMessage("Hello!");
widget.sendMessage("Start over", { newThread: true });
widget.setInput("Review this before sending");

Development

Setup

pnpm install

Development Server

pnpm run dev

Build

pnpm run build

This will generate:

• dist/agent-embed-widget.es.js - ES module build
• dist/agent-embed-widget.umd.js - UMD build for browser
• dist/agent-embed-widget.css - Styles
• dist/index.d.ts - TypeScript declarations

Lint

pnpm run lint

Publishing

Before publishing to npm, make sure to:

1. Update the version in package.json
2. Update the repository URL in package.json
3. Update the author field in package.json
4. Build the package: pnpm run build
5. Publish: npm publish

License

MIT

Peer Dependencies

• React 18.0.0+ or 19.0.0+
• React DOM 18.0.0+ or 19.0.0+