Guide AIv0.5.4-7

An AI-powered voice assistant component for any web page. Guide AI provides intelligent voice interactions, helping users navigate and complete tasks within your application. This page documents the script-tag install — no bundler, no npm required.

Install

Drop two script blocks anywhere in your HTML — usually right before </body>. The bundle is self-contained: React, ReactDOM, and the Guide AI widget are all inside.

<script src="https://cdn.getguide.ai/guideai/0.5.4-7/GuideAI.standalone.js"></script>
<script>
  GuideAI.embed({
    authKey: 'your-access-key',
    workspace: 'your-workspace',
    position: { bottom: '20px', right: '20px' },
  });
</script>

Props

The argument to GuideAI.embed() is an options object. Every prop the Guide AI React component accepts is supported here, plus two embed-only keys (target and useShadowDom) covered at the bottom.

Position

The position prop controls where the microphone button sits, and provides a base z-index for every Guide AI component.

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 base for all Guide AI components (default: 1300)
  // Onboarding modal is set to zIndex + 1.
  zIndex?: number;
}

Bottom-right corner

GuideAI.embed({
  authKey: 'your-access-key',
  position: { bottom: '20px', right: '20px' },
});

Bottom-left corner

GuideAI.embed({
  authKey: 'your-access-key',
  position: { bottom: '20px', left: '20px' },
});

Centered at bottom

GuideAI.embed({
  authKey: 'your-access-key',
  position: {
    bottom: '20px',
    left: '50%',
    transform: 'translateX(-50%)',
  },
});

Top-right corner

GuideAI.embed({
  authKey: 'your-access-key',
  position: { top: '20px', right: '20px' },
});

Transcript

Controls the conversation transcript panel.

transcript?: {
  enabled?: boolean;            // default: true
  position?: 'right' | 'left';  // default: 'right'
}

Disable transcript

GuideAI.embed({
  authKey: 'your-access-key',
  transcript: { enabled: false },
});

Transcript on the left

GuideAI.embed({
  authKey: 'your-access-key',
  transcript: { position: 'left' },
});

Input

Configures text and voice input.

input?: {
  enableTextInput?: boolean;        // default: true
  showInputToggle?: boolean;        // default: true
  defaultMode?: 'voice' | 'text';   // default: 'voice'
  placeholder?: string;             // default: 'Type your message...'
}

Text-only mode

GuideAI.embed({
  authKey: 'your-access-key',
  input: { defaultMode: 'text', showInputToggle: false },
});

Voice only

GuideAI.embed({
  authKey: 'your-access-key',
  input: { enableTextInput: false },
});

Custom placeholder

GuideAI.embed({
  authKey: 'your-access-key',
  input: { placeholder: 'Ask me anything...' },
});

Customizing colors

Override the microphone color with a CSS variable on the page:

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

Brand examples

/* Purple / Indigo */
.guideai-icon-wrapper { --guideai-mic-color: #8b5cf6; }

/* Green / Eco */
.guideai-icon-wrapper { --guideai-mic-color: #059669; }

/* Dark / Monochrome */
.guideai-icon-wrapper { --guideai-mic-color: #ffffff; }

Z-index

If Guide AI components conflict with modals or other overlays, set a single zIndex on position. All components use that value; the onboarding modal sits at zIndex + 1.

GuideAI.embed({
  authKey: 'your-access-key',
  position: {
    bottom: '20px',
    right: '20px',
    zIndex: 5000,
  },
});

Complete example

<script src="https://cdn.getguide.ai/guideai/0.5.4-7/GuideAI.standalone.js"></script>
<script>
  GuideAI.embed({
    authKey: 'your-access-key',
    workspace: 'your-workspace',
    environment: 'production',
    position: { bottom: '40px', right: '40px' },
    transcript: { position: 'right' },
    input: { defaultMode: 'voice' },
  });
</script>

Signed-in users

If people 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.

• 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, return null (or omit username) so Guide AI keeps a normal anonymous experience without rotating identities on every check.
• After login or logout, dispatch GUIDEAI_HOST_USERINFO_REFRESH on window to notify Guide AI right away.

Example

<script src="https://cdn.getguide.ai/guideai/0.5.4-7/GuideAI.standalone.js"></script>
<script>
  // Defined once — same reference every time.
  function getUserInfo() {
    if (!window.currentUser) return null;
    return {
      username: window.currentUser.email,
      displayName: window.currentUser.name,
    };
  }

  GuideAI.embed({
    authKey: 'your-access-key',
    workspace: 'your-workspace',
    getUserInfo: getUserInfo,
    position: { bottom: '20px', right: '20px' },
  });

  // Later — after login or logout, notify Guide AI:
  // window.dispatchEvent(new CustomEvent('GUIDEAI_HOST_USERINFO_REFRESH'));
</script>

Embed-only options

Two keys are specific to the standalone (the React component doesn't accept them):

• target — CSS selector or HTMLElement to mount into. Omit to have the embed append a fresh <div> to document.body.
• useShadowDom — reserved. Currently warns and renders normally. A future build will mount inside a Shadow DOM with cloned styles for full isolation.

Embed handle

GuideAI.embed() returns a handle for managing the widget after mount:

const handle = GuideAI.embed({ authKey: '...', workspace: '...' });

handle.container;          // the DOM node the widget is rendered into
handle.update({ ... });    // re-render with merged props
handle.unmount();          // tear down the widget

Getting your access key

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

Support

For questions, issues, or feature requests, contact the Guide AI team.

Last updated 2026-06-10 23:36 UTC. Pinned to v0.5.4-7.