nexus-chat-widget

v1.1.7

Published

a month ago

A framework-agnostic chat widget that can be easily integrated into any website

0High
0Medium
0Low

okanda

chat widget javascript typescript messaging

Nexus Chat Widget

alt text

A lightweight, framework-agnostic chat widget that can be seamlessly embedded into any website or web app. The widget appears as a floating button in the bottom-right corner and expands into a full-featured chat interface when clicked.

✨ Features

⚙️ Framework-agnostic – Use with React, Vue, Angular, or vanilla JS
💬 Expandable chat interface – Smooth UI with a modern look
📱 Responsive design – Works flawlessly across all screen sizes
🧠 Bot messaging – Programmatic control over bot messages
🧰 Customizable – Set custom bot avatar, title, and more
✅ TypeScript support
🔐 Secure – API key-based authentication
👤 Session management – Track users with unique session IDs

📦 Installation

Via NPM

npm install nexus-chat-widget

Via CDN

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/index.min.js"></script>

🚀 Quick Start (React Example)

1. Create the Widget Component

import { useEffect } from "react";
import ChatWidget from "nexus-chat-widget";

export default function ChatWidgetWrapper() {
  useEffect(() => {
    const chatWidget = new ChatWidget({
      title: 'Team Assistant',
      appToken: "nw_iJYiTEAB804FIiEYBW5m9DGX", // Found in your Nexus dashboard
      sessionId: "user-12345", // Unique identifier for this user session
      botAvatar: "https://example.com/bot-avatar.png" // Optional: custom bot avatar
    });

    // Optional: Send a welcome message
    chatWidget.addBotMessage("Hello! How can I assist you today?");

    // Cleanup function
    return () => {
      chatWidget.destroy();
    };
  }, []);

  return null; // Widget renders independently
}

2. Use the Component in Your App

import { useState } from 'react'
import './App.css'
import ChatWidgetWrapper from './components/ChatWidgetWrapper.jsx';

function App() {
  const [count, setCount] = useState(0)

  return (
    <>
      <ChatWidgetWrapper />
      <div>
        <h1>My App</h1>
        <div className="card">
          <button onClick={() => setCount((count) => count + 1)}>
            count is {count}
          </button>
        </div>
      </div>
    </>
  )
}

export default App

⚙️ API Reference

Constructor Options

| Option | Type | Default | Description | |-------------|--------|--------------------|--------------------------------------------| | title | string | 'Chat with us' | The title displayed in the chat header | | appToken | string | required | Your API key from the Nexus dashboard | | sessionId | string | required | Unique identifier for the user session | | botAvatar | string | Default bot avatar | URL of the bot's avatar image |

Methods

| Method | Parameters | Description | |------------------|----------------|------------------------------------------------| | addBotMessage | text: string | Adds a bot/agent message to the chat | | destroy | none | Removes the widget and cleans up resources | | clearMessages | none | Clears all messages from the chat interface | | isWidgetOpen | none | Returns true if the chat widget is open | | updateOptions | options: Partial<ChatWidgetOptions> | Updates widget configuration |

📁 Usage With Other Frameworks

Vanilla JavaScript (CDN)

<!DOCTYPE html>
<html>
<head>
  <title>My Website</title>
</head>
<body>
  <h1>Welcome to My Site</h1>
  
  <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/index.min.js"></script>
  <script>
    const chat = new ChatWidget({
      title: 'Support Chat',
      appToken: 'nw_your_api_key_here',
      sessionId: 'user-session-123',
      botAvatar: 'https://example.com/bot.png'
    });

    chat.addBotMessage("Welcome to our site!");
  </script>
</body>
</html>

Vanilla JavaScript (NPM)

<script type="module">
  import ChatWidget from 'nexus-chat-widget';

  const chat = new ChatWidget({
    title: 'Support Chat',
    appToken: 'nw_your_api_key_here',
    sessionId: 'user-session-123',
    botAvatar: 'https://example.com/bot.png'
  });

  chat.addBotMessage("Welcome to our site!");
</script>

Vue.js

Create a widget component:

<!-- ChatWidgetWrapper.vue -->
<template>
  <div>
    <!-- Widget renders independently -->
  </div>
</template>

<script>
import ChatWidget from 'nexus-chat-widget';

export default {
  name: 'ChatWidgetWrapper',
  mounted() {
    this.chatWidget = new ChatWidget({
      title: 'Vue Support',
      appToken: 'nw_your_api_key_here',
      sessionId: `user-${Date.now()}`,
    });
    
    this.chatWidget.addBotMessage("Hello from Vue!");
  },
  beforeUnmount() {
    if (this.chatWidget) {
      this.chatWidget.destroy();
    }
  }
}
</script>

Use in your main App.vue:

<template>
  <div id="app">
    <ChatWidgetWrapper />
    <h1>My Vue App</h1>
    <!-- Your app content -->
  </div>
</template>

<script>
import ChatWidgetWrapper from './components/ChatWidgetWrapper.vue';

export default {
  name: 'App',
  components: {
    ChatWidgetWrapper
  }
}
</script>

Angular

Create a widget component:

// chat-widget.component.ts
import { Component, OnInit, OnDestroy } from '@angular/core';
import ChatWidget from 'nexus-chat-widget';

@Component({
  selector: 'app-chat-widget',
  template: `<!-- Widget renders independently -->`
})
export class ChatWidgetComponent implements OnInit, OnDestroy {
  private chatWidget: any;

  ngOnInit() {
    this.chatWidget = new ChatWidget({
      title: 'Angular Support',
      appToken: 'nw_your_api_key_here',
      sessionId: 'angular-user-123'
    });
    
    this.chatWidget.addBotMessage("Hello from Angular!");
  }

  ngOnDestroy() {
    if (this.chatWidget) {
      this.chatWidget.destroy();
    }
  }
}

Use in your app component:

// app.component.ts
import { Component } from '@angular/core';

@Component({
  selector: 'app-root',
  template: `
    <app-chat-widget></app-chat-widget>
    <h1>My Angular App</h1>
    <!-- Your app content -->
  `
})
export class AppComponent {
  title = 'my-app';
}

🔐 Where to Find Your API Key

You can find your appToken (API key) inside your Nexus dashboard under the Messaging Service → Configuration & Setup section.

Important: Your API key should:

Start with nw_ prefix
Be kept secure and never exposed in client-side code in production
Be unique per organization/project

💡 Session Management

The sessionId parameter is crucial for maintaining conversation history across page refreshes and visits. Here are some best practices:

User-Based Sessions

// Use user ID if authenticated
const chatWidget = new ChatWidget({
  sessionId: `user-${userId}`,
  // ... other options
});

Anonymous Sessions

// Generate and store in localStorage for anonymous users
let sessionId = localStorage.getItem('chat-session-id');
if (!sessionId) {
  sessionId = `anon-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
  localStorage.setItem('chat-session-id', sessionId);
}

const chatWidget = new ChatWidget({
  sessionId: sessionId,
  // ... other options
});

📜 License

This project is licensed under the MIT License. See LICENSE for more details.