Chat Widget

1 Chat Widget
- 1.1 Overview
- 1.2 Who it's for
- 1.3 Benefits
  - 1.3.1 Seamless Integration
  - 1.3.2 Real-Time Intelligence
  - 1.3.3 Source Transparency
  - 1.3.4 Guided Interactions
  - 1.3.5 Enterprise Security
  - 1.3.6 Persistent Context
  - 1.3.7 Developer-Friendly
  - 1.3.8 Rich Content Support
- 1.4 Example Use Cases
  - 1.4.1 Knowledge Base Assistant
  - 1.4.2 Customer Support Augmentation
  - 1.4.3 Sales Enablement
  - 1.4.4 Onboarding Assistant
- 1.5 Step-by-Step Guide
  - 1.5.1 If the widget doesn't appear, please verify:
- 1.6 Tips & Tricks
  - 1.6.1 Use Suggested Prompts
  - 1.6.2 Keyboard Shortcuts
  - 1.6.3 Reference Navigation
  - 1.6.4 Markdown Support
  - 1.6.5 Default Prompts
  - 1.6.6 Style Isolation
- 1.7 Limitations
  - 1.7.1 Browser Compatibility
  - 1.7.2 Authentication Required
  - 1.7.3 Network Requirements
  - 1.7.4 Styling Constraints
  - 1.7.5 Single Chat Instance
  - 1.7.6 Message History
  - 1.7.7 Mobile Considerations

Overview

The Chat Widget provides a fully embeddable, AI-powered chat interface that seamlessly integrates into any web application. This component enables real-time conversations with AI assistants, complete with streaming responses, reference tracking, and intelligent prompt suggestions, all wrapped in a secure and isolated package.

Who it's for

Product teams looking to embed conversational AI into their applications
Internal tool developers building knowledge management systems
Enterprise platforms requiring secure, isolated chat components
Development teams needing quick AI integration without infrastructure overhead
Organizations wanting to provide contextual AI assistance within their applications

Benefits

Seamless Integration

Drop-in web component that works with any web framework or vanilla JavaScript. Leverages module federation for zero-friction deployment and Shadow DOM for complete style isolation.

Real-Time Intelligence

Streaming responses provide immediate feedback as the AI generates answers, creating a natural conversational flow rather than waiting for complete responses.

Source Transparency

Every AI response includes trackable references and citations, allowing users to verify information and explore source documents directly from the chat interface.

Guided Interactions

Suggested prompts help users get started quickly and discover powerful use cases they might not have considered, reducing onboarding friction and increasing feature adoption.

Enterprise Security

Built-in OIDC authentication ensures secure access control, while GraphQL and WebSocket communications can be configured to meet enterprise security requirements.

Persistent Context

Automatic chat history preservation across sessions means users never lose their conversation thread, creating continuity in complex, multi-step workflows.

Developer-Friendly

Custom events (ready, reference-click) enable deep integration with host applications, allowing you to create cohesive experiences that respond to chat interactions.

Rich Content Support

Full Markdown rendering with syntax highlighting makes it perfect for technical documentation, code examples, and formatted responses that go beyond plain text.

Example Use Cases

Knowledge Base Assistant

Embed the widget in your documentation portal or internal wiki. Users ask natural language questions and receive contextual answers with direct links to source documents, reducing support tickets and improving self-service.

Customer Support Augmentation

Add to your support dashboard. Support agents query the AI for policy information, troubleshooting steps, or product details, with all responses including references to official documentation for verification.

Sales Enablement

Embed in your CRM or sales portal. Sales teams ask questions about products, pricing, or competitive positioning, receiving accurate information with citations to approved materials.

Onboarding Assistant

Integrate into employee onboarding platforms. New hires ask questions about policies, procedures, or systems, receiving guided answers with links to relevant training materials.

Step-by-Step Guide

Add the Web Component

Add the chat widget to your HTML page or web application:

<unique-chat-widget id="chat"></unique-chat-widget>

The widget is built as a standards-compliant web component and works with any framework (React, Vue, Angular) or vanilla JavaScript.

Configure Authentication

Set up OIDC authentication to secure access to the chat:

const chatWidget = document.getElementById('chat');

  chatWidget.data = {
    spaceId: 'your-space-id',
    auth: {
      redirectUrl: 'https://your-app.com/callback%27, 
      popupRedirectUrl: 'https://your-app.com/popup-callback%27, 
      silentRedirectUrl: 'https://your-app.com/silent-callback%27 
    }
  };

Security Note: The widget uses OIDC-compliant authentication. Ensure your redirect URLs are properly configured in your identity provider.

Start Chatting

Once authenticated, users can:

Type messages directly into the input field
Press Enter to send (Shift+Enter for new lines)
Click suggested prompts for quick access to common queries
View AI responses with real-time streaming
Click references to explore source documents

The AI assistant name appears in the input placeholder, providing context about who you're talking to.

Explore References

When the AI includes references in responses:

Click the "N references" button to expand the reference list
Each reference shows a sequence number matching superscript citations in the text
Click individual references to navigate to source documents
References fire custom events your application can handle

Copy Responses

For AI messages:

Hover over any assistant response
Click the copy button that appears
The full response (excluding reference markers) is copied to your clipboard
Use copied content in emails, documents, or other applications

View Chat History

The widget automatically preserves conversation history:

Scroll up to view previous messages
Infinite scroll loads older messages as needed
Chat sessions persist across page reloads
Time stamps show relative time (e.g., "2 hours ago")

Listen to Widget Events

Integrate the widget with your application by listening to custom events:

const chatWidget = document.getElementById('chat');
  // Fires when the widget is ready
  chatWidget.addEventListener('ready', (event) => {
    console.log('Widget ready:', event.detail.status);
  });
  // Fires when user clicks a reference
  chatWidget.addEventListener('reference-click', (event) => {
    const contentId = event.detail.data;
    // Navigate to document, open modal, etc.
    navigateToDocument(contentId);
  });

Integration Tip: Use the reference-click event to create seamless navigation between chat insights and your document viewer, creating a unified knowledge exploration experience.

If the widget doesn't appear, please verify:

The web component script is loaded before trying to use the element
Authentication is properly configured
Your browser supports web components (all modern browsers do)
Network requests to the GraphQL endpoint are succeeding

Tips & Tricks

Use Suggested Prompts

Click the "Suggestions" button to see pre-configured prompts relevant to your use case. This helps users discover powerful features and get accurate responses faster.

Keyboard Shortcuts

Enter to send message
Shift+Enter for new line
The input auto-focuses for immediate typing

Reference Navigation

When you see superscript numbers in responses (e.g., "According to the documentation[1]"), these link to specific sources. Always expand references for important decisions to verify AI reasoning.

Markdown Support

The widget supports full Markdown, including:

Code blocks with syntax highlighting
Tables and lists
Links and formatting
Inline code

This makes it excellent for technical content and documentation.

Default Prompts

You can pre-populate the chat with a question:

 chatWidget.data = {
    spaceId: 'your-space-id',
    defaultPrompt: 'What are the key features of this product?',
    auth: { /* ... */ }
  };

Great for guided workflows or jumping to specific topics.

Style Isolation

The widget uses Shadow DOM, meaning your application styles won't break the chat interface and the chat won't affect your styles. It's completely isolated while remaining fully customizable through CSS custom

properties.

Limitations

Browser Compatibility

The widget requires modern browser features:

Web Components (Custom Elements v1)
Shadow DOM v1
ES6+ JavaScript

All evergreen browsers (Chrome, Firefox, Safari, Edge) are fully supported. IE11 is not supported.

Authentication Required

The widget requires OIDC authentication to function. Anonymous or unauthenticated usage is not currently supported. You must have an identity provider configured.

Network Requirements

The widget requires:

HTTPS for secure WebSocket connections
GraphQL API endpoint accessibility
WebSocket support (not possible through some corporate proxies)

If WebSockets are blocked, the real-time streaming functionality will fail. Ensure your network infrastructure supports WSS connections.

Styling Constraints

While the widget provides dynamic theming through CSS custom properties, the Shadow DOM isolation means you cannot directly apply arbitrary CSS from your application. Customization is limited to supported theme

variables.

Single Chat Instance

Currently, only one active chat session per user is supported. Opening the widget in multiple tabs will share the same chat session, which may cause confusion if messages are sent from different locations.

Message History

Chat history is stored in browser localStorage. Clearing browser data will reset the conversation history. For multi-device sync, users will need to start new conversations on each device.

Mobile Considerations

The widget is responsive and works on mobile devices, but the experience is optimized for desktop use. On small screens, the references panel and suggestions list may require scrolling.

Our solution uses GraphQL and WebSocket for real-time communication. Performance and feature availability depend on network quality and server capacity. We continuously update the widget as new capabilities become available.

Author	@Abimbola Idowu @Joao Mazarelo

Author	@Abimbola Idowu @Joao Mazarelo

Unique Chat Widget Solution