Skip to main content

​
Installation

npm install agent-embed-widget
The widget requires React 18+ or React 19+ as a peer dependency. If your project doesn’t use React, use the UMD / CDN approach below.

​
Quick Start

​
ES Module

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

const widget = embedWidget({
  url: 'https://console.thesys.dev/app/your-slug',
  theme: 'dark',
});
That’s it — a floating chat button appears in the bottom-right corner. Click it to open the agent.

​
CommonJS

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

const widget = embedWidget({
  url: 'https://console.thesys.dev/app/your-slug',
  theme: 'dark',
});

​
UMD / CDN

If you’re not using a bundler, load the widget from a CDN: 
<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({
    url: 'https://console.thesys.dev/app/your-slug',
    theme: 'dark',
  });
</script>

​
Options

OptionTypeDefaultDescription
urlstring—Required. The published agent URL
type'tray' | 'full-screen' | 'chatbar''tray'Widget layout. See Widget Types
theme'dark' | 'light''dark'Color theme
hideLoginbooleanfalseHide the Thesys login UI inside the agent
identityTokenstring—Signed HS256 JWT for BYOI user identity
getIdentityToken() => Promise<string>—Callback for automatic token refresh on expiry
preloadbooleanfalseLoad the agent iframe in the background immediately
optionsTrayOptions | FullScreenOptions | ChatbarOptions—Type-specific options. See Customization

​
Widget Instance

embedWidget() returns a WidgetInstance with methods for programmatic control: 
const widget = embedWidget({ url: '...', theme: 'dark' });

widget.open();                                    // Show the widget
widget.close();                                   // Hide the widget
widget.sendMessage('Hello!');                     // Send a message
widget.sendMessage('Start over', { newThread: true }); // New thread
widget.setInput('Draft for the user to review');  // Prefill input
widget.preload();                                 // Start loading early
widget.destroy();                                 // Remove from DOM
See Programmatic Control for detailed usage and examples.

​
Direct iframe (Alternative)

If you prefer not to use the npm package, embed the agent directly with an iframe: 
<iframe
  src="https://console.thesys.dev/app/your-slug"
  style="width: 100%; height: 600px; border: none;"
></iframe>
The embed widget is recommended over a raw iframe because it handles widget chrome, responsive layout, programmatic control, and automatic identity token refresh out of the box.

​
Next Steps