PlumoAI Agent Widget for Vue

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

Features

• 🎯 Easy Integration - Simple Vue 3 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-vue

Usage

Basic Example (Floating Widget)

<template>
  <PlumoAIAgentWidget 
    agent-id="your-agent-id"
    position="bottom-right"
  />
</template>

<script setup lang="ts">
import { PlumoAIAgentWidget } from 'plumoai-agent-widget-vue';
</script>

With User Identity Key

<template>
  <PlumoAIAgentWidget 
    agent-id="your-agent-id"
    user-identity-key="user-specific-key"
    position="bottom-right"
  />
</template>

<script setup lang="ts">
import { PlumoAIAgentWidget } from 'plumoai-agent-widget-vue';
</script>

Custom Size Configuration

<template>
  <PlumoAIAgentWidget 
    agent-id="your-agent-id"
    position="bottom-right"
    :initial-width="400"
    :initial-height="500"
    :min-width="300"
    :min-height="400"
    :max-width="800"
    :max-height="900"
  />
</template>

<script setup lang="ts">
import { PlumoAIAgentWidget } from 'plumoai-agent-widget-vue';
</script>

Start Maximized

<template>
  <PlumoAIAgentWidget 
    agent-id="your-agent-id"
    :initial-maximized="true"
  />
</template>

<script setup lang="ts">
import { PlumoAIAgentWidget } from 'plumoai-agent-widget-vue';
</script>

Inline Widget (Simple Container)

<template>
  <div style="width: 100%; padding: 20px;">
    <PlumoAIAgentWidgetInline 
      agent-id="your-agent-id"
      width="100%"
      height="600px"
    />
  </div>
</template>

<script setup lang="ts">
import { PlumoAIAgentWidgetInline } from 'plumoai-agent-widget-vue';
</script>

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)

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', '*');

Requirements

• Vue 3.0.0 or higher

License

MIT

Support

For issues and questions, please visit GitHub Issues