Insyt Widget

Embed real-time, conversational analytics and support directly into your applications. The Insyt Widget enables users to chat with their data, receive instant AI-powered insights, and interact with support or analytics agents—all within a beautiful, resizable chat interface. With seamless Socket.IO integration, robust authorization, and easy customization, you can empower your users to ask questions, get answers, and collaborate in real time, right inside your app.

Package Ownership

This package is developed and maintained by Insyt.

About Insyt:
Insyt empowers businesses to connect, analyze, and visualize data using natural language. With AI-driven analytics, interactive dashboards, and real-time insights, Insyt transforms complex databases into actionable intelligence—no coding required. Learn more at insyt.co.

Repository: github.com/zannujulius/npm_insyt_widget
Homepage: insyt.co
Issues: Report on GitHub

Features

• 🚀 Real-time Communication: Socket.IO integration with automatic reconnection and session restoration
• 🔐 Authorization System: Built-in authentication and authorization checking with RTK Query
• 🎨 Beautiful Design: Modern chat interface with smooth animations
• 📏 Resizable Interface: Drag corners and edges to resize the chat window to your preferred size
• 📱 Responsive: Works perfectly on desktop and mobile devices
• 🔧 Highly Configurable: Customizable themes, positions, and behavior

Installation

npm install insyt-widget

Usage

import React from "react";
import { InsytWidget } from "insyt-widget";
import "insyt-widget/style.css";

function App() {
  return (
    <div>
      <h1>Your App Content</h1>
      <InsytWidget
        projectKey="your-project-key"
        apiKey="your-api-key"
        username="john.doe"
        position="bottom-right"
        secureIdentifier="optional-secure-id"
        context={{
          insyt_user: "john.doe", // Required - identifies the user
          caller_id: "john.doe",
          timezone: "America/New_York",
          current_time: "2025-07-22",
          subdomain: "yourcompany",
          role: "admin",
          sessionid: "unique-session-id",
        }}
      />
    </div>
  );
}

Props

| Prop | Type | Required | Default | Description | | ------------------ | --------------------------------- | -------- | -------------- | ------------------------------------------------ | | projectKey | string | ✅ | - | Your project key | | userId | string | ❌ | - | Unique user identifier | | username | string | ✅ | - | Username for authorization | | position | 'bottom-right' \| 'bottom-left' | ❌ | bottom-right | Widget position | | theme | object | ❌ | - | Custom theme configuration | | secureIdentifier | string | ❌ | '' | Optional secure identifier for enhanced security | | context | object | ✅ | - | User context information (see section below) |

Authorization System

The widget automatically performs authorization checks when mounted using RTK Query:

Authorization Flow

1. Initial Check: When the widget mounts, it calls the authorization API
2. Loading State: Shows a loading component while checking authorization
3. Success: If authorized, the normal chat widget is displayed
4. Failure: If unauthorized, shows an error component with retry option

Error Handling

The widget handles various authorization failure scenarios:

• User not whitelisted
• Domain not whitelisted
• Invalid secure identifier
• Network errors
• API errors

Resizable Interface

The chat widget is fully resizable with the following features:

• Default Size: 20vw width × 70vh height (with reasonable min/max constraints)
• Minimum Size: 300px × 400px
• Maximum Size: 800px × 800px
• Resize Handles: All corners and edges (8 resize handles total)
• Visual Feedback: Resize handles appear on hover
• Responsive: Adapts to different screen sizes

Context Object

The context prop is a crucial part of the widget as it provides information about the user and their environment to Insyt. This context is used to tailor the AI's responses and ensure relevant interactions.

Required Context Fields

| Field | Type | Description | Example | | ------------ | -------- | ------------------------------------------------ | ------------ | | insyt_user | string | REQUIRED - User identifier for Insyt systems | "john.doe" |

Suggested Context Fields

| Field | Type | Description | Example | | -------------- | -------- | ----------------------------------------- | -------------------- | | caller_id | string | Identifier of the user making the request | "john.doe" | | timezone | string | User's timezone (IANA format) | "America/New_York" | | current_time | string | Current time in the user's timezone | "2025-07-22" | | subdomain | string | Subdomain or company identifier | "acme" | | role | string | User's role in the system | "admin" | | sessionid | string | Unique session identifier | "uid12345" |

Example Context Object

context={{
  // Required
  insyt_user: "john.doe",  // Must be included

  // Suggested
  caller_id: "john.doe",
  timezone: "America/New_York",  // IANA timezone format
  current_time: "2025-07-22",    // Current date/time
  subdomain: "acme",             // Company/tenant identifier
  role: "admin",                 // User's role
  sessionid: "uid12345",         // Unique session ID

  // Optional custom fields
  department: "engineering",     // User's department
  language: "en-US",             // Preferred language
  permissions: ["read", "write"] // User permissions
}}

Context Usage

The context object is passed to Insyt's AI system with each interaction, enabling:

1. Personalization: Tailoring responses based on user role and permissions
2. Time-awareness: Providing time-sensitive information in the user's timezone
3. Continuity: Maintaining session context across interactions
4. Authorization: Additional layer of user verification

The context data helps Insyt understand who is interacting with the system and provides critical information that informs AI responses and data access permissions.

Resize Controls

• Corner Handles: se, sw, ne, nw - Resize both width and height
• Edge Handles: n, s, e, w - Resize single dimension
• Visual Cues: Handles become visible on hover with appropriate cursors

Socket.IO Protocol

The widget uses Socket.IO and expects the following events:

Customization

Theme

<InsytWidget
  // ... other props
  theme={{
    primaryColor: "#1890ff",
    backgroundColor: "#ffffff",
    textColor: "#000000",
  }}
/>

Styling

The widget uses Tailwind CSS for styling. You can override styles by targeting the .insyt-widget class:

.insyt-widget {
  /* Your custom styles */
}

/* Customize resize handles */
.insyt-resizable-widget .react-resizable-handle {
  /* Custom handle styles */
}

License

MIT