@wysdym/agent

Official Wysdym Chat Widget for React applications. Embed an AI-powered voice and chat assistant into your website with just a few lines of code.

Installation

npm install @wysdym/agent

Peer Dependencies: React ≥18 and React-DOM ≥18 are required.

⚠️ CSS Import Required

You must import the widget styles for the widget to render correctly:

import '@wysdym/agent/style.css';

Without this import, the widget will appear unstyled or broken. This is the most common setup issue.

Quick Start

import { WysdymWidget } from '@wysdym/agent';
import '@wysdym/agent/style.css';  // Required!

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

That's it! The widget will appear as a floating button in the bottom-right corner of your page.

Display Modes

Floating Mode (Default)

A floating button appears in the corner of the screen. When clicked, it expands into a chat interface.

<WysdymWidget
  agentId="your-agent-id"
  mode="floating"
  position="bottom-right"
/>

Inline Mode

The widget embeds directly into your page layout, useful for dedicated support pages or embedded experiences.

<WysdymWidget
  agentId="your-agent-id"
  mode="inline"
/>

Props Reference

WysdymWidget (Recommended)

The primary component for most use cases.

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | agentId | string | ✓ | — | Your Wysdym agent ID | | mode | 'floating' \| 'inline' | | 'floating' | Display mode | | position | 'bottom-right' \| 'bottom-left' | | 'bottom-right' | Floating button position | | theme | 'light' \| 'dark' | | — | Color theme | | primaryColor | string | | — | Primary brand color (CSS value) | | expandable | boolean | | — | Allow expand/collapse by user | | deferInit | boolean | | — | Defer initialization until triggered |

ChatWidget (Advanced)

A lower-level component with full configuration options. Use when you need fine-grained control over the widget's appearance and behavior.

import { ChatWidget } from '@wysdym/agent';
import '@wysdym/agent/style.css';

<ChatWidget
  agentId="your-agent-id"
  primaryColor="#BA6296"
  mode="floating"
  onExpandChange={(expanded) => console.log('Widget expanded:', expanded)}
/>

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | agentId | string | ✓ | — | Your Wysdym agent ID | | mode | 'floating' \| 'inline' | | 'floating' | Display mode | | primaryColor | string | | '#BA6296' | Primary brand color | | secondaryColor | string | | '#A0527A' | Secondary brand color | | isExpanded | boolean | | false | Start widget in expanded state | | onExpandChange | (expanded: boolean) => void | | — | Callback when expanded state changes | | backendUrl | string | | production URL | Custom backend URL (self-hosted) | | widgetTriggerText | string | | 'Need help?' | Text shown on trigger button | | widgetTriggerButtonText | string | | 'Start a call' | Button text for trigger | | widgetTriggerButtonIcon | string | | 'Phone' | Icon name for trigger button | | emailCollectionButtonText | string | | 'Submit' | Email form submit button text | | emailCollectionButtonIcon | string | | 'ArrowRight' | Email form button icon | | greetingTooltipEnabled | boolean | | true | Show proactive greeting tooltip | | greetingTooltipText | string | | — | Custom tooltip text | | initialAgentName | string | | — | Agent name (before config loads) | | initialAgentFirstMessage | string | | — | First message (before config loads) |

Styling

CSS Import Options

// Recommended: Clean import path
import '@wysdym/agent/style.css';

// Alternative: Direct path
import '@wysdym/agent/dist/index.css';

Style Isolation

Widget styles are scoped to .wysdym-widget-container and will not affect your application's global styles:

• Widget styles only apply inside the widget container
• Your existing Tailwind or custom CSS classes are unaffected
• No CSS reset or preflight styles leak to your host application

Custom Branding

Use primaryColor and secondaryColor props to match your brand:

<WysdymWidget
  agentId="your-agent-id"
  primaryColor="#6366F1"  // Indigo
/>

Non-React / CDN Usage

For websites not using React, embed the widget via a script tag:

<script
  src="https://storage.googleapis.com/wysdym-widget-cdn-production/widget-loader.js"
  data-auto-load="true"
  data-agent-id="your-agent-id"
  data-mode="floating"
  data-position="bottom-right"
  async
></script>

Generating Embed Code Programmatically

import { getEmbedCode } from '@wysdym/agent';

const embedCode = getEmbedCode('your-agent-id', {
  mode: 'floating',
  position: 'bottom-right'
});

console.log(embedCode);
// <script src="..."></script>

TypeScript Support

Full TypeScript definitions are included. Import types as needed:

import type {
  WysdymWidgetProps,
  ChatWidgetProps,
  GetEmbedCodeOptions,
  EmbedMode,
  FloatingPosition,
  DisplayMode,
} from '@wysdym/agent';

Changelog

See the GitHub Releases page for version history and release notes.

Support

• Documentation: docs.wysdym.ai
• Issues: GitHub Issues
• Email: [email protected]

License

MIT © Wysdym