Guide AI

An AI-powered voice assistant component for React applications. Guide AI provides intelligent voice interactions, helping users navigate and complete tasks within your application.

Installation

npm install guideai-app
# or
yarn add guideai-app

Basic Usage

import React from 'react';
import ReactDOM from 'react-dom';
import GuideAI from 'guideai-app';

function App() {
	return (
		<div>
			<GuideAI
				authKey="your-access-key"
				workspace="your-workspace"
				React={React}
				ReactDOM={ReactDOM}
				position={{ bottom: '20px', right: '20px' }}
			/>
		</div>
	);
}

Props

| Prop | Type | Required | Description | | --------------------------------- | ---------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | authKey | string | Yes (customer embed) | Widget access key; not persisted by the package. Exchanged once for a JWT via POST /widget/session. Do not use React’s reserved key attribute — use this prop name. | | workspace | string | No | Default workspace slug for the first realtime session (single value). Forwarded on /initialize. Omit to use the customer default. When used with workspaces, pick a slug from that allowlist. | | workspaces | string or string[] | No | Catalog allowlist: limits which workspaces (and their workflows) end users can access. Omit for all customer workspaces. Comma-separated string ("sales,support") or array. Invalid/empty allowlist removes the widget and logs console.error. | | getUserInfo | function | No | Lets Guide AI know who is signed in on your app (see Signed-in users below). | | initializeUserId | string | No | Advanced: optional fixed user id when you manage identity yourself. | | adminConversationPersistenceKey | string | No | Optional stable key for transcript localStorage isolation. Omit to use a non-secret default from the page origin (same across SPA routes). Never use the raw access key here. | | React | React | Yes | React instance from your application | | ReactDOM | ReactDOM | Yes | ReactDOM instance from your application | | position | object | No | CSS positioning for the component (see below) | | launcher | object | No | Launcher presentation: floating mic circle (default) or a draggable side tab (see below) | | environment | string | No | API environment: 'production' (default), 'development', or 'local' | | transcript | object | No | Transcript panel configuration (see below) | | input | object | No | Text/voice input configuration (see below) | | theme | string | No | Built-in color theme preset id (see Themes below). Omit for the package default palette. |

You must pass authKey (customer integration). For authentication details, see AUTHENTICATION.md in this package.

Themes

Set the widget color palette with the theme prop. All presets are bundled in guideai-app; no extra scripts or CDN files are required.

<GuideAI
	authKey="your-access-key"
	workspace="your-workspace"
	React={React}
	ReactDOM={ReactDOM}
	theme="dark"
/>

Role-based catalog example:

<GuideAI
	authKey={accessKey}
	workspace="support"
	workspaces={user.role === 'admin' ? 'admin,support' : 'support'}
	React={React}
	ReactDOM={ReactDOM}
/>

Omit theme (or pass null) to use the default package palette (Studio blue).

Light themes

| theme id | Name | | -------------- | ----- | | light-ivory | Ivory | | light-snow | Snow | | light-sand | Sand | | light-mist | Mist | | light-mint | Mint | | light-sky | Sky | | light-coral | Coral | | light-rose | Rose | | light-plum | Plum | | light-slate | Slate |

Dark themes

| theme id | Name | | ----------------- | ------------ | | dark | Studio blue | | dark-muted-gray | Muted gray | | dark-midnight | Midnight | | dark-ocean | Ocean | | dark-forest | Forest | | dark-teal | Teal | | dark-violet | Violet | | dark-ember | Ember | | dark-carbon | Carbon | | dark-ruby | Ruby | | dark-graphite | Graphite |

TypeScript hosts can import GuideAIThemeId or GUIDEAI_THEME_IDS from guideai-app. Labels are also available on GUIDEAI_PRESET_THEMES.

Position Object

The position prop accepts an object with CSS positioning properties to control where the Guide AI button appears on your page, as well as z-index configuration for all Guide AI components:

position?: {
  // CSS positioning (applies to microphone button)
  top?: string;
  right?: string;
  bottom?: string;
  left?: string;
  marginTop?: string;
  marginRight?: string;
  marginBottom?: string;
  marginLeft?: string;
  transform?: string;

  // Z-index configuration (applies to all GuideAI components)
  // All component z-indexes are calculated from this base value
  zIndex?: number;  // Base z-index for all components (default: 1300)
                    // Onboarding modal will be set to zIndex + 1
}

Position Examples

Bottom-right corner:

<GuideAI
	authKey="your-access-key"
	React={React}
	ReactDOM={ReactDOM}
	position={{ bottom: '20px', right: '20px' }}
/>

Bottom-left corner:

<GuideAI
	authKey="your-access-key"
	React={React}
	ReactDOM={ReactDOM}
	position={{ bottom: '20px', left: '20px' }}
/>

Centered at bottom:

<GuideAI
	authKey="your-access-key"
	React={React}
	ReactDOM={ReactDOM}
	position={{
		bottom: '20px',
		left: '50%',
		transform: 'translateX(-50%)',
	}}
/>

Top-right corner:

<GuideAI
	authKey="your-access-key"
	React={React}
	ReactDOM={ReactDOM}
	position={{ top: '20px', right: '20px' }}
/>

Launcher Object

The launcher prop selects how the idle Guide AI control is presented:

launcher?: {
  variant?: 'mic' | 'tab'; // 'mic' (default): floating circle. 'tab': edge-docked side tab.
  side?: 'left' | 'right'; // Tab variant only — screen edge to dock to (default: 'right')
}

The tab behaves exactly like the mic circle (click to start/end a conversation, same status colors and idle prompt animations), but it sits flush against the screen edge and can be dragged up and down that edge. The dragged offset is persisted in localStorage per conversation key, so the tab stays where the user left it. With variant: 'tab', the CSS placement properties of position are ignored (position.zIndex still applies), and the transcript defaults to opening on the same side as the tab.

Right-edge tab:

<GuideAI
	authKey="your-access-key"
	React={React}
	ReactDOM={ReactDOM}
	launcher={{ variant: 'tab' }}
/>

Left-edge tab:

<GuideAI
	authKey="your-access-key"
	React={React}
	ReactDOM={ReactDOM}
	launcher={{ variant: 'tab', side: 'left' }}
/>

Transcript Object

The transcript prop controls the conversation transcript panel:

transcript?: {
  enabled?: boolean;   // Whether to show transcript (default: true)
  position?: 'right' | 'left';  // Which side of the button (default: 'right')
}

Transcript Examples

Disable transcript panel:

<GuideAI
	authKey="your-access-key"
	React={React}
	ReactDOM={ReactDOM}
	transcript={{ enabled: false }}
/>

Show transcript on the left:

<GuideAI
	authKey="your-access-key"
	React={React}
	ReactDOM={ReactDOM}
	transcript={{ position: 'left' }}
/>

Input Object

The input prop configures text and voice input options:

input?: {
  enableTextInput?: boolean;   // Show text input option (default: true)
  showInputToggle?: boolean;   // Show voice/text toggle button (default: true)
  defaultMode?: 'voice' | 'text';  // Default input mode (default: 'voice')
  placeholder?: string;        // Placeholder text for text input (default: 'Type your message...')
}

Input Examples

Text-only mode:

<GuideAI
	authKey="your-access-key"
	React={React}
	ReactDOM={ReactDOM}
	input={{ defaultMode: 'text', showInputToggle: false }}
/>

Disable text input (voice only):

<GuideAI
	authKey="your-access-key"
	React={React}
	ReactDOM={ReactDOM}
	input={{ enableTextInput: false }}
/>

Custom placeholder text:

<GuideAI
	authKey="your-access-key"
	React={React}
	ReactDOM={ReactDOM}
	input={{ placeholder: 'Ask me anything...' }}
/>

Customizing Colors

Guide AI allows you to customize the microphone button color to match your application's branding. You can override the default color using CSS variables in your own stylesheet.

Available CSS Variable

| Variable | Default | Description | | --------------------- | --------- | --------------------- | | --guideai-mic-color | #0000FF | Microphone icon color |

Customization Example

Add this style to your application's CSS file to override the default color:

/* Match your brand color */
.guideai-icon-wrapper {
	--guideai-mic-color: #6366f1; /* Your primary brand color */
}

Brand Matching Examples

Purple/Indigo Theme:

.guideai-icon-wrapper {
	--guideai-mic-color: #8b5cf6;
}

Green/Eco Theme:

.guideai-icon-wrapper {
	--guideai-mic-color: #059669;
}

Dark/Monochrome Theme:

.guideai-icon-wrapper {
	--guideai-mic-color: #ffffff;
}

Z-Index Configuration

If Guide AI components conflict with modals or other overlays on your site, you can customize the z-index value for all components using a single zIndex parameter. All GuideAI components will use this base value, with the onboarding modal appearing one level above (zIndex + 1).

Custom z-index value:

<GuideAI
	authKey="your-access-key"
	React={React}
	ReactDOM={ReactDOM}
	position={{
		bottom: '20px',
		right: '20px',
		zIndex: 5000, // All components use 5000, onboarding modal uses 5001
	}}
/>

Positioning with z-index configuration:

<GuideAI
	authKey="your-access-key"
	React={React}
	ReactDOM={ReactDOM}
	position={{
		bottom: '40px',
		right: '40px',
		zIndex: 2000, // Set base z-index to 2000
	}}
/>

Note: You only need to specify a z-index value if the default (1300) conflicts with your existing UI. The onboarding modal will automatically appear at zIndex + 1 to stay above other GuideAI components.

Complete Example

import React from 'react';
import ReactDOM from 'react-dom';
import GuideAI from 'guideai-app';

function App() {
	return (
		<div className="app">
			<h1>My Application</h1>

			<GuideAI
				authKey="your-access-key"
				workspace="your-workspace"
				environment="production"
				React={React}
				ReactDOM={ReactDOM}
				position={{ bottom: '40px', right: '40px' }}
				transcript={{ position: 'right' }}
				input={{ defaultMode: 'voice' }}
			/>
		</div>
	);
}

export default App;

Signed-in users (getUserInfo)

If people can sign in on your site, pass getUserInfo so Guide AI can treat them as the same person across visits and tie voice sessions to their account.

• Your function should return something like { username: user.email } when someone is logged in. Use whatever stable string identifies them (often an email).
• When no one is logged in yet, you can return null (or omit username) so Guide AI keeps a normal anonymous experience without rotating identities on every check.
• After login or logout, you can notify Guide AI right away by dispatching GUIDEAI_HOST_USERINFO_REFRESH_EVENT on window (import it from guideai-app alongside the component).

Wrap getUserInfo in useCallback so it doesn’t change every render.

More detail for integrations lives in docs/WIDGET_USER_IDENTITY.md and AUTHENTICATION.md.

Example

import React, { useCallback } from 'react';
import ReactDOM from 'react-dom';
import GuideAI, { GUIDEAI_HOST_USERINFO_REFRESH_EVENT } from 'guideai-app';

function App({ currentUser }) {
	const getUserInfo = useCallback(() => {
		if (!currentUser) return null;

		return {
			username: currentUser.email,
			displayName: currentUser.name,
		};
	}, [currentUser]);

	// Optional: after your auth state changes, run:
	// window.dispatchEvent(new CustomEvent(GUIDEAI_HOST_USERINFO_REFRESH_EVENT));

	return (
		<GuideAI
			authKey="your-access-key"
			workspace="your-workspace"
			React={React}
			ReactDOM={ReactDOM}
			getUserInfo={getUserInfo}
			position={{ bottom: '20px', right: '20px' }}
		/>
	);
}

Getting Your Access Key

To use Guide AI, you'll need an access key and workspace slug. Contact the Guide AI team to get set up.

Support

For questions, issues, or feature requests, please contact the Guide AI team or visit our documentation.