@zynextechai/chat-widget

An embeddable AI chat widget for websites that provides intelligent conversational AI capabilities with support for multiple authentication providers and customizable branding.

Features

• 🤖 AI-Powered Chat - Intelligent responses using your AI endpoints
• 🔐 Flexible Authentication - Supports Clerk, custom auth, or guest mode
• 🎨 Customizable Branding - Logo, colors, and styling options
• 📱 Responsive Design - Works on desktop and mobile
• ⚡ Framework Independent - Pure React, no Next.js dependencies
• 🔧 TypeScript Support - Full type definitions included

Installation

npm install @zynextechai/chat-widget ai

Note: The ai package is required as a peer dependency for chat functionality. Clerk authentication is bundled within the widget.

Quick Start

Basic Usage (Guest Mode)

import { ExpandableChatWidgetWrapper } from '@zynextechai/chat-widget';
import '@zynextechai/chat-widget/dist/styles.css';

function App() {
  return (
    <ExpandableChatWidgetWrapper 
      organizationId="your-org-id"
      publicScope={true}
      endpoint="https://your-api.com/api/chat/retrieval_agents"
      logoUrl="/your-logo.png"
      brandName="Your Company AI"
    />
  );
}

With Authentication (Default)

import { ExpandableChatWidgetWrapper } from '@zynextechai/chat-widget';
import '@zynextechai/chat-widget/dist/styles.css';

function App() {
  return (
    <ExpandableChatWidgetWrapper 
        organizationId="your-org-id"
      endpoint="https://your-api.com/api/chat/retrieval_agents"
      logoUrl="/your-logo.png"
      brandName="Your Company AI"
      />
  );
}

Note: Authentication is managed by ZynexTech. Users will be prompted to sign in/up through our secure authentication system.

API Reference

ExpandableChatWidgetWrapper Props

| Prop | Type | Required | Description | |------|------|----------|-------------| | organizationId | string | ❌ | Your organization identifier | | endpoint | string | ❌ | Your AI chat API endpoint (defaults to ZynexTech endpoint) | | publicScope | boolean | ❌ | Allow guest users (default: false) | | allowAllAccess | boolean | ❌ | Allow unrestricted access (default: false) | | logoUrl | string | ❌ | URL to your logo image | | logoAlt | string | ❌ | Alt text for logo | | brandName | string | ❌ | Your brand/company name | | placeholder | string | ❌ | Chat input placeholder text | | className | string | ❌ | Additional CSS classes |

ExpandableChatWidget Props

| Prop | Type | Required | Description | |------|------|----------|-------------| | organizationId | string | ✅ | Your organization identifier | | endpoint | string | ✅ | Your AI chat API endpoint | | userId | string | ❌ | Current user ID | | logoUrl | string | ❌ | URL to your logo image | | logoAlt | string | ❌ | Alt text for logo | | brandName | string | ❌ | Your brand/company name |

Styling

The widget comes with default Tailwind CSS styles. Import the CSS file:

import '@zynextechai/chat-widget/dist/styles.css';

Custom Styling

You can override the default styles by targeting the widget's CSS classes:

/* Customize the widget button */
.chat-widget-button {
  background-color: your-brand-color !important;
}

/* Customize the chat window */
.chat-widget-window {
  border-radius: 12px !important;
}

Authentication

Authentication is automatically handled by ZynexTech's secure system. Users will be prompted to sign in or create an account when they first interact with the widget.

Guest Mode (Optional)

If you want to allow anonymous users to chat without authentication:

<ExpandableChatWidgetWrapper 
  organizationId="your-org-id"
  publicScope={true}
  endpoint="https://your-api.com/api/chat/retrieval_agents"
/>

Authenticated Mode (Default)

By default, users must authenticate to use the chat:

<ExpandableChatWidgetWrapper 
  organizationId="your-org-id"
  endpoint="https://your-api.com/api/chat/retrieval_agents"
/>

API Endpoint Requirements

Your chat endpoint should accept POST requests with the following format:

// Request
{
  messages: Array<{
    id: string;
    content: string;
    role: 'user' | 'assistant';
  }>;
  organizationId: string;
  userId?: string;
}

// Response (streaming)
// Should return a streaming response compatible with the AI SDK

TypeScript Support

The package includes full TypeScript definitions. Import types as needed:

import type { 
  ExpandableChatWidgetProps,
  ExpandableChatWidgetWrapperProps 
} from '@zynextechai/chat-widget';

Browser Support

• Chrome 60+
• Firefox 60+
• Safari 12+
• Edge 79+

License

MIT

Support

For issues and questions, please visit our GitHub repository.

Styling Props (New!)

The widget now comes with sensible default styles that work out of the box. All styling props are optional and only needed if you want to customize the appearance.

Default Classes Applied

// These are now the default values - no need to specify unless customizing
<ExpandableChatWidget
  organizationId="your-org-id"
  publicScope={true}
  // Default styling (automatically applied):
  // widgetClassName='h-[600px] w-[500px]'
  // buttonsClassName='absolute top-12 text-[10px]'
  // inputClassName='min-h-[80px] mx-auto w-[98%]'
  // dropdownClassName='pt-2 space-x-2'
/>

widgetClassName

| Prop | Type | Default | Description | |------|------|---------|-------------| | widgetClassName | string | 'h-[600px] w-[500px]' | Custom CSS class for the expanded chat widget container (only applies when expanded, not minimized) |

zIndex

| Prop | Type | Default | Description | |------|------|---------|-------------| | zIndex | number | 9999 | Z-index for the widget positioning |

bubbleClassName

| Prop | Type | Default | Description | |------|------|---------|-------------| | bubbleClassName | string | - | Custom CSS class for the chat bubble specifically |

inputClassName

| Prop | Type | Default | Description | |------|------|---------|-------------| | inputClassName | string | 'min-h-[80px] mx-auto w-[98%]' | Custom CSS class for the input/textarea |

buttonsClassName

| Prop | Type | Default | Description | |------|------|---------|-------------| | buttonsClassName | string | 'absolute top-12 text-[10px]' | Custom CSS class for the buttons container (suggestions toggle, intermediate steps toggle, and send button) |

dropdownClassName

| Prop | Type | Default | Description | |------|------|---------|-------------| | dropdownClassName | string | 'pt-2 space-x-2' | Custom CSS class for the dropdown container (Knowledge Sources and MCP Tools dropdowns) |

direction

| Prop | Type | Default | Description | |------|------|---------|-------------| | direction | 'up' \| 'down' | 'down' | Direction the widget expands when opened |

dropdownDirection

| Prop | Type | Default | Description | |------|------|---------|-------------| | dropdownDirection | 'top' \| 'bottom' | 'bottom' | Direction dropdowns open (Knowledge Sources and MCP Tools) |

Styling Examples

Custom Colors

<ExpandableChatWidget
  organizationId="your-org-id"
  publicScope={true}
  bubbleClassName="bg-gradient-to-r from-green-500 to-blue-600"
  widgetClassName="border-2 border-green-500"
  inputClassName="border-green-300 focus:border-green-500"
/>

High Z-Index for Overlays

<ExpandableChatWidget
  organizationId="your-org-id"
  publicScope={true}
  zIndex={99999}
  className="shadow-2xl"
/>

Custom Input Styling

<ExpandableChatWidget
  organizationId="your-org-id"
  publicScope={true}
  inputClassName="bg-gray-100 border-2 border-blue-400 rounded-xl font-mono text-lg"
/>

Custom Buttons Styling

<ExpandableChatWidget
  organizationId="your-org-id"
  publicScope={true}
  buttonsClassName="bg-blue-50 border border-blue-200 rounded-lg p-2 shadow-sm gap-3"
/>

Advanced Button Positioning

<ExpandableChatWidget
  organizationId="your-org-id"
  publicScope={true}
  // Move buttons to top-right corner with custom spacing
  buttonsClassName="absolute top-2 right-2 flex items-center gap-3 bg-white/90 backdrop-blur-sm rounded-xl p-3 shadow-lg border"
/>

Z-Index Considerations

The widget uses high z-index values to ensure dropdowns appear above other page content:

• Widget container: Uses the zIndex prop (default: 9999)
• Dropdown menus: Fixed at z-index 99999 to appear above the widget

If you encounter dropdown visibility issues, ensure your page elements don't use higher z-index values.

Custom Dropdown Styling

<ExpandableChatWidget
  organizationId="your-org-id"
  publicScope={true}
  dropdownClassName="flex-1 justify-center gap-4 mb-6 bg-gradient-to-r from-blue-50 to-purple-50 p-4 rounded-xl border border-blue-200"
/>

Widget Opening Direction

<ExpandableChatWidget
  organizationId="your-org-id"
  publicScope={true}
  // For bottom-right placement, make widget expand upward
  direction="up"
  // Make dropdowns open upward too
  dropdownDirection="top"
/>

Full Customization

<ExpandableChatWidget
  organizationId="your-org-id"
  publicScope={true}
  // Widget container styling
  widgetClassName="backdrop-blur-md bg-white/90 border-purple-200 shadow-purple-500/20"
  // Chat bubble styling
  bubbleClassName="bg-gradient-to-r from-purple-600 to-pink-600 hover:from-purple-700 hover:to-pink-700"
  // Input field styling
  inputClassName="bg-purple-50 border-purple-300 focus:border-purple-500 placeholder-purple-400"
  // Buttons container styling
  buttonsClassName="bg-white/80 backdrop-blur-sm border border-purple-200 rounded-lg p-2"
  // Dropdown container styling
  dropdownClassName="flex-1 justify-center gap-6 mb-6 bg-purple-50/50 p-4 rounded-xl"
  // Z-index for layering
  zIndex={50000}
  // Branding
  brandName="MyCompany AI"
  logoUrl="/my-logo.png"
  placeholder="How can I help you today?"
  // Event handling
  onToast={(message, type) => {
    console.log(`Toast: ${type} - ${message}`);
  }}
/>

Authentication Integration

Guest Mode (Recommended for public websites)

<ExpandableChatWidget
  organizationId="your-org-id"
  publicScope={true}
  // No authentication required - users can chat immediately
/>

Authenticated Mode

import { useState } from 'react';

function ChatComponent() {
  const [user, setUser] = useState(null);
  const [isSignedIn, setIsSignedIn] = useState(false);
  const [authLoading, setAuthLoading] = useState(false);
  const [authError, setAuthError] = useState(null);

  const handleSignIn = async (email, password) => {
    setAuthLoading(true);
    setAuthError(null);
    
    try {
      // Your authentication logic here
      const user = await signInUser(email, password);
      setUser(user);
      setIsSignedIn(true);
    } catch (error) {
      setAuthError(error.message);
      throw error; // Widget will handle the error display
    } finally {
      setAuthLoading(false);
    }
  };

  const handleSignUp = async (email, password, fullName) => {
    setAuthLoading(true);
    setAuthError(null);
    
    try {
      // Your registration logic here
      const user = await signUpUser(email, password, fullName);
      setUser(user);
      setIsSignedIn(true);
    } catch (error) {
      setAuthError(error.message);
      throw error; // Widget will handle the error display
    } finally {
      setAuthLoading(false);
    }
  };

  return (
    <ExpandableChatWidget
      organizationId="your-org-id"
      publicScope={false}
      isSignedIn={isSignedIn}
      user={user}
      onSignIn={handleSignIn}
      onSignUp={handleSignUp}
      authLoading={authLoading}
      authError={authError}
    />
  );
}

Configuration

Environment Variables

Create a .env.local file in your project root:

NEXT_PUBLIC_ZYNEX_ORG_ID=your-organization-id
NEXT_PUBLIC_ZYNEX_BASE_URL=https://zynextechai.com

Then use in your component:

<ExpandableChatWidget
  organizationId={process.env.NEXT_PUBLIC_ZYNEX_ORG_ID}
  baseUrl={process.env.NEXT_PUBLIC_ZYNEX_BASE_URL}
  publicScope={true}
/>

Features

• 🤖 Conversational AI - Advanced AI responses with context awareness
• 📚 Knowledge Base Integration - Access to your organization's knowledge sources
• 🔧 MCP Tools - Model Context Protocol tools for enhanced capabilities
• 👥 Guest Mode - Allow users to chat without signing up
• 🔐 Authentication - Optional user authentication for personalized experiences
• 📱 Responsive Design - Works on desktop and mobile devices
• 🎨 Fully Customizable - Style the widget to match your brand
• ⚡ Fast Loading - Optimized bundle size and lazy loading

Browser Support

• Chrome 88+
• Firefox 85+
• Safari 14+
• Edge 88+

License

MIT License. See LICENSE for details.

Support

For support, please contact [email protected] or visit our documentation.