API reference

The window.handhold SDK. Open demos with fields and UTM attribution, identify signed-in users, pass on marketing consent, fire programmatic triggers, and control the launcher.

Every method lives on window.handhold, available once the embed.js script from the quick start has loaded.

openDemo(options)

Opens a Demo or Inbound agent in an overlay, or works with an Inbound agent's chat bar already on the page. To open an Onboarding agent from code, prefer a programmatic trigger, which carries context the agent can act on.

/**
 * Opens a demo with the specified configuration.
 *
 * @param options.id (required) - Agent ID (a UUID; copy it from the agent's Embed dialog)
 * @param options.fields (optional) - Field values keyed by Handhold field ID
 * @param options.utm (optional) - UTM attribution: source, medium, campaign, term, content
 * @param options.externalVisitorId (optional) - Your identifier for the signed-in user, applied to every agent on the page like identify()
 * @param options.externalVisitorIdSignature (required with externalVisitorId) - HMAC-SHA256 of the identifier, computed on your server
 * @param options.theme (optional, default: host page or 'light') - 'light' | 'dark'
 * @param options.locale (optional, default: the visitor's browser language) - Language code (see supported languages)
 *
 * @example
 * window.handhold.openDemo({
 *   id: 'agent-uuid',
 *   externalVisitorId: 'user-8f3k2p',
 *   externalVisitorIdSignature: '9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08',
 *   fields: {
 *     '123e4567-e89b-12d3-a456-426614174000': 'Enterprise',
 *   },
 *   utm: {
 *     source: 'google',
 *     medium: 'paid-search',
 *     campaign: 'spring-launch',
 *     term: 'security-platform',
 *     content: 'hero-cta',
 *   },
 *   locale: 'en',
 * });
 */

fields is keyed by Handhold field ID, not field name. Values must match the configured field type (string, number, or boolean); select fields use one of their configured options. The fields must be configured on the agent being opened. Empty string values are ignored.

utm supports the canonical keys source, medium, campaign, term, and content. Values passed here override matching UTM values from the page URL, or remembered from an earlier page with marketing consent, for the new session. If your site already keeps campaign tags, for example for your analytics, pass them here. All five UTM values are available as mapping sources in Handhold automations, including HubSpot contact mappings.

externalVisitorId and externalVisitorIdSignature identify the signed-in user the same way as identify(): the identity applies to every agent on the page until the page reloads or reset() is called.

The locale option accepts any of the supported languages. When omitted, the visitor's browser language is used. A language that is not enabled for the agent falls back to English.

For Inbound agents, openDemo additionally accepts initialQuery: pass the visitor's question from your own search bar or help input, and the agent opens already answering it.

Each call replaces the fields and utm of an earlier one, so pass them again.

The chat bar

When an Inbound agent's chat bar (mode=input, from the quick start) is on the page, openDemo works with it instead of opening an overlay:

  • With initialQuery, the bar asks the question, in the open conversation if there is one.
  • Called without initialQuery within a few seconds of the visitor's click or key press, it puts the cursor in the bar, which shows its suggested questions. It leaves the cursor where it is while the visitor is typing in a field on your page. Safari doesn't let the bar, which loads from handhold.io, take the cursor on your site, so in Safari this part changes nothing.

To start with the launcher hidden, pass both mode: 'hidden' and hidden: true, then reveal it later with showLauncher(). (The launcher and input modes are iframe URL parameters, shown in the quick start, not openDemo options.)

identify()

Tells every agent on the page who the signed-in user is. Handhold then recognises the user on any of your apps, browsers and devices: a conversation they left open in the launcher or chat bar continues wherever they open it next, until it ends five minutes after they leave; the start screen skips questions they already answered; and the agent carries context from their earlier conversations.

/**
 * @param identity.externalVisitorId (required) - Your identifier for the signed-in user, 8 to 255 characters
 * @param identity.externalVisitorIdSignature (required) - HMAC-SHA256 of the identifier, computed on your server
 *
 * @example
 * window.handhold.identify({
 *   externalVisitorId: 'user-8f3k2p',
 *   externalVisitorIdSignature: '9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08',
 * });
 */

Call it on every page load where a user is signed in. The identity lasts until the page reloads and isn't saved in the browser, so a page that doesn't call identify() treats its visitor as anonymous.

Call it as early as you can, and before launch(). When the page already knows the user, call it from the script's onload:

<script
  async
  src="https://handhold.io/demo/embed.js"
  onload="window.handhold.identify({ externalVisitorId: 'user-8f3k2p', externalVisitorIdSignature: '9f86d0…' })"
></script>

When your app loads the user after the page, call identify() as soon as it knows them. window.handhold exists only once embed.js has loaded, so if your app can know the user before that, also call identify() from the script's onload with the user it knows by then. Agents wait up to a quarter of a second after embed.js loads, so a call from onload is in place before they start. A later call still works: the agent switches to the user where it is, without reloading. A conversation the visitor started before the call continues as the user's, unless the user already has a conversation open elsewhere; then the launcher or chat bar switches to that one. The launcher also reopens an anonymous conversation left open in the same browser, until it ends five minutes after its visitor leaves. So on a shared computer, a late call can give the previous visitor's conversation to the user who just signed in. A call from onload avoids this: a launcher that starts with the user signed in never reopens an anonymous conversation.

Calling identify() again with the same externalVisitorId changes nothing. Calling it with a different one switches to that user, as reset() followed by identify() would. A call with a missing or malformed identifier or signature is ignored with a console warning, but if it names a different user than the one already identified, that user is still signed out, as with reset().

Identity verification

Because the identifier unlocks the user's conversations, it must be signed. Every externalVisitorId, whether passed to identify() or openDemo, has to be accompanied by externalVisitorIdSignature: an HMAC-SHA256 of the identifier, keyed with your organisation's visitor identity secret and hex-encoded. Identifiers are scoped to your organisation. When the signature isn't valid, the agents work without recognising the visitor.

Generate the secret under Settings → Visitor identity and store it with your other server-side secrets. Compute the HMAC on your server and never ship the secret to the browser — anyone holding it can impersonate any of your visitors. Regenerating the secret invalidates signatures made with the previous one.

// Node.js — on the server that renders the page
import { createHmac } from 'node:crypto';

const externalVisitorIdSignature = createHmac(
  'sha256',
  process.env.HANDHOLD_VISITOR_IDENTITY_SECRET,
)
  .update(user.id)
  .digest('hex');
# Python
import hashlib, hmac, os

external_visitor_id_signature = hmac.new(
    os.environ["HANDHOLD_VISITOR_IDENTITY_SECRET"].encode(),
    user.id.encode(),
    hashlib.sha256,
).hexdigest()
# Ruby
external_visitor_id_signature = OpenSSL::HMAC.hexdigest(
  "SHA256", ENV.fetch("HANDHOLD_VISITOR_IDENTITY_SECRET"), user.id
)
// PHP
$externalVisitorIdSignature = hash_hmac('sha256', $user->id, getenv('HANDHOLD_VISITOR_IDENTITY_SECRET'));

Pass the result straight through to identify() or openDemo, and use an opaque internal user id rather than an email address so the identifier is not guessable even by someone who can read it.

reset()

Makes the page anonymous again. Call it when a user signs out without the page reloading. If the user's conversation is open, the agent closes it and continues for the anonymous visitor; the conversation stays open for the user, and the launcher or chat bar continues it the next time they're identified, until it ends five minutes after they leave.

window.handhold.reset();

launch() (programmatic triggers)

Programmatic triggers are the recommended way to open an Onboarding agent from your own code. Instead of just popping the agent open, a trigger carries the context you configured, so the agent knows why it appeared and greets the visitor accordingly: a help button on a settings page, a "show me" link in an announcement, a moment where the visitor seems stuck.

Set one up in the agent's Triggers tab: create a Trigger from your code trigger, give it a name and, optionally, context the agent should know when it fires. The dialog gives you a ready-made snippet:

window.handhold.launch({ agentId: 'YOUR_AGENT_ID', triggerId: 'YOUR_TRIGGER_ID' });

Call it on any page that has both the embed.js script and the agent's iframe from the quick start installed.

  • The call only fires when the trigger is configured on the agent. An unknown or removed trigger is silently ignored: nothing opens and no error is shown. This means you can ship trigger calls in your product ahead of configuring them in Handhold, and turn each one on by creating it in the Triggers tab.
  • Opens the agent and starts a session, from the launcher or the chat bar. If a conversation is already open, the call does nothing.
  • A trigger set to Fire only once per visitor opens the agent only once for each visitor. After it has opened the agent for a visitor, later calls for that visitor are silently ignored, in any tab and on later visits. Users you identify with identify() are recognised across devices and domains; anonymous visitors only within one browser and origin, so each subdomain counts separately. A user you identify after they used the agent anonymously counts as a new visitor, so the trigger can open the agent for them again, unless it opened the conversation that continued as theirs when they signed in. In the agent preview inside Handhold, the trigger opens the agent every time.
  • Safe to call while the widget is still initializing: as long as the agent's iframe is on the page, early calls run once it's ready.

showLauncher(agentId?)

Shows the Onboarding agent launcher. Only applies to Onboarding agents embedded with mode=launcher; it has no effect on Demo agents or on the chat bar (mode=input), which is always visible. If the user is in an active conversation, this is a no-op (the conversation UI remains visible).

/**
 * @param agentId (optional) - Agent identifier. If omitted, targets the most recently opened agent.
 *
 * @example
 * window.handhold.showLauncher('agent-uuid');
 */

hideLauncher(agentId?)

Hides the Onboarding agent launcher. Only applies to Onboarding agents embedded with mode=launcher; it has no effect on Demo agents or on the chat bar (mode=input), which stays visible. If the user is in an active conversation, this is a no-op (the conversation stays open).

/**
 * @param agentId (optional) - Agent identifier. If omitted, targets the most recently opened agent.
 *
 * @example
 * window.handhold.hideLauncher('agent-uuid');
 */

setMarketingConsent(granted)

Tells Handhold whether the visitor has accepted marketing cookies on your site. Handhold always uses the UTM tags in the address of the page where a conversation starts. With marketing consent, it also remembers the tags of the page the visitor arrived on for 30 days, so a conversation started on a later page is attributed to the same campaign. Without it, Handhold keeps no campaign tags in the visitor's browser.

/**
 * @param granted (required) - true if the visitor accepted marketing cookies, false if not
 *
 * @example
 * window.handhold.setMarketingConsent(true);
 */
  • true remembers the current page's tags, and uses tags remembered on earlier pages.
  • false deletes remembered tags. Handhold then uses only the tags in the current page's address.

Until you call it, Handhold treats the answer as false. The choice isn't saved in the browser, so call it on every page load once your cookie banner knows the visitor's choice, and again whenever the visitor changes it. window.handhold exists only once embed.js has loaded, and your banner may know the choice before or after that, so call it from both places. With Cookiebot:

<script>
  function syncHandholdConsent() {
    const marketing = window.Cookiebot?.consent?.marketing;
    if (window.handhold && marketing !== undefined) {
      window.handhold.setMarketingConsent(marketing);
    }
  }
  window.addEventListener('CookiebotOnConsentReady', syncHandholdConsent);
</script>
<script async src="https://handhold.io/demo/embed.js" onload="syncHandholdConsent()"></script>

Other cookie banners report the choice in a similar way:

BannerWhen the choice is known or changesMarketing consent
OneTrustOptanonWrapper(), which OneTrust calls when it loads and on every change. If your site already defines OptanonWrapper, call the existing one from yours.OnetrustActiveGroups.includes('C0004'). C0004 is OneTrust's default targeting category; use yours if it differs.
CookieYesThe cookieyes_banner_load and cookieyes_consent_update events on documentgetCkyConsent().categories.advertisement
HubSpot_hsp.push(['addPrivacyConsentListener', callback])consent.categories.advertisement, passed to the callback

If your site doesn't need consent for this, call setMarketingConsent(true) from the script's onload.

Control Onboarding agent page access

Onboarding agents read the page they run on so they can guide visitors. They see its visible text and structure, including same-origin iframes. They don't see form field values, hidden elements, images, link URLs, or cross-origin iframes. Inbound and Demo agents don't read the page they're embedded on.

Add data-handhold-sanitize to hide content from the agent. It can't read or point at the marked element or anything inside it.

<section data-handhold-sanitize>
  <!-- The Onboarding agent cannot see this account area. -->
</section>
  • The attribute works by presence, so data-handhold-sanitize="false" still hides the element. In React, use data-handhold-sanitize={hidden ? '' : undefined}.
  • Put it on html or body to hide a whole page. It also works on an iframe and inside same-origin frames.
  • Add it before the content renders.
  • Mark components that show typed text elsewhere on the page, such as code editors or search fields that display the search term.

The marker doesn't cover chat messages, session fields, page URLs, UTM values, or Demo agents' live product browser.

For AI agents: a clean Markdown version is available at /docs/api.md.