BetterCX Widget

Professional AI-powered chat widget for BetterCX platform. Seamlessly integrate intelligent customer support into any website.

The BetterCX Widget is a production-ready, embeddable chat widget that provides AI-powered customer support capabilities. Built for modern web applications, it offers seamless integration across all major platforms and frameworks.

✨ Features

• 🤖 AI-Powered Support - Intelligent responses powered by advanced AI
• 🎨 Brand Customization - Match your website's design with custom themes, colors, and titles
• 📱 Universal Compatibility - Works with React, Vue, Angular, WordPress, Shopify, and more
• 🌙 Smart Theming - Automatic light/dark mode detection
• ♿ Accessibility First - WCAG compliant with keyboard navigation
• 📊 Analytics Ready - Built-in event tracking for insights
• 🔒 Enterprise Security - JWT authentication and origin validation
• ⚡ Performance Optimized - Lightweight and fast loading
• 🖼️ Rich Media Support - Image upload and sharing capabilities
• 🏷️ Branding Options - Customizable "Powered by BetterCX" attribution
• 📌 In-page component - Embed the chat in your layout (is-component) with optional min-height and corner radii

🚀 Quick Start

React (Recommended)

npm install bettercx-widget

import React from 'react';
import { BetterCXWidgetReact } from 'bettercx-widget/react';

function App() {
  return <BetterCXWidgetReact publicKey="pk_your_widget_key_here" theme="auto" />;
}

HTML/JavaScript

<!-- Load the widget (version pinned for stability) -->
<script type="module" src="https://unpkg.com/[email protected]/dist/bettercx-widget-bundle.js"></script>

<!-- Place the widget -->
<bettercx-widget public-key="pk_your_widget_key_here" theme="auto" position="right"></bettercx-widget>

Production notes for plain HTML/JS

• Pin the version: avoid @latest; use an exact version like @1.0.54.
• CORS/Allowlist: ensure your site domain(s) are allowed by the BetterCX API.
• CSP: allow the script CDN and BetterCX API hosts in your policy. Example:
  • default-src 'self'; script-src 'self' https://unpkg.com; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; connect-src 'self' https://api.bettercx.ai https://chat.bettercx.ai; worker-src 'self' blob:;
• HTTPS: serve your site over HTTPS to avoid mixed-content/session issues.
• Rate limits: session creation is rate-limited; avoid frequent auto-reloads.

📋 Prerequisites

• A BetterCX account with an active widget key
• Your widget public key (starts with pk_)
• A modern web browser (Chrome 60+, Firefox 55+, Safari 12+, Edge 79+)

🎯 Integration Methods

React Integration

The React wrapper provides the most seamless integration experience:

import { BetterCXWidgetReact } from 'bettercx-widget/react';

// Basic usage
<BetterCXWidgetReact publicKey="pk_your_key" />;

// Advanced usage with controls
const widgetRef = useRef<BetterCXWidgetReactRef>(null);

<BetterCXWidgetReact ref={widgetRef} publicKey="pk_your_key" theme="dark" position="left" onWidgetEvent={event => console.log(event)} />;

Available Props:

• publicKey (required) - Your widget public key
• theme - 'light' | 'dark' | 'auto' (default: 'auto')
• position - 'left' | 'right' (default: 'right')
• embedded - Inline overlay mode (modal-style), distinct from isComponent
• isComponent - Render the chat in place in the page (no floating launcher); the “all conversations” list stays inside the same panel
• componentMinHeight - Optional CSS value for the shell min-height when isComponent is true (e.g. "420px", "min(80vh, 720px)")
• panelRadius, headerRadius, messageRadius, inputRadius, buttonRadius, dropdownRadius, itemRadius, avatarRadius - Optional border-radius values (any valid CSS) for isComponent only; omitted props keep the default look
• isAttachmentsDisabled - Disable image attachments
• onWidgetEvent - Event handler function
• className - Custom CSS class
• style - Inline styles object

Web Component

For vanilla JavaScript or other frameworks:

<bettercx-widget public-key="pk_your_key" theme="auto" position="right"> </bettercx-widget>

WordPress Integration

Add to your theme's functions.php:

function bettercx_widget_shortcode($atts) {
    $atts = shortcode_atts(array(
        'public_key' => '',
        'theme' => 'auto'
    ), $atts);

    if (empty($atts['public_key'])) {
        return '<!-- BetterCX Widget: public_key required -->';
    }

    return sprintf(
        '<script type="module" src="https://unpkg.com/bettercx-widget@latest/dist/bettercx-widget/bettercx-widget.esm.js"></script>
        <bettercx-widget public-key="%s" theme="%s"></bettercx-widget>',
        esc_attr($atts['public_key']),
        esc_attr($atts['theme'])
    );
}
add_shortcode('bettercx_widget', 'bettercx_widget_shortcode');

Usage: [bettercx_widget public_key="pk_your_key"]

Shopify Integration

Add to your theme's theme.liquid before </body>:

<script type="module" src="https://unpkg.com/bettercx-widget@latest/dist/bettercx-widget/bettercx-widget.esm.js"></script>
<bettercx-widget
  public-key="{{ settings.bettercx_public_key }}"
  theme="{{ settings.bettercx_theme | default: 'auto' }}">
</bettercx-widget>

🎨 Customization

Themes

The widget automatically detects your website's theme, but you can override it:

// Light theme
<BetterCXWidgetReact theme="light" />

// Dark theme
<BetterCXWidgetReact theme="dark" />

// Auto-detect (recommended)
<BetterCXWidgetReact theme="auto" />

Custom Styling

Override CSS custom properties to match your brand:

bettercx-widget {
  --bcx-primary: #your-brand-color;
  --bcx-background: #ffffff;
  --bcx-text: #333333;
  --bcx-title: 'Your Custom Title';
}

Custom Title

Set a custom title for your chat widget:

<BetterCXWidgetReact publicKey="pk_your_key" title="Welcome to Support" />

Branding Options

Control the "Powered by BetterCX" attribution:

<BetterCXWidgetReact publicKey="pk_your_key" showAttribution={true} />

Positioning

Control widget placement:

// Right side (default)
<BetterCXWidgetReact position="right" />

// Left side
<BetterCXWidgetReact position="left" />

In-page component mode (is-component)

Use this when the chat should live inside your layout (e.g. a Webflow Embed, a React section, or a WordPress block area) instead of a floating corner button.

Behavior:

• No floating launcher: the chat UI is shown where you place the <bettercx-widget> element.
• The conversation list and the main chat share one enclosed panel (same as embedded/floating UX, but anchored in the document flow).
• In this mode the widget uses light DOM styling so font-family inherits from the host page (useful for brand typography).
• Optional radius props map to internal CSS variables and only affect is-component; if you omit them, defaults match the standard design.

HTML / vanilla — use kebab-case attributes:

<script type="module" src="https://unpkg.com/[email protected]/dist/bettercx-widget-bundle.js"></script>

<bettercx-widget
  public-key="pk_your_key"
  is-component="true"
  component-min-height="min(80vh, 720px)"
  panel-radius="16px"
  header-radius="12px"
  message-radius="14px"
  input-radius="10px"
  button-radius="8px"
  dropdown-radius="10px"
  item-radius="12px"
  avatar-radius="9999px"
  theme="auto"
></bettercx-widget>

React — use camelCase props (the wrapper passes kebab-case attributes to the element):

<BetterCXWidgetReact
  publicKey="pk_your_key"
  isComponent
  componentMinHeight="min(80vh, 720px)"
  panelRadius="16px"
  headerRadius="12px"
  messageRadius="14px"
  inputRadius="10px"
  buttonRadius="8px"
  dropdownRadius="10px"
  itemRadius="12px"
  avatarRadius="9999px"
/>

WordPress shortcode — use snake_case attributes (see plugin for full list):

[bettercx_widget public_key="pk_your_key" is_component="true" component_min_height="min(65vh,560px)" panel_radius="20px" header_radius="8px" message_radius="14px" input_radius="10px" button_radius="8px" dropdown_radius="10px" item_radius="12px" avatar_radius="8px"]

Reference — same knobs, different naming:

| Feature | HTML attribute | React prop | Shortcode attribute | |--------|----------------|------------|---------------------| | In-page mode | is-component | isComponent | is_component | | Shell min-height | component-min-height | componentMinHeight | component_min_height | | Main panel corners | panel-radius | panelRadius | panel_radius | | Header / bar | header-radius | headerRadius | header_radius | | Message bubbles | message-radius | messageRadius | message_radius | | Composer field | input-radius | inputRadius | input_radius | | Icon / action buttons | button-radius | buttonRadius | button_radius | | Dropdown container | dropdown-radius | dropdownRadius | dropdown_radius | | List rows / small cards | item-radius | itemRadius | item_radius | | Avatars | avatar-radius | avatarRadius | avatar_radius |

component-min-height: any valid CSS length for min-height (e.g. 480px, 70vh, or min(80vh, 720px) so the block grows on short viewports but caps on tall screens).

📊 Event Tracking

Monitor widget interactions for analytics:

<BetterCXWidgetReact
  publicKey="pk_your_key"
  onWidgetEvent={event => {
    switch (event.type) {
      case 'opened':
        // Track chat opened
        analytics.track('chat_opened');
        break;
      case 'message-sent':
        // Track message sent
        analytics.track('message_sent', { content: event.data.content });
        break;
      case 'message-received':
        // Track AI response
        analytics.track('ai_response_received');
        break;
    }
  }}
/>

🔧 Programmatic Control

Control the widget programmatically:

const widgetRef = useRef<BetterCXWidgetReactRef>(null);

// Open chat
await widgetRef.current?.open();

// Close chat
await widgetRef.current?.close();

// Toggle chat
await widgetRef.current?.toggle();

// Send message
await widgetRef.current?.sendMessage('Hello!');

🌍 Multi-language Support

The widget automatically detects your website's language and provides localized text:

• English (default)
• Polish (auto-detected)

🖼️ Rich Media Support

The widget supports image sharing and uploads:

• Image Upload - Users can upload and share images in chat
• File Support - Various image formats supported (JPG, PNG, GIF, WebP)
• Secure Handling - Images are processed securely through BetterCX servers

📱 Responsive Design

The widget adapts to all screen sizes:

• Desktop: Floating widget in corner
• Tablet: Optimized for touch interaction
• Mobile: Full-screen chat experience

🔒 Security & Privacy

• JWT Authentication - Secure token-based authentication
• Origin Validation - Only works on authorized domains
• No Data Storage - No sensitive data stored locally
• HTTPS Required - Secure communication only
• GDPR Compliant - Privacy-first design

🚀 Performance

• Lightweight - Minimal bundle size impact
• Lazy Loading - Loads only when needed
• Optimized Assets - Compressed and minified
• Fast Rendering - 60fps animations

🛠️ Troubleshooting

Widget Not Appearing

1. Verify your public key is correct
2. Check browser console for errors
3. Ensure your domain is authorized
4. Verify HTTPS is enabled

Styling Issues

1. Check for CSS conflicts
2. Verify custom properties are set correctly
3. Test with different themes
4. Clear browser cache

Integration Problems

1. Ensure proper script loading
2. Check for JavaScript errors
3. Verify framework compatibility
4. Test in different browsers

📚 Examples

Check out our comprehensive examples:

• React Examples - Complete React applications
• WordPress Plugin - WordPress integration
• Live Demo - Interactive demonstration

🤝 Support

• Documentation: Full API Reference
• Examples: Integration Examples
• Support: BetterCX Support Portal
• Email: [email protected]

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Ready to enhance your customer support? Get started with the BetterCX Widget today! 🚀