The global object
When the script loads it creates window.GlimpzeWidget. All methods below live on that object. Because the script loads asynchronously, call methods from a user interaction or after the glimpze:triggers-ready event.
open(config?)
Opens the widget. Without an action it opens to whatever the widget's Opening behavior is set to in the dashboard — the welcome screen, straight to chat, or straight to a call (Settings > widget editor > Content > Opening behavior). Passing action overrides that for a single call. Pass prefillFields (or visitorInfo / customData) to pre-populate the visitor.
GlimpzeWidget.open();
GlimpzeWidget.open({ prefillFields: { email: 'jane@acme.com' } });
// Deep-link straight into a call:
GlimpzeWidget.open({ action: 'call' });
// Skip the camera/mic device-check screen and connect right away (pair with
// prefillFields so the visitor's required details aren't skipped):
GlimpzeWidget.open({
action: 'call',
callPreferences: { media: 'video' },
prefillFields: { name: 'Jane', email: 'jane@acme.com' },
skipSetup: true,
});| Option | Type | Description |
|---|---|---|
prefillFields | Record<string, string | number | boolean> | Field values keyed by field name. See Prefilling visitor details. |
visitorInfo | { name?: string; email?: string } | Lower-level identity prefill. |
customData | Record<string, unknown> | Lower-level custom-data prefill / visitor metadata. |
action | 'call' | Deep-link into a call once the widget opens, skipping the home screen. The visitor lands on the camera/mic device check before connecting (unless skipSetup). Omit to follow the widget's configured Opening behavior. |
callPreferences | { media: 'audio' | 'video' } | Call media when action: 'call'. Defaults to video. |
skipSetup | boolean | With action: 'call': false (default) shows the camera/mic device-check screen first; true skips that screen and connects right away. The device check still runs (invisibly) to acquire the mic/camera, so the screen is only skipped when the visitor's required fields are already satisfied — pair with prefillFields, or they're still asked for their details first. |
skipSetup still needs a user gesture the first time. Skipping the device-check screen does not remove the browser's camera/mic permission prompt — trigger open({ action: 'call', skipSetup: true }) from a click (not on page load) so the browser allows the prompt. Visitors who already granted access on your site connect silently; if access is blocked, the in-call “Allow access” banner lets them grant it and retry.getStatus().agents.free first and fall back to your booking page if you'd rather not queue them.close()
Closes the widget.
GlimpzeWidget.close();configure(config)
Sets defaults reused by every later open() / proactiveStart(). Accepts the same keys as open() (prefillFields, visitorInfo, customData). Returns { supportedKeys, unsupportedKeys }; unsupported keys are ignored with a console warning.
const result = GlimpzeWidget.configure({
prefillFields: { name: 'Jane', email: 'jane@acme.com' },
});
// result.supportedKeys -> ['visitorInfo']getFields()
Returns the widget's enabled form fields, in display order — so you can discover what's available to prefill. Internal columns are not exposed.
GlimpzeWidget.getFields();
// [
// { name: 'name', label: 'Name', type: 'text', required: true },
// { name: 'email', label: 'Email', type: 'email', required: true },
// { name: 'plan', label: 'Plan', type: 'single_select', required: false,
// options: ['Free', 'Pro', 'Enterprise'] },
// ]| Field | Type | Description |
|---|---|---|
name | string | The field name — the key you pass in prefillFields. |
label | string | Human label shown in the form. |
type | 'text' | 'email' | 'tel' | 'textarea' | 'single_select' | Input type. |
required | boolean | Whether the visitor must fill it. |
options | string[] | Present only for single_select. |
getStatus()
Resolves with the widget's current status. Capability tokens (conversation secrets, room URLs) are redacted from context.
const { state, isAvailable, agents, nextAvailableAt, context } = await GlimpzeWidget.getStatus();
// state: 'idle' | 'preInteractionChoice' | 'inCall' | ... (see Widget states)
// isAvailable: boolean — the team is REACHABLE: at least one agent is online.
// It stays true even when every online agent is already on a call (the visitor
// would queue). For "can a human take a call THIS INSTANT", use agents.free.
// agents: { online, free, busy } — live agent counts:
// online = agents present/working, free = present and NOT in a call,
// busy = present but currently in a call.
// nextAvailableAt: string | null — ISO time an agent is next expected free
// (from calendars), when nobody is free right now.
// All of these update live — see the AVAILABILITY_CHANGE event.on(eventName, handler) / off(eventName, handler)
Subscribe / unsubscribe to widget events. on returns an unsubscribe function. See Events & widget states for the full event list.
const unsubscribe = GlimpzeWidget.on(
GlimpzeWidget.events.AVAILABILITY_CHANGE,
({ isAvailable }) => toggleBanner(isAvailable),
);
// later: unsubscribe();proactiveStart(config?) / proactiveOpen(conversationId, secret, config?)
Advanced entry points for proactive outreach flows. Both accept the same prefill keys as open(). proactiveStart begins a fresh proactive conversation; proactiveOpen re-opens an existing one you already hold the capability for. Most integrations don't need these — prefer proactiveNotify for nudges.
proactiveNotify(payload)
Shows a proactive nudge above the launcher. Up to 3 nudges stack with a single clear-all control.
GlimpzeWidget.proactiveNotify({
id: 'pricing-30s',
message: 'Questions about pricing? We can help.',
ctaText: 'Open chat',
openBehavior: 'start_chat', // 'start_chat' | 'open_widget' | 'open_existing_conversation'
});