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

npm install @plumoai/agent-widget

Usage

Basic Example

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

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

With User Identity Key

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

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

Custom Size Configuration

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

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:

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