3Guide Docs

SDK reference

Every script attribute and JavaScript method, in one place.

3Guide ships as two separate scripts. The Guidance script is 3Guide; the Analytics script is optional. See Installation options.

Scriptdata-guideai-bundleWhat it does
https://cdn.3guideai.com/sdk/guideai.jsguidanceChat bubble, guides, help hints, announcements, AI Assistant
https://cdn.3guideai.com/sdk/guideai-tracking.jstrackingAnalytics, replays, feature flags. Invisible.

Both need the same data-site-id and data-token. When both are loaded they share one window.guideai object.

The easiest way to set most attributes is the editor in Settings → SDK Installation, which builds the snippet for you. Some settings, such as the bubble label, icon and widget mode, can also be saved there and are applied on the next page load without changing your snippet.

Script attributes

Required

AttributeValue
data-site-idYour site's ID (or read it from storage with data-site-id-source, data-site-id-key and data-site-id-token-field, see Installation options)
data-tokenYour Public Token (pk_live_…)

Connection

AttributeDefaultNotes
data-api-urlhttps://cdn.3guideai.com3Guide API address
data-cdn-urlhttps://cdn.3guideai.comWhere knowledge base and assets load from
data-disable-routesnoneComma-separated paths where 3Guide stays completely off, e.g. /admin/*,/checkout

Chat and bubble

AttributeDefaultNotes
data-widget-modeset by Agent Blueprintcombined, guide, assistant, support or docs. Leave it out to let the dashboard decide. See chat modes.
data-bubble-enabledtrueShow the chat bubble
data-bubble-labelnoneText on the bubble, e.g. Help
data-bubble-iconrobotMascot icon. Or set data-bubble-image to your own image URL.
data-bubble-positionbottom-rightbottom-right, bottom-left or center (bottom-centre)
data-bubble-bottom-offset0Percentage of screen height. Positive moves the launcher up, negative down.
data-bubble-modedriftHow the bubble moves: drift (gently floats) or crawl (moves along the page edges with speech messages)
data-chat-expand-dockrightWhere the expanded chat docks: right, left or bottom
data-chat-suggestionsHow do I get started?, Show me aroundStarter questions, separated by |
data-chat-guidance-title / -textbuilt inWelcome text in Guidance mode
data-chat-assistant-title / -textbuilt inWelcome text in Assistant mode
data-live-supporttrueAllow hand-off to a person
data-headlessfalseNo built-in UI at all. Drive everything from your own code. See Use 3Guide with your own AI.
data-voice-inputtrueMic button. false hides it.
data-voice-replytrueRead answers to recorded messages aloud. false hides it.
data-live-voicefalseLive conversation button. true shows it.
data-home-sourceinlineUse published to load the Home configuration published from Experience Studio. The generated installation snippet sets this for you.

Experience Studio buttons

When Home is enabled, any element can open a specific widget destination:

<button data-guideai-open="home">Get help</button>
<button data-guideai-open="assistant">Ask the Assistant</button>
<button data-guideai-open="demos">Browse demos</button>

Use home, chat, guidance, assistant, demos, blog, updates or support. The destination is ignored when its Home section is disabled.

Look and feel

AttributeDefault
data-theme-primary#3b82f6
data-theme-text#1a1a2e
data-theme-background#ffffff
data-theme-fontsystem font
data-color-schemelight (or dark, auto)
data-dark-primary, data-dark-background, data-dark-text, data-dark-text-secondary, data-dark-text-muted, data-dark-border, data-dark-surface, data-dark-surface-hoverbuilt-in dark palette (used only when dark is active)
data-bubble-background, data-bubble-background-hover, data-bubble-text-color, data-bubble-border, data-bubble-border-hover, data-bubble-shadow, data-bubble-shadow-hover, data-bubble-focus-ringderived from the theme

Guides and hints

AttributeDefaultNotes
data-guides-enabledtrueAllow guides to play
data-auto-advance-on-target-clicktrueMove to the next step when the user clicks the highlighted element
data-chip-dismiss-seconds300How long a dismissed suggestion chip stays hidden
data-hint-icon-color, data-hint-button-color, data-hint-button-text-color, data-hint-button-labelbuilt inHelp hint colours and demo-button label. Hints are on by default; turn them off in Settings.
data-help-hints-cache-ttl-ms86400000 (24 h)How long hints are cached in the browser

Announcements

AttributeDefaultNotes
data-announcement-surfacemodalmodal, banner or drawer
data-announcement-display-modeautoDefault for announcements that don't set their own
data-announcement-frequencyonceDefault frequency
data-announcement-auto-show-delay-ms500Delay before auto-showing
data-announcement-close-on-backdroptrueClose when the backdrop is clicked

Settings chosen for an individual announcement in the Studio take priority.

Analytics and privacy

AttributeDefaultNotes
data-recordingfalseSession replays (on the tracking script)
data-geolocationoffoff, granted-only or prompt. Location otherwise comes from the IP address.
data-idle-timeout20000Milliseconds before a visitor counts as idle
data-session-timeout-ms1800000Inactivity before a new session starts (30 min)
data-batch-size / data-batch-interval-ms50 / 30000How events are batched
data-feedback-auto-promptfalseAsk for feedback automatically

JavaScript API

Everything is on window.guideai. It's available once the script has loaded. Wait for it with:

await window.guideai.ready()

Identity

MethodWhat it does
initialize({ visitor, account })Identify the signed-in person and their account, with any properties
identify(userId)Switch to a stable user ID, merging earlier anonymous activity
clearSession()Forget the current person. Call on sign-out.

Analytics

MethodWhat it does
track(name, properties?)Send a business event, e.g. track('invoice_paid', { amount: 120 }). track('signup') and track('login') also start onboarding, even without the Analytics script.
trackFeature(key, label?, properties?)Record use of a feature
pageLoad()Record a page view manually, for routers 3Guide can't detect
flushNow()Send buffered events immediately
optOut() / optIn() / isOptedOut()Pause and resume tracking, e.g. for consent

Feature flags

MethodWhat it does
isFeatureEnabled(key)true if the flag is on for this visitor
getFeatureFlag(key)The flag's value or variant
getFeatureFlagPayload(key)Extra data attached to the flag
reloadFeatureFlags()Fetch flags again, e.g. after identify

Guides

MethodWhat it does
validateGuideById(id)Check a guide exists and can play
showGuideById(id, stepIndex?)Start a guide, optionally from a given step
dismissGuide()Close the guide that's playing

Chat

MethodWhat it does
openChat(mode?, lockMode?, anchor?, compact?)Open the chat, optionally in a mode, anchored to an element, compact or full. See your own button.
openGuidance() / openAssistant()Open it in a specific mode
openDocsSearch(anchor?) / closeDocsSearch()Open or close Docs mode search
setColorScheme(scheme)light, dark or auto
refreshHelpHints()Look for help hints again after your app changes the page
openSupportChat()Open a conversation with your team
send(text, { mode? })Send a message as the user. In headless mode it resolves with the answer and steps.
runWalkthrough(steps, title?)Play walkthrough steps on the page
navigateTo(url)Take the user to a page
assistantAvailabletrue if Assistant mode can answer on this site
expandChat(dock?) / collapseChat()Expand the chat (right, left or bottom) or collapse it

Surveys and lifecycle

MethodWhat it does
showNPSSurvey(context?) / showCSATSurvey(context?)Show a survey now
on(event, handler)Listen to SDK events
destroy()Remove 3Guide from the page

To change script attributes on a live page, call destroy(), then add the script tag again with the new attributes.

On this page