PlumoAI Agent Widget for Vanilla JavaScript

A vanilla JavaScript chatbot widget component library that embeds PlumoAI agents in any website. Works with WordPress, plain HTML, React, Vue, Angular, or any JavaScript framework - no dependencies required!

Features

• 🎯 Zero Dependencies - Pure vanilla JavaScript, works everywhere
• 📱 Resizable Widget - Floating widget with resize capability
• 📦 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
• 🌐 WordPress Compatible - Works seamlessly in WordPress themes and plugins

Installation

Via npm

npm install @plumoai/agent-widget-js

Via CDN (Coming Soon)

<script src="https://cdn.jsdelivr.net/npm/@plumoai/agent-widget-js/dist/index.umd.js"></script>

Usage

Basic Example (Floating Widget)

ES Modules

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

const widget = new PlumoAIAgentWidget({
  agentId: 'your-agent-id',
  position: 'bottom-right'
});

Browser (Global)

<script src="https://cdn.jsdelivr.net/npm/@plumoai/agent-widget-js/dist/index.umd.js"></script>
<script>
  const widget = new PlumoAIAgentWidget({
    agentId: 'your-agent-id',
    position: 'bottom-right'
  });
</script>

WordPress Integration

Method 1: Add to Theme's functions.php

function add_plumoai_widget() {
    ?>
    <script src="https://cdn.jsdelivr.net/npm/@plumoai/agent-widget-js/dist/index.umd.js"></script>
    <script>
        document.addEventListener('DOMContentLoaded', function() {
            new PlumoAIAgentWidget({
                agentId: 'your-agent-id',
                position: 'bottom-right',
                initialWidth: 420,
                initialHeight: 484
            });
        });
    </script>
    <?php
}
add_action('wp_footer', 'add_plumoai_widget');

Method 2: WordPress Plugin

Create a simple plugin:

<?php
/**
 * Plugin Name: PlumoAI Agent Widget
 * Description: Add PlumoAI chatbot widget to your WordPress site
 * Version: 1.0.0
 */

function plumoai_widget_enqueue_scripts() {
    wp_enqueue_script(
        'plumoai-widget',
        'https://cdn.jsdelivr.net/npm/@plumoai/agent-widget-js/dist/index.umd.js',
        array(),
        '1.0.0',
        true
    );
}
add_action('wp_enqueue_scripts', 'plumoai_widget_enqueue_scripts');

function plumoai_widget_footer_script() {
    ?>
    <script>
        document.addEventListener('DOMContentLoaded', function() {
            new PlumoAIAgentWidget({
                agentId: '<?php echo get_option('plumoai_agent_id', ''); ?>',
                position: 'bottom-right'
            });
        });
    </script>
    <?php
}
add_action('wp_footer', 'plumoai_widget_footer_script');

Inline Widget

import { PlumoAIAgentWidgetInline } from '@plumoai/agent-widget-js';

// Place in a specific container
const inlineWidget = new PlumoAIAgentWidgetInline({
  agentId: 'your-agent-id',
  container: '#my-container', // CSS selector
  width: '100%',
  height: '600px'
});

// Or let it create its own container
const inlineWidget2 = new PlumoAIAgentWidgetInline({
  agentId: 'your-agent-id',
  width: '100%',
  height: '600px'
});

With User Identity Key

const widget = new PlumoAIAgentWidget({
  agentId: 'your-agent-id',
  userIdentityKey: 'user-specific-key',
  position: 'bottom-right'
});

Custom Size Configuration

const widget = new PlumoAIAgentWidget({
  agentId: 'your-agent-id',
  position: 'bottom-right',
  initialWidth: 400,
  initialHeight: 500,
  minWidth: 300,
  minHeight: 400,
  maxWidth: 800,
  maxHeight: 900
});

Start Maximized

const widget = new PlumoAIAgentWidget({
  agentId: 'your-agent-id',
  initialMaximized: true
});

API Reference

PlumoAIAgentWidget

Constructor Options

| Option | 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 |

Methods

• destroy() - Removes the widget from the DOM and cleans up event listeners

PlumoAIAgentWidgetInline

Constructor Options

| Option | 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 | | container | string \| HTMLElement | - | Container element or CSS selector where the widget should be mounted. If not provided, creates its own container |

Methods

• destroy() - Removes the widget from the DOM

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.

PostMessage Events

The widget listens for postMessage events from the iframe:

Close

window.parent.postMessage({ type: 'close' }, '*');
// or
window.parent.postMessage('close', '*');

Maximize

window.parent.postMessage({ type: 'maximize' }, '*');
// or
window.parent.postMessage('maximize', '*');

Restore/Minimize

window.parent.postMessage({ type: 'restore' }, '*');
// or
window.parent.postMessage('restore', '*');

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

• Modern browser with ES6+ support
• No framework dependencies required!

License

MIT

Support

For issues and questions, please visit GitHub Issues