newinstance-livechat-widget

v0.1.4

Published

5 months ago

A production-ready React chat widget with live agent support, bot integration, and standalone deployment capabilities

0High
0Medium
0Low

talktothelaw

chat widget livechat customer-support react typescript bot agent

NewInstance Live Chat Widget

A production-ready React chat widget with live agent support, bot integration, and standalone deployment capabilities.

Features

React SDK: Easy integration into React applications
Standalone Script: Embeddable in any website without React
Live Agent Support: Real-time chat with human agents
Bot Integration: AI-powered conversation flows with seamless handoff
Session Persistence: Maintains conversation state across page reloads
Responsive Design: Mobile-first design with customizable themes
TypeScript: Full type safety and excellent developer experience
Production Ready: Optimized builds and comprehensive error handling

Quick Reference

Standalone Script (Most Common)

<div id="chat-container"></div>
<script src="https://live-chat.cinstance.com/dist/newinstance-widget.umd.js"></script>
<script>
const widget = new NewInstanceWidget.ChatWidgetVanilla({
    appId: 'your-app-id',
    apiKey: 'your-api-key'
});
widget.mount('chat-container');
</script>

React Component

import { ChatWidget } from 'newinstance-livechat-widget';
<ChatWidget config={{ appId: 'your-app', apiKey: 'your-key' }} />

Quick Start

React SDK Installation

npm install newinstance-livechat-widget

Basic React Usage

import React, { useState } from 'react';
import { ChatWidget } from 'newinstance-livechat-widget';

const config = {
  appId: 'your-app-id',
  apiKey: 'your-api-key',
  customerName: 'John Doe', // Optional - user will be prompted if not provided
  customerEmail: '[email protected]', // Optional
  autoOpen: false,
  theme: 'dark' as const // or custom theme object
};

function App() {
  const [error, setError] = useState<string | null>(null);

  const handleError = (error: Error) => {
    console.error('Widget error:', error);
    setError(error.message);
  };

  return (
    <div>
      <h1>My App</h1>
      <ChatWidget
        config={config}
        onError={handleError}
        onClose={() => {
          console.log('Widget closed');
        }}
        onMinimize={() => {
          console.log('Widget minimized');
        }}
      />
    </div>
  );
}

export default App;

Standalone Script Usage

For non-React websites, include the standalone script:

<!DOCTYPE html>
<html>
<head>
    <title>My Website</title>
</head>
<body>
    <h1>Welcome to my website</h1>

    <!-- Chat Widget Container -->
    <div id="chat-container"></div>

    <!-- Include the widget script -->
    <script src="https://live-chat.cinstance.com/dist/newinstance-widget.umd.js"></script>
    <script>
        // Initialize the widget
        const widget = new NewInstanceWidget.ChatWidgetVanilla({
            appId: 'your-app-id',
            apiKey: 'your-api-key',
            customerName: 'John Doe', // Optional - user will be prompted if not provided
            customerEmail: '[email protected]', // Optional
            autoOpen: false, // Optional - controls if widget opens automatically
            theme: 'dark' // or custom theme object
        });

        // Set event handlers (optional)
        widget.setEventHandlers({
            onError: (error) => {
                console.error('Widget error:', error);
            },
            onClose: () => {
                console.log('Widget closed');
            },
            onMinimize: () => {
                console.log('Widget minimized');
            }
        });

        // Mount the widget
        widget.mount('chat-container');
    </script>
</body>
</html>

Configuration Options

Widget Configuration

| Option | Type | Required | Default | Description | |--------|------|----------|---------|-------------| | appId | string | ✅ | - | Your application ID | | apiKey | string | ✅ | - | Your API key for authentication | | customerName | string | ❌ | - | Customer name (user will be prompted if not provided) | | customerEmail | string | ❌ | - | Customer email address | | customerId | string | ❌ | - | Optional identifier for the customer | | initialMessage | string | ❌ | - | Optional initial message to send | | theme | string | object | ❌ | 'light' | Theme configuration ('light', 'dark', or custom theme object) | | autoOpen | boolean | ❌ | false | Whether to automatically open the widget when customer info is provided |

React Component Props

For React usage, the ChatWidget component accepts these props:

| Prop | Type | Required | Description | |------|------|----------|-------------| | config | WidgetConfig | ✅ | Widget configuration object (see above) | | onClose | () => void | ❌ | Callback when widget is closed | | onMinimize | () => void | ❌ | Callback when widget is minimized | | onError | (error: Error) => void | ❌ | Callback for error handling | | className | string | ❌ | Additional CSS class name |

Widget Methods (Standalone Only)

After creating a standalone widget instance with new NewInstanceWidget.ChatWidgetVanilla(), you can use these methods:

// Mount the widget to a container
widget.mount('container-id');

// Unmount the widget
widget.unmount();

// Update widget configuration
widget.updateConfig({
    theme: 'dark',
    customerName: 'New Name'
});

// Set event handlers
widget.setEventHandlers({
    onError: (error) => console.error(error),
    onClose: () => console.log('Widget closed'),
    onMinimize: () => console.log('Widget minimized')
});

// Get widget mode (react or standalone)
const mode = widget.getMode();

Custom Theme Object

const customTheme = {
  primaryColor: '#007bff',
  secondaryColor: '#6c757d',
  bubbleColor: '#ffffff',
  iconColor: '#ffffff',
  backgroundColor: '#ffffff',
  textColor: '#333333'
};

// For React
<ChatWidget
  config={{
    appId: 'your-app-id',
    apiKey: 'your-api-key',
    theme: customTheme
  }}
/>

// For Standalone
const widget = new NewInstanceWidget.ChatWidgetVanilla({
    apiKey: 'your-api-key',
    appId: 'your-app-id',
    theme: customTheme
});

API Integration

Authentication

The widget uses API key authentication. Include your API key in the widget configuration:

React:

<ChatWidget
  config={{
    appId: 'your-app-id',
    apiKey: 'your-api-key-here'
  }}
/>

Standalone:

const widget = new NewInstanceWidget.ChatWidgetVanilla({
    apiKey: 'your-api-key-here',
    appId: 'your-app-id'
});

Bot Integration

The widget automatically integrates with your bot system. Configure bot flows in your NewInstance dashboard.

Live Agent Handoff

When a bot conversation needs human assistance, the widget seamlessly transitions to live agent chat with real-time messaging.

Customization

Styling

The widget includes all necessary styles internally. Customization is handled through the theme configuration object only - no external CSS imports are required.

All styling is controlled through the theme property in your widget configuration:

Event Handling

React:

const handleError = (error: Error) => {
  console.error('Widget error:', error);
  // Handle error (e.g., show notification)
};

<ChatWidget
  config={config}
  onError={handleError}
  onClose={() => {
    console.log('Widget closed');
  }}
  onMinimize={() => {
    console.log('Widget minimized');
  }}
/>

Standalone:

const widget = new NewInstanceWidget.ChatWidgetVanilla({
    apiKey: 'your-api-key',
    appId: 'your-app-id'
});

// Set event handlers after creating the widget
widget.setEventHandlers({
    onError: (error) => {
        console.error('Widget error:', error);
        // Handle error (e.g., show notification)
    },
    onClose: () => {
        console.log('Widget closed');
    },
    onMinimize: () => {
        console.log('Widget minimized');
    }
});

widget.mount('chat-container');

Troubleshooting

Common Issues

Widget not loading:
- Verify your API key is correct and active
- Check browser console for JavaScript errors
- Ensure the widget script is loaded properly
Styling issues:
- Verify theme configuration is properly formatted
- Ensure theme colors are valid CSS color values
- Check for z-index conflicts if the widget appears behind other elements
React integration issues:
- Ensure React and ReactDOM versions are compatible (16.8+)
- Check for TypeScript errors if using TypeScript
- Verify the component is properly imported
Standalone script issues:
- Ensure the script is loaded before creating new NewInstanceWidget.ChatWidgetVanilla()
- Check that the configuration object is properly formatted
- Verify the container element exists before calling widget.mount()
- Make sure to use the correct constructor: NewInstanceWidget.ChatWidgetVanilla

Debug Tips

Open browser developer tools to check for console errors
Verify network requests are successful in the Network tab
Check that the widget configuration matches the expected format
Test with a minimal configuration first, then add customizations

Support

For widget integration help:

Documentation: https://docs.cinstance.com
Integration Issues: GitLab Issues
Technical Support: [email protected]
API Questions: Check the troubleshooting section above

Examples

Check out example implementations in the /test-implementations directory:

Standalone HTML Example

See test-implementations/standalone.html for a complete working example with:

Theme customization controls
Event handling
Environment detection
Error handling
Dynamic configuration updates

React Integration

import React, { useState } from 'react';
import { ChatWidget } from 'newinstance-livechat-widget';

const DEMO_CONFIG = {
  appId: 'your-app-id',
  apiKey: 'your-api-key',
  customerName: 'Demo User',
  customerEmail: '[email protected]',
  autoOpen: false,
  theme: 'dark' as const
};

function App() {
  const [error, setError] = useState<string | null>(null);

  const handleError = (error: Error) => {
    console.error('Widget error:', error);
    setError(error.message);
  };

  return (
    <div>
      <h1>My App</h1>
      <ChatWidget
        config={DEMO_CONFIG}
        onError={handleError}
        onClose={() => {
          console.log('Widget closed');
        }}
        onMinimize={() => {
          console.log('Widget minimized');
        }}
      />
    </div>
  );
}