Widget Integration Guide

Quick Start

Add the GuidMe widget to your website with a single script tag:

<script 
  src="https://widget.guidme.ai/v1/loader.js" 
  data-key="gm_live_xxxxxxxxxxxx"
  data-app-id="11111111-1111-4111-8111-111111111111"
></script>

That's it! The widget will appear as a floating button in the bottom-right corner.

The privacy boundary still uses this single script tag and requires no app-specific masking code. If your application creates closed shadow roots on standard HTML elements, place the tag before the application's main bundle so the loader can retain a local reference to them.

Configuration Options

Basic Configuration (Data Attributes)

<script 
  src="https://widget.guidme.ai/v1/loader.js"
  data-key="gm_live_xxxxxxxxxxxx"
  data-app-id="11111111-1111-4111-8111-111111111111"
  data-api-url="https://api.guidme.ai"
  data-position="bottom-right"
  data-theme="dark"
  data-locale="auto"
  data-default-input="voice"
  data-default-output="voice"
  data-allow-text-input="true"
  data-allow-text-output="true"
  data-enable-screen-share="true"
  data-operational-telemetry="false"
  data-accent-color="#537FE7"
></script>

Configuration Reference

Attribute	Type	Default	Description
`data-key`	string	required	Publishable widget key (starts with `gm_live_`)
`data-app-id`	string	required	App/project identifier bound to this embed
`data-api-url`	string	environment default	Environment-bound API URL; cross-environment overrides are rejected
`data-position`	string	`bottom-right`	Widget position: `bottom-right`, `bottom-left`, `top-right`, `top-left`
`data-theme`	string	`dark`	Theme: `light`, `dark`, `auto`
`data-locale`	string	`auto`	Widget language: `auto`, `en`, `es`, `fr`, `de`, `it`, `ja`, `ko`, `pt`, `zh`. `auto` follows the host page language and falls back to English when the page language is missing or unsupported.
`data-button-size`	string	`medium`	Button size: `small` (40px), `medium` (48px), `large` (56px)
`data-default-input`	string	`voice`	Default input mode: `voice`, `text`
`data-default-output`	string	`voice`	Default output mode: `voice`, `text`
`data-allow-text-input`	boolean	`true`	Allow users to switch to text input
`data-allow-text-output`	boolean	`true`	Allow users to switch to text output
`data-enable-screen-share`	boolean	`true`	Show the user-controlled screen-sharing option
`data-operational-telemetry`	boolean	`false`	Opt in to GuidMe operational error and performance telemetry for this embed
`data-show-transcript`	boolean	`false`	Show live transcript with voice
`data-accent-color`	string	`#537FE7`	Brand color (hex)
`data-auto-open`	boolean	`false`	Open widget on page load
`data-greeting`	string	-	Custom greeting message
`data-z-index`	number	`999999`	CSS z-index for widget
`data-container`	string	-	CSS selector for custom container element

Programmatic API

Initialization

window.GuidMe.init({
  apiKey: 'gm_live_xxxxxxxxxxxx',
  appId: '11111111-1111-4111-8111-111111111111',
  apiUrl: 'https://api.guidme.ai',
  position: 'bottom-right',
  theme: 'dark',
  locale: 'auto',
  defaultInputMode: 'voice',
  defaultOutputMode: 'voice',
  allowTextInput: true,
  allowTextOutput: true,
  enableScreenShare: true,
  operationalTelemetry: false,
  accentColor: '#537FE7',
  
  onReady: () => console.log('Widget is ready'),
  onSessionStart: (session) => {},
  onSessionEnd: (session) => {},
  onMessage: (message) => {},
  onError: (error) => console.error('Widget error:', error)
});

Control Methods

window.GuidMe.open();
window.GuidMe.close();
window.GuidMe.toggle();
window.GuidMe.setInputMode('text');
window.GuidMe.setOutputMode('voice');
window.GuidMe.endSession();
window.GuidMe.destroy();

Get State

const isOpen = window.GuidMe.isOpen();
const session = window.GuidMe.getSession();
// { id: string, status: string, duration: number } | null
const config = window.GuidMe.getConfig();

Widget appearance and preview

The embedded widget uses a 384 × 720 full shell and a 256 × 256 compact shell. It is always an overlay and never changes the host page layout. Opening the launcher starts the voice-first session; minimizing preserves the session and active media, closing pauses media but keeps the session resumable, and End session terminates it.

Dashboard > Widget previews the production Preact shell directly. Its controls cover Voice, Chat, Compact, With response, Minimized, Mute mic, and Silent AI. Pro and Enterprise customers can edit launcher text, alignment, page spacing, drag behavior, the assistant avatar, and the voice visual. The launcher image, avatar, and voice visual accept JPEG, PNG, WebP, or AVIF files up to 5 MB. GuidMe validates and crops each upload, publishes a managed WebP in a project-bound slot, and removes replaced objects.

The production shell uses the GuidMe brandmark. Unless the server-issued plan configuration disables branding, Powered by GuidMe links to https://www.guidme.ai/ in a new tab.

Permissions

The widget will request:

Microphone: Requested when a voice-configured launcher opens, mutable from the widget controls, and stopped whenever the panel is closed
Protected Screen Sharing: Optional and off until the user explicitly selects this application's browser tab. GuidMe masks detected sensitive areas on the device, leaves non-sensitive text and elements visible for useful context, and holds the first exact protected frame for confirmation. Nothing is sent before that confirmation; afterward, every frame is sanitized again and only protected JPEGs are sent to Google Gemini. Declining, cancelling, or stopping screen sharing leaves voice and text support available; the widget never re-prompts automatically.

The microphone prompt appears when the user opens a voice-configured launcher. The screen chooser appears only after the user selects Share protected screen.

An app administrator controls the profile for each project under Widget > Rules > Screen privacy. Balanced (recommended) selectively masks detected sensitive content and preserves ordinary context. Strict also masks every visible form control and editable field. The portal warns that Strict can hide controls, text, or larger page areas, so guidance may be less specific or require more clarification. The embed tag cannot select or weaken this server-issued profile.

Security

The gm_live_ widget key is publishable and visible to visitors. Never expose a tenant admin key, platform credential, or other secret in the client.
Your domain must be in the app's allowed origins in the dashboard.
For a strict host-page CSP, allow script-src https://widget.guidme.ai, frame-src https://widget.guidme.ai, and connect-src https://api.guidme.ai. The iframe ships its own restricted CSP.
The loader delegates microphone to the iframe and delegates display-capture only when screen sharing is enabled. The browser still asks the end user for permission.
Operational Sentry/OpenTelemetry export is disabled by default. Set data-operational-telemetry="true" only after your organization has approved that processing. This flag does not disable the API calls required to run a requested session.

Version Pinning and Integrity

/v1/loader.js is a revalidated channel alias. The iframe alias is not stored in browser or CDN caches, and the loader couples it to the exact privacy build. https://widget.guidme.ai/v1/integrity.json publishes its SHA-384 integrity value and a content-hashed loader path under /v1/assets/, which is served with immutable caching. Resolve the manifest during your deployment and pin the returned path and integrity value when your release process requires a fixed artifact. Do not fetch the manifest in the end user's browser on every page load.

Public widget artifacts do not include source maps.

Support

Dashboard: https://app.guidme.ai
Email: support@guidme.ai