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

🚀 Quick Start

$3

``bash
npm install bettercx-widget
`

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

function App() {
return ;
}
`

$3

`html





`

#### Production notes for plain HTML/JS

- Pin the version: avoid @latest; use an exact version like @1.0.43.
- 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://widget.bettercx.ai/prod; 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

$3

The React wrapper provides the most seamless integration experience:

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

// Basic usage
;

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

console.log(event)} />;
`

Available Props:

- publicKey (required) - Your widget public key
- theme - 'light' | 'dark' | 'auto' (default: 'auto')
- position - 'left' | 'right' (default: 'right')
- onWidgetEvent - Event handler function
- className - Custom CSS class
- style - Inline styles object

$3

For vanilla JavaScript or other frameworks:

`html

`

$3

Add to your theme's functions.php:

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

if (empty($atts['public_key'])) {
return '';
}

return sprintf(
'
',
esc_attr($atts['public_key']),
esc_attr($atts['theme'])
);
}
add_shortcode('bettercx_widget', 'bettercx_widget_shortcode');
`

Usage: [bettercx_widget public_key="pk_your_key"]

$3

Add to your theme's theme.liquid before :

`liquid

public-key="{{ settings.bettercx_public_key }}"
theme="{{ settings.bettercx_theme | default: 'auto' }}">

`

🎨 Customization

$3

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

`tsx
// Light theme


// Dark theme


// Auto-detect (recommended)

`

$3

Override CSS custom properties to match your brand:

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

$3

Set a custom title for your chat widget:

`tsx

`

$3

Control the "Powered by BetterCX" attribution:

`tsx

`

$3

Control widget placement:

`tsx
// Right side (default)


// Left side

`

📊 Event Tracking

Monitor widget interactions for analytics:

`tsx
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:

`tsx
const widgetRef = useRef(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

$3

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

$3

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

$3

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: office@appwave.dev

📄 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! 🚀