Skip to main content
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 checked against the prepared package declarations in the Puntego repository. Every signature below comes from @puntego/embed. Importing the package augments the global Window, so window.Puntego is fully typed with no extra setup:
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 developer packages (@puntego/embed, @puntego/react, and @puntego/cli) publish to npm at launch and are not yet published today, so package imports on this page are release-preview APIs until then. The hosted boot script works today and exposes the same window.Puntego surface — 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.
(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, customerIdentityToken, headless, theme, launcher, and appearance (see Appearance); appearance is written to the boot script as data-accent, data-theme, data-font and data-radius. apiUrl defaults to the public Puntego worker; for strict CSP, nonce is propagated to both nonce and data-nonce. Set headless: true on the first load for a custom Guide/Experience UI.
(timeoutMs?: number, signal?: AbortSignal) => 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. Pass an AbortSignal to stop waiting early; an already-aborted or later-aborted signal also resolves null and removes the poller.
Builds a bounded HTTPS customer-product link from the one-time opaque campaignToken returned by campaign creation. destination must be an absolute URL without embedded credentials; public HTTP, malformed 43-character campaign tokens, and links over 4096 characters are refused.
Create the campaign in Dashboard → Guides → Links or through the authenticated Magic Links API. Its create response returns the opaque campaign token once; use that token to build the customer-product destination:
Destinations require HTTPS outside localhost. The runtime removes the reserved token before boot, latches only its SHA-256 fingerprint per browser session, and resolves the active campaign through the origin-bound visitor session. A refresh or remount cannot replay it. Prompt text, attribution, credentials, action receipts, and permissions never enter the URL. Expired or revoked campaigns fail closed; legacy prompt-bearing parameters are removed but never submitted. The bounded source and landing path are recorded in aggregate campaign reporting, while any later action still passes its normal policy and confirmation gates.

Authenticated customer boot

customerIdentityToken accepts a short-lived, one-time token minted by your server through POST /api/identity/token. The mint endpoint requires a server-held API key scoped to identity:write; never expose that key to browser code. This minimal server example uses environment placeholders, not a real secret:
Return only identity_token from a same-origin, Cache-Control: private, no-store route, fetch it after hydration, and pass it directly to loadPuntego({ customerIdentityToken: identity_token, ... }). Do not serialize it through a Server Component or place it in markup, URLs, logs, cookies, or browser storage. The loader holds it in memory only, sends it on the first /boot, clears it after success or terminal failure, and never replays it on a JWT refresh. An identity boot is intentionally not retried or downgraded to an anonymous visitor. See the complete Next.js identity example.

Shared types

These types appear across the method signatures below.
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: most visual helpers return void synchronously (point returns a Promise<boolean>), while the messaging, voice, and lifecycle methods return a Promise you should await.

Pointing and captions

point() returns a Promise<boolean> that resolves true when the pointer actually landed on the target (false otherwise), so await sdk.point(...) is valid when you need to sequence work after the pointer shows. caption() returns void — it is not a promise.
caption(target, text) places the note beside that element, with a thin outline on it; the note follows the element as the page scrolls or re-renders, a keyboard visitor can tab to it, and screen readers hear it once. caption(text) shows the note in the guide instead. 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

showSteps renders a static step list; tour walks the visitor through each PuntegoStep in sequence. A tour can cross pages. Give each step the route of the page it is on. A navigate step points at the link to the next step’s page: the visitor follows it (or presses Next, which follows the same link) and the tour continues on that page. A focus step puts the cursor in a field so the visitor can type; it never types for them.

Messaging and voice

speak always shows and announces the text. It is read aloud only when voice is turned on for the workspace (Settings → Guide behavior → Voice) and the visitor has accepted the voice notice; otherwise it stays text.
A turn with initiatedBy: 'system' (your own sendMessage, or the guide speaking first when the panel opens) counts as one AI reply when it answers, like a visitor’s question. Each person (the signed customer, otherwise the visitor) gets up to 20 system turns a day (UTC). Past that, the turn is refused with HTTP 429 and chat/system_turn_limit before any model runs, until the next UTC day. Questions the visitor asks are never counted against this limit.

Turns

The typed turn model behind the built-in answer card. Each PuntegoTurn has the question, answer text, disclosed sources, follow-up chips, a tour proposal, footer actions with localized labels, status, and timings — never proofs, selectors, or executable actions. See Headless SDK. Turn commands act only on the latest turn where the built-in guide would, and are inert in privacy-only mode, while consent blocks the assistant, and after destroy(). runTurnAction runs an action only while that turn offers it (listed and not disabled), through the built-in button’s own path, so consent, confirmation, plan limits and action policy still apply; do_it and undo also need a real visitor gesture where the browser reports one, so call it from the click handler itself. To build the whole answer card with your own components, see React components. Feature-detect them (typeof sdk.getTurnSnapshot === 'function') when a newer package may meet an older hosted runtime.
sendMessage and speak are async — await them. speak uses the workspace voice; see Configuration for enabling voice. Production requires hosted-provider credentials and otherwise leaves voice unavailable while text guidance continues. The internal mock is development/test-only.
trackExperienceEvent connects a trusted product milestone to an authored host-event experience or checklist item:
It accepts only a name (no arbitrary payload), ignores invalid names, and the public widget can match production deployments only. Names begin with a letter, may contain letters, digits, _, ., :, and -, and are capped at 120 characters. A host event is additive: it cannot dismiss an unrelated active page-load experience.

Customer and account traits

User and group traits are supported through the server identity handoff, not through a browser identify, group, or event-properties method. Your authenticated server calls POST /api/identity/token (or mintPuntegoIdentityToken from @puntego/react/server) with scalar customer traits and an optional account object with scalar group traits. The one-time token is consumed only by the initial boot; keep it in memory and never expose the API key or token in HTML, URLs, logs, cookies, or browser storage. The worker accepts strings, finite numbers, booleans, null, and arrays of those scalars. Nested objects, unsafe keys, oversized values, and control characters are rejected. During chat and Experience matching, only the workspace’s explicit non-sensitive trait allowlist is projected into grounding; credential- and direct-identifier-shaped keys remain refused even when an owner tries to allowlist them. Consent still gates every visitor-bound chat, match, and engagement request. PuntegoInitOptions.context is unsigned page metadata, not an identity or authorization channel. Its typed accountFacts (plan, seats, usage, features, renewal date, role) can ground answers but never authorize anything, and signedAccountFacts carries facts your server signed with the workspace secret. Keep credentials and personal data out of it. See Account facts.

Headless Experiences

These methods are active only when the first page boot used headless: true. They expose sanitized content and typed engagement commands; the runtime keeps the signed match proof private. engageExperience accepts impressions, dismissals, authored action indexes, checklist completions, and validated Survey/Form answers. It does not accept a deployment, environment, credential, URL, callback, or signed proof. See the Headless SDK for complete examples and security boundaries. Typed snapshots include user-opened hint Nudges, release_feed Announcements, and progress Checklist badges without exposing disclosure state or private match proofs.

Lifecycle and visibility

requestHandoff asks for a person from your own button, exactly like Talk to a person in the guide: it fires handoff:requested and then opens your site’s chat or the contact form (see Hand off to a person). It does nothing while human handoff is off, before consent, or when called from the agent tools. 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 open and close the assistant on its entry surface — the ask bar by default, or the conversation panel with launcher: { entry: 'panel' } (see Configuration); destroy tears the runtime down.
context is read on every message. A later init({ context }) on its own replaces the function without touching the running widget’s presentation, and when accountFacts.accountId (or the signed token’s subject) names another account the guide starts a new conversation at once. See Account facts for the contract, signing and the dashboard mapping. locale sets the widget’s visitor-facing language (en, es, pt, fr, de, it, or a tag such as es-MX or fr-CA). Without it, the widget follows your page’s <html lang>, then the visitor’s browser language. A later init({ locale }) switches the language of an already-running widget. Once a visitor writes in one of these languages, the widget’s own words follow the conversation’s language. customerIdentityToken is honored only by the first page-level init. Later init calls cannot change identity. When the signed-in customer changes without a page reload (login, logout, an account switch in a single-page app), call setIdentity(token) with a fresh one-time token your server minted, or clearIdentity() on logout. Either stops the current runtime at once — its conversation and anything grounded on it never reach the next visitor — and boots the same app again, keeping your event listeners, host context, targets, actions and host tools; register closed shadow roots again. It resolves true once the new guide is ready. A newer call supersedes an earlier one: if that one is still queued its token is simply not used, and if it is still booting it stops at once and never becomes ready. destroy() cancels a queued change. In React, pass the token to PuntegoProvider as customerIdentityToken instead: the provider runs the same lifecycle. In normal integrations, prefer the loader option or that prop for the first boot so the value is present before automatic boot. headless is also page-lifetime immutable. It suppresses Puntego’s built-in launcher, panel, automatic prompts, and Experience renderer, while preserving required privacy/consent controls and action policy.

Targets, actions, and sensitivity

A page registers at most 100 targets and 100 actions. Past that, registerTarget and registerAction return { ok: false, reason: 'over_limit' }, keep every earlier registration, and print E_TARGET_REFUSED or E_ACTION_REFUSED once per page session; re-registering an id that is already registered is an update and always works. recordTarget follows the same limit: past it, it says so on the page and records nothing new until a capture names a target ID the page already has. null means nothing was registered: the guide is not running, the id is empty, or the target can’t be resolved on the page. 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. Grounding, not authorization. registerTarget and registerAction describe your page to the guide; they do not authorize a chat-turn action. Anything the browser sends is untrusted, so the server authorizes only against the declared-action manifest your workspace holds. Declare the action in your workspace’s Guide Action Contract as well when you want the guide to execute it. getActionRegistry() returns the union of your workspace manifest and the page’s local registrations, which is what the SDK-dispatch path validates against locally.
Open shadow roots are discovered automatically, including roots attached after boot. Closed roots are not exposed through element.shadowRoot; the component owner must retain that ShadowRoot reference and pass it to registerShadowRoot(root). See what the guide can and cannot see for the full visibility model.

Host tools

registerTool offers the guide a read-only function of your page — list invoices, read usage — that it may call to answer with the visitor’s own data. Only the fields you list leave the page, and they ground the answer like page-reported account facts: never authorization. See Host tools. With kind: 'write' it offers a write tool instead: a function that changes the visitor’s own account (an API key, access, a role, the plan or billing, the payment method) with their own session. It runs only after the visitor presses Do it on the guide’s card, which counts after a second and always offers I’ll do it instead; Growth and above, never for another AI agent, at most one per turn. A secret it creates is shown by your own UI, inside an element marked data-puntego-ignore, and never reaches the guide; a successful write counts as one agent action. Register one only when hostToolKinds includes 'write'. See Write tools.

Agent tools (assist)

assist lets another AI agent working in the visitor’s browser — or your own in-page assistant — use the guide as a governed tool: ask (an answer with sources), show_me (a pointer or a visual tour) and do_action (one action the visitor approves on the guide’s card). Off until an owner turns it on in Settings → Guide behavior → Other AI agents. See Other AI agents. Neither call throws. A do_action result carries the receipt the page or your site verified (receipt.verified), or what happened instead (declined, shown_instead, not_done, failed, awaiting_person). The agent can never approve a write: only the visitor’s own press on the card does. A payment, signature or deletion is always refused for an agent: not_done with error.code high_risk_refused, and the visitor is shown where it is. A write your team approves is awaiting_person while your team decides (its summary says so) and not_done with error.code owner_declined when your team does not approve it. Every PuntegoAgentToolResult also carries type, one of started, answer, needs_clarification, unavailable or error: the branch an agent takes, with status as the detail. See the typed response.

Outcomes

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

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:
The signatures match their top-level counterparts: caption, highlight, scrollTo, markers, showSteps, and tour return void; point returns Promise<boolean>; 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. The event contract is versioned. window.Puntego.eventsVersion is 1. Within a version, event names and payload fields are stable: new events and new optional fields may be added, nothing is renamed or removed; a breaking change ships as a new version. In React, usePuntegoEvents delivers any of them as { name, payload, version, at } for your analytics.
The chat:* events are the legacy stream view and keep firing unchanged. A generated record link (see Generative UI) opens a same-origin path built from a record page you declared. Before anything moves, Puntego dispatches a cancelable puntego:navigate event on window and the SDK navigate event. Take it over with either:
detail is { href, path, reason: 'record', record: { id, route }, turnId }. The SDK event carries the same fields plus preventDefault(). Without a handler that calls preventDefault(), Puntego opens the path itself. A visitor who opens the link in a new tab (a modified or middle click) gets the browser’s own behaviour.

Page inspection and target recording

The typed SDK includes getPageContext(), inspect(), locateTarget(), and recordTarget(). The first three expose bounded snapshots of what the guide can currently see. recordTarget() opens the in-product target recorder and resolves to the recorded manifest target, or null when recording is cancelled.
Use getPageContext() for the full capture context, inspect() for the compact DOM digest, and locateTarget() when you need the current position of one PublicGuideTarget. These return snapshots, not live DOM handles.

Sub-apps in frames (@puntego/embed/frame)

Inside a sub-app that your page embeds as a cross-origin iframe, the child SDK answers the guide on your page. It has no UI and needs no app ID or key. The page that embeds it must allow the sub-app’s origin in Dashboard → Install → Sub-apps in frames. It accepts the guide only with a pass Puntego signs for each connection, checked with Puntego’s public keys (apiUrl: your Worker, only when it is not the public one). See Sub-apps in iframes. parentOrigins are the exact origins of the pages allowed to guide inside the sub-app (the script tag’s data-parent-origin). The child answers only its direct parent, only from one of them, and acts only on a write your page prepared with it and confirmed after the visitor approved it on the guide’s card, and only when the pass for that connection allows actions (Allow actions in this frame in Install → Sub-apps in frames, off by default; version 1.2.0 and later).

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.
  • usePuntego returns the booted window.Puntego SDK for imperative calls (point, sendMessage, on/off, …), or null until it is ready.
  • usePuntegoStatus exposes render-safe connection state and the current loader error. A timed-out boot can recover from error to ready on a slow network.
  • 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.
  • usePuntegoTargetRef returns a callback ref with the same lifecycle, avoiding a separate useRef when Puntego is the only ref consumer.
  • usePuntegoAction declares an action while the component is mounted and removes it on unmount.
  • usePuntegoEvent subscribes to a typed runtime event, always invokes the latest handler, and detaches on unmount or when enabled becomes false.
  • usePuntegoGuide and usePuntegoExperiences use render-safe external-store snapshots and stable server fallbacks. Mount the provider with headless before using them as the product UI.
  • usePuntegoTool offers a host tool — a read, or a write tool the visitor approves — while the component is mounted, always calls the latest handler, and withdraws it on unmount.
  • usePuntegoEvents subscribes to many public events at once (all of PUNTEGO_EVENT_NAMES by default) and delivers each as a versioned envelope { name, payload, version: 1, at }.
  • @puntego/react/ui is a separate entry point with the answer card and ask bar built from your own components; see React components.

Server identity helper (@puntego/react/server)

The @puntego/react/server subpath exports mintPuntegoIdentityToken for custom server flows and createPuntegoIdentityRoute for a POST-only Fetch API handler. Both accept a server-held identity:write key, validate the worker URL and bounded identity fields, never retry an ambiguous mint, and surface only sanitized errors. The route returns only { identity_token, expires_at } with Cache-Control: private, no-store; its required identify(request) callback must resolve from your authenticated server session.
PuntegoProvider props mirror the loader: appId is required; apiUrl is optional and defaults to the public Puntego worker. Optional props also include baseUrl, src, nonce (propagated to both nonce and data-nonce), and the initial-only customerIdentityToken. Use onReady for one-time instrumentation and onError to route loader failures into your observability UI. 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.