Web SDK Functions

Complete reference for the Told Web SDK API. All functions are called through the global told() function.

info

The SDK must be initialized with told('init', ...) before calling any other function.

How the SDK works

The Told SDK is a lightweight JavaScript snippet that runs on your website. Here's how it works under the hood:

Script loading — The snippet you paste in your <head> creates a queue (told.q) and starts loading the SDK asynchronously. Any calls to told(...) before the script finishes loading are queued and replayed once the SDK is ready.
Initialization — told('init', sourceID) validates your source against the current domain, generates an anonymous ID for the visitor, and starts listening for trigger events (page views, clicks, scroll, custom events).
Iframe rendering — Surveys and product tours are displayed inside isolated <iframe> elements injected into a <div id="told-container"> at the bottom of your page. This ensures they don't interfere with your CSS or JavaScript.
Communication — The SDK and iframes communicate via the browser's postMessage API. The SDK only accepts messages from trusted Told origins.
User tracking — Each visitor gets a unique anonymous ID stored in localStorage (told-anonymousID). When you call identify, this anonymous profile is enriched with the data you provide.
Language detection — The SDK detects the browser language automatically. If the survey or product tour has a translation for that language, it displays in it; otherwise it uses the default language. You can override this with init({ language }) or identify({ language }). See Languages.

INIT

Initialize the SDK with your Source ID. Must be called before any other function.

told('init', 'YOUR_SOURCE_ID');

With options:

told('init', 'YOUR_SOURCE_ID', {
  language: 'fr',              // Override browser language detection
  noLocalStorage: true,        // Disable localStorage (anonymous ID won't persist across sessions)
  hidden_fields: {             // Pre-identify the user at init time
    email: '[email protected]',
    userId: '123',
    plan: 'pro',
  },
});

Parameter	Type	Required	Description
`sourceID`	`string`	Yes	Your Source ID (found in Settings > Installation)
`options.language`	`string`	No	ISO language code (e.g. `'en'`, `'fr'`). Overrides automatic browser detection. Persisted for future sessions. See Languages
`options.noLocalStorage`	`boolean`	No	If `true`, the SDK won't use `localStorage`. The anonymous ID is regenerated on each page load
`options.hidden_fields`	`object`	No	Key-value pairs to identify the user at init time. Same as calling `identify` separately

warning

If noLocalStorage is true, each page load creates a new anonymous user. Use this only when you cannot use localStorage (e.g., strict privacy requirements).

IDENTIFY

Associate custom data with the current visitor. Use this to link survey responses to your authenticated users.

told('identify', {
  email: '[email protected]',
  userId: '123',
  name: 'Jane Doe',
  plan: 'enterprise',
});

Reset all previous data and replace with new fields:

told('identify', { email: '[email protected]' }, true);

Parameter	Type	Required	Description
`fields`	`object`	Yes	Key-value pairs of user data. You can pass any custom properties
`reset`	`boolean`	No	If `true`, clears all previous fields before setting the new ones

Special fields:

Field	Effect
`email`	Shown in the user profile in the Told dashboard
`id` or `userId`	Used to match users across sessions
`language`	Sets the user's language and persists it. Surveys and product tours that have a translation for this language will display in it; otherwise they fall back to the default language. See Languages

tip

Call identify as soon as the user logs in. This ensures all their survey responses are linked to their account.

identify is an alias for addHiddenFields — both work identically:

told('addHiddenFields', { email: '[email protected]' });

RESET

Clear all user data and generate a new anonymous ID. Call this when a user logs out.

told('reset');

This removes the stored anonymous ID and language from localStorage and creates a fresh anonymous session.

You can also trigger a reset by calling told('identify', null).

TRACK

Send a custom event. Events can be used as survey or product tour triggers.

told('track', { event: 'purchase_completed', amount: 49.99, currency: 'EUR' });

Parameter	Type	Required	Description
`eventData`	`object`	Yes	An object containing the event data
`eventData.event`	`string`	Yes	The event name (used to match triggers)
Other properties	any	No	Any additional data attached to the event

track is an alias for addEvent — both work identically:

told('addEvent', { event: 'signup_completed' });

Automatic event capture

The SDK automatically captures events from:

Google Analytics / GTM — If you push events to window.dataLayer, the SDK detects them and forwards the event name.
Segment — If you use window.analytics.track(), the SDK intercepts those calls too.

You don't need to call told('track') separately for events already sent through these tools.

START

Manually trigger a specific survey by its ID, bypassing the normal trigger rules.

told('start', 'SURVEY_ID');

Parameter	Type	Required	Description
`surveyID`	`string`	Yes	The survey ID (found in the survey URL or settings)

info

The survey must be activated (published). start bypasses trigger conditions (URL, scroll, click) but the survey still needs to be in an active state.

CLOSE

Close an active survey or product tour.

told('close', 'SURVEY_OR_PRODUCT_TOUR_ID');

Parameter	Type	Required	Description
`id`	`string`	Yes	The ID of the survey or product tour to close

GROUP

Associate the current user with a group (company). Groups let you segment users and view analytics by company.

told('group', 'company_123', { name: 'Acme Corp', plan: 'enterprise', employees: 50 });

Parameter	Type	Required	Description
`groupId`	`string`	Yes	A unique identifier for the group/company
`customData`	`object`	No	Key-value pairs of group metadata

LAUNCH PRODUCT TOUR

Manually launch a product tour by its ID.

told('launchProductTour', 'PRODUCT_TOUR_ID');

Force a new session (useful if the user already completed the tour):

told('launchProductTour', 'PRODUCT_TOUR_ID', { forceNewSession: true });

Parameter	Type	Required	Description
`productTourID`	`string`	Yes	The product tour ID
`options.forceNewSession`	`boolean`	No	If `true`, starts a fresh session even if the user already completed the tour

DEBUG

Display diagnostic information about your source and active surveys in the browser console.

told('debug', 'YOUR_SOURCE_ID');

If the SDK is already initialized, you can omit the Source ID:

told('debug');

The output includes information about the source configuration, active surveys, triggers, and any issues detected.

PREVIEW MODE

Test your surveys and product tours without publishing them by adding ?toldPreview to any page URL where the SDK is installed.

https://yourwebsite.com/page?toldPreview

To preview a specific survey or product tour, pass its ID:

https://yourwebsite.com/page?toldPreview=SURVEY_OR_TOUR_ID

You can also enable preview mode programmatically at init time:

told('init', 'YOUR_SOURCE_ID', { preview: true });

tip

Preview mode is useful for QA: triggers, audience rules, and "display only once" limits are bypassed. The parameter is automatically removed from the URL after detection, so it won't appear in shared links or analytics.

SHUTDOWN

Completely tear down the SDK: close all active surveys and product tours, remove the DOM container, and clean up event listeners. Use this when you need to fully remove Told from the page (e.g., in a SPA when navigating to a section where Told should not run).

told('shutdown');

After calling shutdown, the told() function is no longer available. You would need to reload the page to use the SDK again.

Automatic event capture (Segment & GTM)

The SDK automatically intercepts events from Google Tag Manager and Segment. You can use these events as survey or product tour triggers without any extra code.

Google Tag Manager / Google Analytics

Any event pushed to window.dataLayer is automatically captured:

// Your existing GTM code — no changes needed
dataLayer.push({ event: 'purchase_completed', value: 49.99 });

In the Told dashboard, create a trigger with type Custom event and set the event name to purchase_completed. The survey will trigger when this GTM event fires.

Segment

If you use Segment's analytics.track(), the SDK intercepts those calls automatically:

// Your existing Segment code — no changes needed
analytics.track('Plan Upgraded', { plan: 'enterprise' });

In the Told dashboard, create a trigger with type Custom event and set the event name to Plan Upgraded.

info

Automatic capture works as soon as the SDK is initialized. You don't need to call told('track') for events already sent through GTM or Segment.

Quick reference

Function	Syntax	Description
init	`told('init', sourceID, options?)`	Initialize the SDK
identify	`told('identify', fields, reset?)`	Set user data
reset	`told('reset')`	Clear user data and create new anonymous session
track	`told('track', eventData)`	Send a custom event
start	`told('start', surveyID)`	Manually trigger a survey
close	`told('close', id)`	Close an active survey or product tour
group	`told('group', groupId, customData?)`	Associate user with a group
launchProductTour	`told('launchProductTour', id, options?)`	Manually launch a product tour
debug	`told('debug', sourceID?)`	Show diagnostic info in the console
shutdown	`told('shutdown')`	Tear down the SDK entirely

Web SDK Functions

How the SDK works​

INIT​

IDENTIFY​

RESET​

TRACK​

Automatic event capture​

START​

CLOSE​

GROUP​

LAUNCH PRODUCT TOUR​

DEBUG​

PREVIEW MODE​

SHUTDOWN​

Automatic event capture (Segment & GTM)​

Google Tag Manager / Google Analytics​

Segment​

Quick reference​

Related pages​

How the SDK works

INIT

IDENTIFY

RESET

TRACK

Automatic event capture

START

CLOSE

GROUP

LAUNCH PRODUCT TOUR

DEBUG

PREVIEW MODE

SHUTDOWN

Automatic event capture (Segment & GTM)

Google Tag Manager / Google Analytics

Segment

Quick reference

Related pages