> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thesys.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Install the embed widget and add a Thesys agent to your site in under five minutes.

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install agent-embed-widget
  ```

  ```bash yarn theme={null}
  yarn add agent-embed-widget
  ```

  ```bash pnpm theme={null}
  pnpm add agent-embed-widget
  ```
</CodeGroup>

<Info>
  The widget requires **React 18+** or **React 19+** as a peer dependency. If your project doesn't use React, use the [UMD / CDN](#umd--cdn) approach below.
</Info>

***

## Quick Start

### ES Module

```javascript theme={null}
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

```javascript theme={null}
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:

```html theme={null}
<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

| Option             | Type                                                     | Default  | Description                                                                           |
| ------------------ | -------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------- |
| `url`              | `string`                                                 | —        | **Required.** The published agent URL                                                 |
| `type`             | `'tray'` \| `'full-screen'` \| `'chatbar'`               | `'tray'` | Widget layout. See [Widget Types](/agent-builder/embed-widget/widget-types)           |
| `theme`            | `'dark'` \| `'light'`                                    | `'dark'` | Color theme                                                                           |
| `hideLogin`        | `boolean`                                                | `false`  | Hide the Thesys login UI inside the agent                                             |
| `identityToken`    | `string`                                                 | —        | Signed HS256 JWT for [BYOI](/agent-builder/byoi) user identity                        |
| `getIdentityToken` | `() => Promise<string>`                                  | —        | Callback for automatic token refresh on expiry                                        |
| `preload`          | `boolean`                                                | `false`  | Load the agent iframe in the background immediately                                   |
| `options`          | `TrayOptions` \| `FullScreenOptions` \| `ChatbarOptions` | —        | Type-specific options. See [Customization](/agent-builder/embed-widget/customization) |

***

## Widget Instance

`embedWidget()` returns a `WidgetInstance` with methods for programmatic control:

```javascript theme={null}
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](/agent-builder/embed-widget/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:

```html theme={null}
<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

* [**Widget Types**](/agent-builder/embed-widget/widget-types) — Choose the right layout for your use case
* [**Customization**](/agent-builder/embed-widget/customization) — Theme the chatbar and configure options
* [**User Identity (BYOI)**](/agent-builder/byoi) — Identify users and isolate their conversations