@nabeh/chat-widget

Embeddable AI chat widget for Angular and other web applications.

Installation

npm install @nabeh/chat-widget

Angular Usage

Use the widget after the user session is available so you can pass user context and, if needed, an access token.

import { AfterViewInit, Component, OnDestroy } from '@angular/core';
import { createChatWidget } from '@nabeh/chat-widget';

@Component({
  selector: 'app-root',
  template: ''
})
export class AppComponent implements AfterViewInit, OnDestroy {
  private widget?: ReturnType<typeof createChatWidget>;

  ngAfterViewInit(): void {
    this.widget = createChatWidget({
      apiBaseUrl: 'http://your-api-url',
      endpoints: {
        ask: '/my-chats/:chatId/messages',
        history: '/my-chats/:chatId/messages',
        listChats: '/my-chats',
        createChat: '/my-chats',
        updateChat: '/my-chats/:chatId',
        deleteChat: '/my-chats/:chatId'
      },
      rag: {
        knowledgeNames: ['sample-kb'],
        loadHistoryOnOpen: true
      },
      getUserContext: async () => ({
        userId: 'your-user-id',
        // email: '[email protected]'
      })
    });
  }

  ngOnDestroy(): void {
    this.widget?.destroy();
  }
}

Angular Embedded Page Usage

Use displayMode: 'embedded' when the host application already owns the page shell and you only want the chat experience rendered inside a content area.

import { AfterViewInit, Component, ElementRef, OnDestroy, ViewChild } from '@angular/core';
import { createChatWidget } from '@nabeh/chat-widget';

@Component({
  selector: 'app-knowledge-assistant-page',
  template: `<div #chatRoot class="knowledge-assistant-root"></div>`
})
export class KnowledgeAssistantPageComponent implements AfterViewInit, OnDestroy {
  @ViewChild('chatRoot', { static: true })
  private chatRoot?: ElementRef<HTMLElement>;

  private widget?: ReturnType<typeof createChatWidget>;

  ngAfterViewInit(): void {
    if (!this.chatRoot?.nativeElement) {
      return;
    }

    this.widget = createChatWidget({
      apiBaseUrl: 'http://your-api-url',
      displayMode: 'embedded',
      mount: this.chatRoot.nativeElement,
      embedded: {
        showHeader: false
      },
      endpoints: {
        ask: '/my-chats/:chatId/messages',
        history: '/my-chats/:chatId/messages',
        listChats: '/my-chats',
        createChat: '/my-chats',
        updateChat: '/my-chats/:chatId',
        deleteChat: '/my-chats/:chatId'
      },
      rag: {
        knowledgeNames: ['sample-kb'],
        loadHistoryOnOpen: true
      },
      getUserContext: async () => ({
        userId: 'your-user-id'
      })
    });
  }

  ngOnDestroy(): void {
    this.widget?.destroy();
  }
}

Configuration

• apiBaseUrl: Backend base URL. Example: https://api.example.com
• displayMode: widget for the floating launcher, embedded for a full chat page rendered inside mount
• endpoints.ask: Send-message endpoint
• endpoints.history: Fetch chat history endpoint
• endpoints.listChats: List chats endpoint
• endpoints.createChat: Create chat endpoint
• endpoints.updateChat: Update chat metadata endpoint
• endpoints.deleteChat: Delete chat endpoint
• rag.knowledgeNames: Knowledge bases to query
• rag.loadHistoryOnOpen: Load history automatically when the widget opens
• getUserContext: Function that returns the current user context
• getAccessToken: Optional function that returns a bearer token
• embedded.showHeader: In embedded mode, show or hide the library-owned page header. Default: false

Example With Token

import { createChatWidget } from '@nabeh/chat-widget';

const widget = createChatWidget({
  apiBaseUrl: 'http://your-api-url',
  endpoints: {
    ask: '/my-chats/:chatId/messages',
    history: '/my-chats/:chatId/messages',
    listChats: '/my-chats',
    createChat: '/my-chats',
    updateChat: '/my-chats/:chatId',
    deleteChat: '/my-chats/:chatId'
  },
  rag: {
    knowledgeNames: ['sample-kb'],
    loadHistoryOnOpen: true
  },
  getAccessToken: async () => localStorage.getItem('access_token'),
  getUserContext: async () => ({
    userId: 'your-user-id',
    email: '[email protected]'
  })
});

Browser Global

If you are loading the browser bundle manually, the package also exposes:

• window.ChatWidget.init(config)
• window.ChatWidget.createChatWidget(config)

Widget Instance API

createChatWidget(...) returns an instance with:

• open()
• close()
• toggle()
• destroy()
• sendMessage(message)
• setAccessTokenProvider(provider)
• getChatId()
• loadChats()
• loadHistory()

Notes

• apiBaseUrl should point to your backend, not your Angular frontend
• initialize the widget after authentication if your backend requires user identity or tokens
• call destroy() when the hosting Angular component is destroyed
• for embedded mode, give the mount container a real height such as min-height: calc(100vh - navbar - footer)