Widget Embedding

The Gnosari chat widget allows you to embed AI agents on any website with just a few lines of JavaScript. The widget creates an iframe-based chat interface that is isolated from your page's styles and scripts.

Quick Start

The fastest way to add a chat widget to your website:

<!-- Configure the widget -->
<script>
  window.gnosariConfig = {
    agentId: 'your-agent-identifier',
    apiUrl: 'https://your-domain.com'
  };
</script>

<!-- Load the widget script -->
<script src="https://your-domain.com/gnosari-chat-widget-advanced.js"></script>

Place this code just before the closing </body> tag on your page.

Display Modes

The widget supports multiple display modes to fit different use cases:

Bubble Mode (Default)

Floating chat button that opens a chat window when clicked.

window.gnosariConfig = {
  agentId: 'support-bot',
  displayMode: 'bubble',
  position: 'bottom-right'
};

Features:

• Minimally intrusive
• Opens on click
• Floating button follows scroll
• Positions: bottom-right, bottom-left, top-right, top-left

Sidebar Mode

Slide-in panel that overlays the page content.

window.gnosariConfig = {
  agentId: 'support-bot',
  displayMode: 'sidebar',
  sidebarPosition: 'right',
  sidebarWidth: '420px'
};

Features:

• Slides in from left or right
• Overlays page content (doesn't push)
• Backdrop dims page when open
• Customizable width

Sidebar Push Mode

Sidebar that pushes page content aside when opened.

window.gnosariConfig = {
  agentId: 'support-bot',
  displayMode: 'sidebar-push',
  sidebarPosition: 'right',
  sidebarWidth: '420px'
};

Features:

• Pushes page content aside
• Page remains fully visible
• Smooth transition animation
• Best for wide layouts

Drawer Mode

Bottom drawer that slides up from the bottom of the screen.

window.gnosariConfig = {
  agentId: 'support-bot',
  displayMode: 'drawer',
  drawerHeight: '60vh'
};

Features:

• Slides up from bottom
• Mobile-friendly
• Customizable height
• Good for full-width layouts

Configuration Options

Complete list of configuration options:

Connection Options

Option	Type	Required	Description
agentId	string	Yes*	Agent identifier (not numeric ID)
teamId	number	Yes*	Team ID (alternative to agentId)
apiUrl	string	Yes	Your Gnosari instance URL
password	string	No	Password for password-protected agents

*Either agentId or teamId is required.

Display Options

Option	Type	Default	Description
displayMode	string	'bubble'	Display mode: bubble, sidebar, sidebar-push, drawer
position	string	'bottom-right'	Bubble position (bubble mode only)
sidebarPosition	string	'right'	Sidebar position: left or right
sidebarWidth	string	'420px'	Sidebar width (sidebar modes)
drawerHeight	string	'60vh'	Drawer height (drawer mode)

Appearance Options

Option	Type	Default	Description
primaryColor	string	'#667eea'	Brand color (hex format)
theme	string	'auto'	Color scheme: light, dark, auto
disableTheme	boolean	false	Ignore agent's custom theme

Behavior Options

Option	Type	Default	Description
autoOpen	boolean	false	Auto-open widget on page load
showAfterSeconds	number	null	Delay showing widget (seconds)

Advanced Options

Option	Type	Default	Description
debug	boolean	false	Enable console logging

JavaScript API

After the widget loads, you can control it programmatically via the global GnosariChatAdvanced object.

Methods

open()

Open the chat widget.

window.GnosariChatAdvanced.open();

close()

Close the chat widget.

window.GnosariChatAdvanced.close();

toggle()

Toggle the widget open/closed.

window.GnosariChatAdvanced.toggle();

sendMessage(message)

Send a message programmatically.

window.GnosariChatAdvanced.sendMessage('Hello from the website!');

Parameters:

• message (string): The message to send

destroy()

Remove the widget from the page completely.

window.GnosariChatAdvanced.destroy();

Use this when navigating to a new page in single-page applications.

getState()

Get the current widget state.

const state = window.GnosariChatAdvanced.getState();
console.log(state);
// { isOpen: true, sessionId: 'sess_abc123', ... }

Returns:

• isOpen (boolean): Whether widget is currently open
• sessionId (string): Current chat session ID
• agentId (string): Connected agent identifier

Events

Listen for widget events using standard DOM event listeners:

gnosari-chat-ready

Fired when the widget is fully initialized and ready to use.

window.addEventListener('gnosari-chat-ready', (event) => {
  console.log('Widget ready!', event.detail);
});

Event detail:

• agentId (string): Connected agent identifier

gnosari-chat-open

Fired when the widget opens.

window.addEventListener('gnosari-chat-open', (event) => {
  console.log('Widget opened');
  // Track in analytics, show tooltips, etc.
});

gnosari-chat-close

Fired when the widget closes.

window.addEventListener('gnosari-chat-close', (event) => {
  console.log('Widget closed');
});

gnosari-chat-new-message

Fired when a new message is received from the agent.

window.addEventListener('gnosari-chat-new-message', (event) => {
  console.log('New message:', event.detail.message);
  // Show notification, play sound, etc.
});

Event detail:

• message (string): The message content
• role (string): 'assistant' or 'user'

Configuration via URL Parameters

You can override config options via URL query parameters on the embed page:

<script>
  window.gnosariConfig = {
    agentId: 'support-bot',
    // URL params will override these
  };
</script>

Supported URL parameters:

Parameter	Type	Example
theme	string	?theme=dark
password	string	?password=secret123
session_id	string	?session_id=sess_abc
autoMessage	string	?autoMessage=Hello!
disableTheme	boolean	?disableTheme=true
channel	string	?channel=WIDGET

channel is auto-set by the widget SDK scripts (widget.js and gnosari-chat-widget-advanced.js both stamp it on the generated embed URL) — you don't need to set it yourself.

Example embed URL:

https://your-domain.com/embed/agent/support-bot?theme=dark&autoMessage=Hi%20there!

Using the Widget Configurator

The easiest way to generate embed code is through the UI:

1. Navigate to /gnosaris/{id}/widget (or /teams/{id}/widget)
2. Configure display mode, colors, and behavior
3. Preview changes in real-time
4. Click Copy Embed Code when satisfied
5. Paste the code into your website

The configurator generates the exact JavaScript needed with all your customizations.

Agent Requirements

For the widget to work, your agent must be:

• Access Level: Set to Public or Password Protected (not Private)
• Identifier: Must have a unique identifier (auto-generated if empty)

To check/update agent settings:

1. Go to /gnosaris/{id}/edit
2. Navigate to Publication section
3. Set Access Level to Public or Password Protected
4. Save changes

Common Patterns

Customer Support Widget

window.gnosariConfig = {
  agentId: 'support-bot',
  apiUrl: 'https://chat.yourcompany.com',
  displayMode: 'bubble',
  position: 'bottom-right',
  primaryColor: '#10b981', // Your brand color
  theme: 'auto',
  autoOpen: false
};

Sales Assistant (Proactive)

window.gnosariConfig = {
  agentId: 'sales-bot',
  apiUrl: 'https://chat.yourcompany.com',
  displayMode: 'sidebar',
  sidebarPosition: 'right',
  primaryColor: '#6366f1',
  autoOpen: true,  // Open automatically
  showAfterSeconds: 3  // After 3 seconds on page
};

Help Documentation Chat

window.gnosariConfig = {
  agentId: 'docs-helper',
  apiUrl: 'https://chat.yourcompany.com',
  displayMode: 'drawer',
  drawerHeight: '50vh',
  primaryColor: '#8b5cf6',
  theme: 'light'
};

Internal Tools (Password Protected)

window.gnosariConfig = {
  agentId: 'internal-bot',
  apiUrl: 'https://chat.yourcompany.com',
  password: 'team-secret-123',  // Skip password prompt
  displayMode: 'sidebar-push',
  theme: 'dark'
};

Mobile Optimization

The widget is fully responsive and optimized for mobile devices:

• Touch-friendly: Large tap targets, swipe gestures
• Viewport-aware: Adjusts to screen size automatically
• Performance: Lazy-loads iframe, minimal impact on page load
• Gestures: Swipe down to close (drawer mode)

No additional configuration needed for mobile support.

Accessibility

The widget follows WCAG 2.1 AA accessibility standards:

• Keyboard navigation: Full support for Tab, Enter, Escape
• Screen readers: Proper ARIA labels and landmarks
• Focus management: Traps focus when open, restores on close
• Color contrast: Meets minimum contrast ratios
• Focus indicators: Clear visual focus rings

Troubleshooting

Widget Not Showing

1. Check agent access level: Must be Public or Password Protected
2. Verify agentId: Use the identifier (string), not numeric ID
3. Check browser console: Look for JavaScript errors
4. Test API URL: Ensure apiUrl is correct and accessible

Widget Shows But Won't Connect

1. Password required: Add password option for password-protected agents
2. CORS issues: Ensure your domain is allowed (check browser console)
3. Agent disabled: Verify agent is not disabled in Gnosari UI

Widget Appears Behind Other Elements

Increase the z-index by customizing the widget CSS or ensuring your page elements don't have excessively high z-index values. Contact support if issues persist.

Styling Conflicts

The widget uses an iframe for complete style isolation. If you see styling issues, it's likely:

1. Theme conflict: Try setting disableTheme: true
2. Color issues: Customize primaryColor to match your site
3. Parent page styles: Iframe prevents most conflicts, but check for !important rules

Performance

Widget performance characteristics:

• Load time: ~200ms initial load (iframe-based)
• Bundle size: ~50KB (compressed widget script)
• Memory: ~5-10MB (includes chat UI and Vue runtime)
• Network: Minimal - uses WebSocket for real-time messaging

Optimization tips:

• Load script at end of <body> (non-blocking)
• Use autoOpen: false to defer iframe creation
• Consider lazy-loading for below-the-fold pages