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:
@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 assignswindow.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.
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.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.Magic Links
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: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:
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.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
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.
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. EachPuntegoTurn 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:
_, ., :, 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 browseridentify, 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 usedheadless: 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.
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:
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 withon 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.
Routing record links in a single-page app
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 cancelablepuntego: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 includesgetPageContext(), 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.
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.
usePuntegoreturns the bootedwindow.PuntegoSDK for imperative calls (point,sendMessage,on/off, …), ornulluntil it is ready.usePuntegoStatusexposes render-safe connection state and the current loader error. A timed-out boot can recover fromerrortoreadyon a slow network.usePuntegoTargetregisters the element behind a ref as a guide target while the component is mounted, and unregisters it on unmount. Pass the sameidyou reference from an action’starget_id.usePuntegoTargetRefreturns a callback ref with the same lifecycle, avoiding a separateuseRefwhen Puntego is the only ref consumer.usePuntegoActiondeclares an action while the component is mounted and removes it on unmount.usePuntegoEventsubscribes to a typed runtime event, always invokes the latest handler, and detaches on unmount or whenenabledbecomes false.usePuntegoGuideandusePuntegoExperiencesuse render-safe external-store snapshots and stable server fallbacks. Mount the provider withheadlessbefore using them as the product UI.usePuntegoTooloffers 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.usePuntegoEventssubscribes to many public events at once (all ofPUNTEGO_EVENT_NAMESby default) and delivers each as a versioned envelope{ name, payload, version: 1, at }.@puntego/react/uiis 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.