SDK reference

The browser SDK is the typed control surface the runtime exposes on window.Puntego. Use it to point at elements, run guided tours, send messages, register page targets and actions, and listen for what the guide does. This page is the exact signature reference, generated from the published types. Every signature below comes from @puntego/embed. Importing the package augments the global Window, so window.Puntego is fully typed with no extra setup:

import '@puntego/embed';
// window.Puntego is now typed as PuntegoApi

Prefer explicit imports? The same types are available as named exports from @puntego/embed/types, and the React hooks re-export the ones you need.

The npm packages (@puntego/embed, @puntego/react) are rolling out to the registry and may still 404 until they are published. The single boot script install works today — see Install.

Get a reference to the SDK

The runtime boots from the page’s boot script and assigns window.Puntego once it is ready. From plain JavaScript you can read it directly, but it is undefined until boot completes. The cleanest way to wait is the loader helper.

import { loadPuntego, whenPuntegoReady } from '@puntego/embed/loader';

// Inject the boot script imperatively (no-op on the server, deduped per page).
loadPuntego({
  appId: 'gp_your_app_id',
  apiUrl: 'https://worker.puntego.com',
});

const sdk = await whenPuntegoReady(); // PuntegoApi | null (null on timeout)
sdk?.point('#checkout-button', 'Finish here');

// If the boot script tag is already on the page, read the global once it exists.
const sdk = window.Puntego;
sdk?.point('#checkout-button', 'Finish here');

(options: LoadPuntegoOptions) => HTMLScriptElement | null

Injects exactly one boot script per page. Returns the script element on the client, or null during server rendering. Options: appId (required), apiUrl, baseUrl, src, nonce. A reachable worker needs apiUrl (the data-gp-api origin); for strict CSP, nonce is propagated to both nonce and data-nonce.

(timeoutMs?: number) => Promise<PuntegoApi | null>

Resolves with window.Puntego once the runtime has booted, immediately if it is already present, or null if timeoutMs (default 8000) elapses first.

Shared types

These types appear across the method signatures below.

// Anything the SDK can resolve to an on-page element.
type PublicGuideTarget = Element | PuntegoGuideTarget | string;

interface PuntegoGuideTarget {
  gp_id?: string;
  href?: string;
  route?: string;
  selector?: string;
  target_id?: string;
  xy?: { x: number; y: number };
}

interface PuntegoMarker {
  accent?: string;
  label: string;
  target: PublicGuideTarget;
}

interface PuntegoStep {
  label?: string;
  narration: string;
  target?: PublicGuideTarget;
  text?: string;
  type?: 'caption' | 'point' | 'scroll' | 'spotlight';
}

interface PuntegoWorkflow {
  steps: PuntegoStep[];
  title?: string;
}

interface PuntegoWorkflowResult {
  actionId?: string;
  details?: Record<string, unknown>;
  durationMs?: number;
  status: 'cancelled' | 'completed' | 'failed';
  workflowId?: string;
}

A string PublicGuideTarget is treated as a CSS selector. Pass a live Element when you already hold a node, or a PuntegoGuideTarget object to resolve by gp_id, target_id, route, href, selector, or raw xy coordinates.

window.Puntego methods

window.Puntego implements the PuntegoApi interface. Methods are grouped below by what they do. Pay attention to the return column: the visual helpers return void synchronously, while the messaging, voice, and lifecycle methods return a Promise you should await.

Pointing and captions

Method	Signature	Returns
`point`	`point(target: PublicGuideTarget, label?: string)`	`void`
`caption`	`caption(text: string)` / `caption(target: PublicGuideTarget, text: string)`	`void`
`highlight`	`highlight(target: PublicGuideTarget, label?: string)`	`void`
`scrollTo`	`scrollTo(target: PublicGuideTarget, label?: string)`	`void`
`markers`	`markers(markers: PuntegoMarker[], durationMs?: number)`	`void`
`clear`	`clear()`	`void`

point() and caption() return void — they are not promises. Do not write await sdk.point(...); there is nothing to await.

markers draws a labeled set of pins; pass durationMs to auto-clear after a delay. clear removes the current pointer, caption, highlight, and markers.

Steps and tours

Method	Signature	Returns
`showSteps`	`showSteps(workflow: PuntegoWorkflow)`	`void`
`tour`	`tour(workflow: PuntegoWorkflow)`	`void`

showSteps renders a static step list; tour walks the visitor through each PuntegoStep in sequence.

Messaging and voice

Method	Signature	Returns
`sendMessage`	`sendMessage(prompt: string, opts?: PuntegoSendMessageOptions)`	`Promise<void>`
`speak`	`speak(text: string)`	`Promise<void>`

interface PuntegoSendMessageOptions {
  initiatedBy?: 'system' | 'visitor';
  source?: string;
}

sendMessage and speak are async — await them. speak uses the workspace voice; see Configuration for enabling voice. When voice provider credentials are absent, the runtime falls back to an internal mock voice.

Lifecycle and visibility

Method	Signature	Returns
`init`	`init(options?: PuntegoInitOptions)`	`Promise<PuntegoApi>`
`open`	`open()`	`void`
`close`	`close()`	`void`
`show`	`show()`	`void`
`hide`	`hide()`	`void`
`destroy`	`destroy()`	`void`

init is async and resolves with the SDK; the boot script calls it for you, so you only call it when you opt into manual init with extra options. show/hide toggle the launcher’s visibility; open/close toggle the conversation panel; destroy tears the runtime down.

interface PuntegoInitOptions {
  actions?: GuideActionManifestEntry[];
  autoAsk?: boolean;
  behavior?: PuntegoBehaviorOptions;
  context?: () => Record<string, unknown>;
  launcher?: PuntegoLauncherOptions;
  targets?: GuideActionManifestTarget[];
}

Targets, actions, and sensitivity

These methods feed the guide’s grounding and action registry. See the Guide Tools SDK for the full grounding model and how registered targets and actions are used.

Method	Signature	Returns
`registerTarget`	`registerTarget(target: PublicGuideTarget, registration: PuntegoTargetRegistration)`	`GuideActionManifestTarget \| null`
`unregisterTarget`	`unregisterTarget(id: string)`	`boolean`
`registerAction`	`registerAction(action: GuideActionManifestEntry)`	`GuideActionManifestEntry`
`unregisterAction`	`unregisterAction(id: string)`	`boolean`
`registerShadowRoot`	`registerShadowRoot(root: ShadowRoot)`	`void`
`markSensitive`	`markSensitive(target: PublicGuideTarget, sensitive?: boolean)`	`boolean`
`getActionRegistry`	`getActionRegistry()`	`GuideActionManifest`

interface PuntegoTargetRegistration {
  allowedActions?: PuntegoGuideActionType[];
  description?: string;
  href?: string;
  id: string;
  route?: string;
  sensitive?: boolean;
}

The guide cannot see into a shadow DOM (open or closed) unless you register it with registerShadowRoot. Call it for each shadow root you want the guide to reach. See what the guide can and cannot see for the full visibility model.

Outcomes

Method	Signature	Returns
`reportWorkflowResult`	`reportWorkflowResult(result: PuntegoWorkflowResult)`	`Promise<void>`

reportWorkflowResult is async — await it. It records an outcome trace for owner review (completed, cancelled, or failed). It does not create repair drafts or feed a learning loop.

Events

Method	Signature	Returns
`on`	`on<K>(event: K, handler: PuntegoEventHandler<K>)`	`void`
`off`	`off<K>(event: K, handler: PuntegoEventHandler<K>)`	`void`

See Events below for the full event map.

The control namespace

window.Puntego.control is a parallel surface for product-owned helpers — the visual primitives, mirrored so your own UI code can drive the guide without touching the conversation lifecycle. It implements PuntegoControlApi:

interface PuntegoControlApi {
  caption(text: string): void;
  caption(target: PublicGuideTarget, text: string): void;
  clear(): void;
  highlight(target: PublicGuideTarget, label?: string): void;
  markers(markers: PuntegoMarker[], durationMs?: number): void;
  point(target: PublicGuideTarget, label?: string): void;
  scrollTo(target: PublicGuideTarget, label?: string): void;
  showSteps(workflow: PuntegoWorkflow): void;
  speak(text: string): Promise<void>;
  tour(workflow: PuntegoWorkflow): void;
}

The signatures match their top-level counterparts: point, caption, highlight, scrollTo, markers, showSteps, and tour return void; speak returns Promise<void>. Registration, messaging, lifecycle, and events live only on the top-level window.Puntego, not on control.

Events

Subscribe with on and unsubscribe with the same handler reference via off. Handlers are fully typed against the event name — each payload below is the exact PuntegoEventMap shape.

const onReady = (e: { appId: string; conversationId: string; visitorId: string }) => {
  console.log('guide ready', e.conversationId);
};
window.Puntego?.on('ready', onReady);
window.Puntego?.off('ready', onReady);

Event	Payload	Fires when
`ready`	`{ appId: string; conversationId: string; visitorId: string }`	The runtime has booted and the guide is live.
`bubble:update`	`{ text: string }`	The guide bubble text changes.
`chat:user`	`{ text: string }`	The visitor sends a message.
`chat:assistant-chunk`	`{ delta: string }`	A streamed token chunk arrives from the guide.
`chat:assistant-complete`	`{ fullText: string }`	The guide finishes a streamed reply.
`point:detected`	`{ id: string \| null; label: string \| null; selector: string \| null }`	The guide resolves an element to point at.
`point:unreachable`	`{ label: string; reason: string }`	The guide cannot reach the requested target.
`guide-action:proposed`	`{ action: PuntegoGuideAction }`	An action is proposed to the visitor.
`guide-action:started`	`{ action: PuntegoGuideAction }`	An action begins executing.
`guide-action:completed`	`{ action: PuntegoGuideAction }`	An action finishes successfully.
`guide-action:failed`	`{ action: PuntegoGuideAction; reason: string }`	An action fails.
`opt-out`	`Record<string, never>` (empty object)	The visitor opts out.
`destroy`	`{ reason: 'destroy' \| 'opt-out' }`	The runtime is torn down.
`error`	`{ cause?: unknown; code: string; message: string }`	A runtime error is surfaced.

interface PuntegoGuideAction {
  id: string;
  label?: string;
  risk: 'commit' | 'input' | 'navigation' | 'visual';
  target?: PuntegoGuideTarget;
  type: PuntegoGuideActionType;
}

Runtime-only methods

The runtime also exposes getPageContext() and locateTarget(). These exist at runtime but are not part of the public TypeScript types, so a typed consumer needs a cast to reach them. Treat them as advanced and unstable.

// Not in the public PuntegoApi type — cast to call them.
const sdk = window.Puntego as unknown as {
  getPageContext(): unknown;
  locateTarget(target: PublicGuideTarget): unknown | null;
};
const ctx = sdk.getPageContext();
const located = sdk.locateTarget('#checkout-button'); // null if unresolved

getPageContext() returns a snapshot of the current page the guide can see; locateTarget() resolves a PublicGuideTarget to its on-page location, or null when it cannot. Because they are untyped, their return shapes may change without notice — prefer the typed methods above for anything you ship.

React hooks (@puntego/react)

@puntego/react wraps the same SDK for React apps. Mount PuntegoProvider once near the root, then call the hooks from any descendant. The provider is SSR-safe (the loader only runs in a client effect), so it works with the Next.js App Router. For the full provider setup, see Frameworks.

Hook	Signature	Returns
`usePuntego`	`usePuntego()`	`PuntegoApi \| null` (null until the SDK is ready)
`usePuntegoTarget`	`usePuntegoTarget<T extends Element>(ref: RefObject<T \| null>, options: PuntegoTargetRegistration)`	`void`
`usePuntegoAction`	`usePuntegoAction(options: GuideActionManifestEntry)`	`void`

usePuntego returns the booted window.Puntego SDK for imperative calls (point, sendMessage, on/off, …), or null until it is ready.
usePuntegoTarget registers the element behind a ref as a guide target while the component is mounted, and unregisters it on unmount. Pass the same id you reference from an action’s target_id.
usePuntegoAction declares an action while the component is mounted and removes it on unmount.

import { usePuntego, usePuntegoTarget } from '@puntego/react';
import { useRef } from 'react';

function CheckoutButton() {
  const ref = useRef<HTMLButtonElement>(null);
  usePuntegoTarget(ref, { id: 'checkout-button', description: 'Place the order' });

  const sdk = usePuntego();
  return (
    <button ref={ref} onClick={() => sdk?.point('#checkout-button', 'Finish here')}>
      Check out
    </button>
  );
}

PuntegoProvider props mirror the loader: appId (required), apiUrl (required for a reachable worker), plus optional baseUrl, src, and nonce (propagated to both nonce and data-nonce). See Frameworks.

Next steps

Guide Tools SDK

The grounding model behind targets, actions, and the visual primitives.

Frameworks

Full PuntegoProvider setup for React and the App Router.

What the guide can see

Visibility limits, shadow DOM, iframes, and canvas mode.

Install

The boot script, attributes, and route targeting.

Get started

Integrate

Deploy & security

Resources

Get a reference to the SDK

Shared types

window.Puntego methods

Pointing and captions

Steps and tours

Messaging and voice

Lifecycle and visibility

Targets, actions, and sensitivity

Outcomes

Events

The control namespace

Events

Runtime-only methods

React hooks (@puntego/react)

Next steps

Guide Tools SDK

Frameworks

What the guide can see

Install

​Get a reference to the SDK

​Shared types

​window.Puntego methods

​Pointing and captions

​Steps and tours

​Messaging and voice

​Lifecycle and visibility

​Targets, actions, and sensitivity

​Outcomes

​Events

​The control namespace

​Events

​Runtime-only methods

​React hooks (@puntego/react)

​Next steps

Guide Tools SDK

Frameworks

What the guide can see

Install

Get a reference to the SDK

Shared types

window.Puntego methods

Pointing and captions

Steps and tours

Messaging and voice

Lifecycle and visibility

Targets, actions, and sensitivity

Outcomes

Events

The control namespace

Events

Runtime-only methods

React hooks (@puntego/react)

Next steps