> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nexudus.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Standalone AI Chat Widget
> Embed the Nexudus AI assistant on any website with a single script tag — no framework or login required.
The **Standalone AI Chat Widget** lets you embed the Nexudus AI assistant on any external website — your company homepage, a landing page, a blog, or any third-party site — with a single `
```
Replace `myworkspace` with your actual Domain value from the step above.
### Step 3: Test the widget
Open your website in a browser. You should see a floating chat button in the bottom corner. Click it to open the chat modal and send a test message.
If you don't see the button, check your browser console for errors. The most common issue is a missing or incorrect `data-api-base` value.
## Configuration parameters
All configuration is passed through `data-*` attributes on the `
```
**Auto-open on page load with a greeting:**
```html theme={null}
```
**Dark theme with custom portal URL:**
```html theme={null}
```
## Controlling the widget with JavaScript
After the widget loads, it exposes a `window.nxAiChat` object that lets you control it programmatically from your website's JavaScript.
### Available methods
| Method | Description |
| -------------------------- | ---------------------------------------------- |
| `nxAiChat.open()` | Open the chat modal |
| `nxAiChat.close()` | Close the chat modal |
| `nxAiChat.newSession()` | Start a new conversation (clears chat history) |
| `nxAiChat.destroy()` | Remove the widget completely from the page |
| `nxAiChat.setToken(token)` | Set or update the authentication token |
### Examples
**Open the chat when a user clicks a button on your page:**
```html theme={null}
```
**Close the chat after a certain action:**
```javascript theme={null}
// Close the widget after the user completes a form
document.getElementById('contact-form').addEventListener('submit', () => {
window.nxAiChat.close();
});
```
**Start a fresh conversation:**
```javascript theme={null}
// Reset the chat when navigating to a new section
window.nxAiChat.newSession();
```
**Remove the widget entirely (e.g. on logout):**
```javascript theme={null}
// Destroy the widget if the user logs out
window.nxAiChat.destroy();
```
**Set an authentication token after user login:**
```javascript theme={null}
// After your user authenticates on your website, pass their token to the widget
// This enables authenticated features like inline booking confirmation
window.nxAiChat.setToken('user-auth-token-here');
```
The `setToken` method is only useful if your website has its own authentication system and you want to pass the user's session to the Nexudus API. For most use cases, the widget works fine without a token.
## Listening to widget events
The widget emits events during its lifecycle. You can subscribe to these events using `nxAiChat.on()` and unsubscribe with `nxAiChat.off()`.
### Available events
| Event | When it fires | Payload |
| ------------------- | ----------------------------- | ------------------------------------------- |
| `open` | When the chat modal opens | — |
| `close` | When the chat modal closes | — |
| `message:sent` | When the user sends a message | `{ prompt: string }` |
| `message:received` | When the AI responds | `{ response: string, tools?: unknown[] }` |
| `tool:displayed` | When a tool card is shown | `{ toolName: string, toolData: unknown }` |
| `booking:confirmed` | When a booking is confirmed | `{ bookingId: string, resourceId: string }` |
| `error` | When an API error occurs | `{ code: number, message: string }` |
| `session:new` | When a new session starts | — |
### Examples
**Track when a booking is confirmed:**
```javascript theme={null}
window.nxAiChat.on('booking:confirmed', (data) => {
console.log('Booking confirmed:', data.bookingId);
// Send to your analytics platform
gtag('event', 'booking_confirmed', {
booking_id: data.bookingId,
resource_id: data.resourceId
});
});
```
**Log all AI responses for debugging:**
```javascript theme={null}
window.nxAiChat.on('message:received', (data) => {
console.log('AI response:', data.response);
if (data.tools && data.tools.length > 0) {
console.log('Tool cards:', data.tools);
}
});
```
**Track chat open/close events:**
```javascript theme={null}
window.nxAiChat.on('open', () => {
console.log('Chat opened');
});
window.nxAiChat.on('close', () => {
console.log('Chat closed');
});
```
**Handle errors gracefully:**
```javascript theme={null}
window.nxAiChat.on('error', (data) => {
console.error('Widget error:', data.code, data.message);
// Notify your error tracking service
Sentry.captureException(new Error(data.message), {
tags: { widget_error_code: data.code }
});
});
```
**Unsubscribe from an event:**
```javascript theme={null}
function onMessageSent(data) {
console.log('User sent:', data.prompt);
}
// Subscribe
window.nxAiChat.on('message:sent', onMessageSent);
// Later, unsubscribe
window.nxAiChat.off('message:sent', onMessageSent);
```
## Style isolation
The widget uses **Shadow DOM** to mount its UI, which means:
* Your website's CSS does not affect the widget's appearance
* The widget's CSS does not leak into your website
* The widget inherits the host page's font family and base font size for a cohesive look
Colors like the button background and text are controlled via the `data-primary-color` and `data-text-color` attributes. The widget adapts to these values using CSS custom properties.
If you need to override additional styles, you can target the shadow host element (`#nxai-root`) and pass custom properties into the shadow root. However, this is rarely necessary — the built-in configuration options cover most use cases.
## Session persistence
The widget stores conversation history in the browser's `localStorage`, keyed by your `data-api-base` URL. This means:
* If a visitor closes the chat and returns later, their conversation history is restored
* Sessions expire after **7 days** — older conversations are automatically discarded
* The "New chat" button in the chat header clears the session and starts fresh
## Geolocation
When `data-geolocation="true"` (the default), the widget will request the visitor's browser location on their first message. This allows the AI to calculate distances when presenting rooms, locations, and offices.
If the visitor denies the location permission, the widget continues to work normally — distance information is simply omitted from the AI's responses.
## Accessibility
The widget follows accessibility best practices:
* All interactive elements have proper ARIA roles and labels
* Focus is trapped inside the modal when it's open
* **Escape** closes the modal, **Enter** sends a message
* An `aria-live="polite"` region announces new AI messages to screen readers
* The widget respects `prefers-reduced-motion` — the typewriter animation is skipped for users who prefer reduced motion
## Size and performance
* The minified bundle is approximately **15–25KB gzipped**
* The widget loads asynchronously and does not block page rendering
* No external dependencies — everything is contained in a single file
* The AI API is only called when the user sends a message
## Troubleshooting
| Problem | Solution |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Widget button doesn't appear | Check that `data-api-base` is set correctly. Open browser console for errors. |
| Chat shows "API error" | Verify your `data-api-base` URL is accessible. Check that AI is enabled in your Nexudus account. |
| Widget styles look broken | Ensure the script tag is loaded after the page content (before ``). |
| Multiple widgets on one page | Only one widget instance is allowed per page. The widget is idempotent — adding the script tag twice won't create duplicates. |
| Chat doesn't open on load | Make sure `data-open-on-load="true"` (as a string, not a boolean). |
| Tool cards show broken links | Set `data-portal-url` to your correct portal URL. |
## Comparison with portal chat
| Feature | Standalone Widget | Portal Chat |
| -------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| Where it works | Any external website | Inside the members portal only |
| How to add | Single `