npm package: @plumoai/agent-widget
Description: PlumoAI Agent Widget - A resizable chatbot widget component that embeds PlumoAI agents in your React applications
Author: PlumoAI
Latest version: 1.0.7

# PlumoAI Agent Widget

A chatbot widget component library for React that embeds PlumoAI agents in your applications. Includes both a floating resizable widget and a simple inline widget component.

## Features

- 🎯 **Easy Integration** - Simple React components, easy to integrate
- 📱 **Resizable Widget** - Floating widget with resize capability from all directions (8 handles)
- 📦 **Inline Widget** - Simple inline component for embedding in page content
- 🍪 **Auto Identity Management** - Automatically generates and stores user identity keys in cookies
- 🎨 **Customizable** - Configurable size, position, and constraints
- 🔒 **TypeScript** - Full TypeScript support with type definitions
- ⚡ **Lightweight** - Small bundle size, optimized for performance
- 🔄 **Maximize/Restore** - Floating widget can maximize to take 25% width, pushing content to 75%
- 📨 **PostMessage Support** - Listen for close/maximize/restore events from iframe

## Installation

```bash
npm install @plumoai/agent-widget
```

## Usage

### Basic Example

```tsx
import { PlumoAIAgentWidget } from "@plumoai/agent-widget";

function App() {
  return (
    <PlumoAIAgentWidget 
      agentId="your-agent-id"
      position="bottom-right"
    />
  );
}
```

### With User Identity Key

```tsx
import { PlumoAIAgentWidget } from "@plumoai/agent-widget";

function App() {
  return (
    <PlumoAIAgentWidget 
      agentId="your-agent-id"
      userIdentityKey="user-specific-key"
      position="bottom-right"
    />
  );
}
```

### Custom Size Configuration

```tsx
import { PlumoAIAgentWidget } from "@plumoai/agent-widget";

function App() {
  return (
    <PlumoAIAgentWidget 
      agentId="your-agent-id"
      position="bottom-right"
      initialWidth={400}
      initialHeight={500}
      minWidth={300}
      minHeight={400}
      maxWidth={800}
      maxHeight={900}
    />
  );
}
```

### Start Maximized

```tsx
import { PlumoAIAgentWidget } from "@plumoai/agent-widget";

function App() {
  return (
    <PlumoAIAgentWidget 
      agentId="your-agent-id"
      initialMaximized={true}
    />
  );
}
```

### Inline Widget (Simple Container)

For a simpler inline widget that can be placed in any container:

```tsx
import { PlumoAIAgentWidgetInline } from "@plumoai/agent-widget";

function App() {
  return (
    <div style={{ width: "100%", padding: "20px" }}>
      <PlumoAIAgentWidgetInline 
        agentId="your-agent-id"
        width="100%"
        height="600px"
      />
    </div>
  );
}
```

The inline widget is perfect for embedding directly in your page content without floating or resizing functionality.

## Components

### PlumoAIAgentWidget

The main floating, resizable widget component.

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `agentId` | `string` | - | **Required.** The PlumoAI agent ID to load in the iframe |
| `userIdentityKey` | `string` | - | Optional. User identity key. If not provided, a GUID will be auto-generated and stored in cookies |
| `position` | `"bottom-right" \| "bottom-left"` | `"bottom-right"` | Position of the floating button |
| `initialWidth` | `number` | `320` | Initial width of the chat window (in pixels) |
| `initialHeight` | `number` | `384` | Initial height of the chat window (in pixels) |
| `minWidth` | `number` | `280` | Minimum width of the chat window (in pixels) |
| `minHeight` | `number` | `300` | Minimum height of the chat window (in pixels) |
| `maxWidth` | `number` | `600` | Maximum width of the chat window (in pixels) |
| `maxHeight` | `number` | `800` | Maximum height of the chat window (in pixels) |
| `initialMaximized` | `boolean` | `false` | Whether the widget should start maximized (slides from right, full height, 1/4 width) |
| `className` | `string` | `""` | Additional CSS classes for the widget container |

### PlumoAIAgentWidgetInline

A simple inline widget component that can be placed in any container.

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `agentId` | `string` | - | **Required.** The PlumoAI agent ID to load in the iframe |
| `userIdentityKey` | `string` | - | Optional. User identity key. If not provided, a GUID will be auto-generated and stored in cookies |
| `width` | `string \| number` | `"100%"` | Width of the widget |
| `height` | `string \| number` | `"600px"` | Height of the widget |
| `className` | `string` | `""` | Additional CSS classes for the widget container |

## Identity Key Management

The widget automatically manages user identity keys:

1. **If `userIdentityKey` is provided**: Uses the provided value
2. **If not provided**: Checks browser cookie `plumoai_user_identity_key`
3. **If no cookie exists**: Generates a new GUID and stores it in the cookie (expires in 365 days)

This ensures users maintain the same identity across sessions without requiring manual key management.

## Resizing (PlumoAIAgentWidget only)

The floating chat window can be resized from all directions:
- **4 Corner handles**: Top-left, top-right, bottom-left, bottom-right
- **4 Edge handles**: Top, bottom, left, right

Simply hover over any edge or corner and drag to resize. The window respects the configured min/max constraints.

**Note**: The inline widget (`PlumoAIAgentWidgetInline`) does not support resizing - it uses fixed width and height as specified in props.

## Iframe URL

The widget loads the PlumoAI agent in an iframe with the following URL pattern:

```
https://aiagent.plumoai.com/{agentId}?identitykey={identityKey}
```

Where:
- `{agentId}` is the agent ID you provide
- `{identityKey}` is the user identity key (from prop, cookie, or auto-generated)

## Requirements

- React 18.0.0 or higher
- React DOM 18.0.0 or higher

## License

MIT

## Support

For issues and questions, please visit [GitHub Issues](https://github.com/plumoai/agent-widget/issues)