JavaScript API: users, email, and events

To see a visitor's name and email in “Audience”, pass them from your application through the JavaScript API. You can then find the person in the list and view their activity history.

A website developer is needed to set up the integration. The code runs in the browser and calls widget methods when a user signs in, updates their details, or signs out.

Set up data collection

Open “Widget integration” in the sidebar:

1. Create a public key if you do not have one yet.
2. Under “Audience and event collection”, enable “Collect visitor data”.
3. In “Allowed website addresses”, enter your website address, such as https://app.example.com, without a page path or trailing /.
4. Choose a mode in “When to collect data” and click “Save settings”.

In “Only with consent” mode, your website must obtain the user's consent before sending their data. The order of calls is described below under “Consent to data collection”.

Install the widget

If the widget is already on your website, you do not need to install it again.

For a plain HTML website, add the widget script and a file containing your integration code:

<script
  defer
  src="https://app.flowtomate.ru/widget/v1/widget.js"
  data-flowtomate-key="pub_live_REPLACE_WITH_YOUR_KEY"
  data-flowtomate-api="https://api.flowtomate.ru">
</script>
<script defer src="/flowtomate-integration.js"></script>

Replace pub_live_REPLACE_WITH_YOUR_KEY with your project's key. It can be included in your website code. Your dashboard password and token are not needed here.

Your developer creates the /flowtomate-integration.js file and adds the calls from this guide. The defer attribute preserves execution order: the browser runs the widget script first, then your code.

GTM and React have a separate installation guide. When using async, GTM, or React, wait for the script to load before accessing window.FlowtomateWidget. Once the object is available, run await window.FlowtomateWidget.ready(), then proceed with the other calls.

Run examples containing await inside an async function or in the browser console on a test website. This code does not run on the server.

Consent to data collection

In “Only with consent” mode, connect the API calls to your website's consent banner. After the widget loads and the user consents, run:

window.FlowtomateWidget.setConsent('granted');

await window.FlowtomateWidget.identify('user_42', {
  email: 'anna@example.com',
  name: 'Anna'
});

This and the following examples use fictional data. In your code, use the current user's details.

Call setConsent('granted') after the user consents in the banner. Signing in does not itself provide that consent. Do not call identify, setTraits, or track before consent.

In “Without requesting consent” mode, a separate setConsent('granted') call is not needed. If the user has already declined data collection, that refusal remains in effect.

If the user declines or withdraws consent, call:

window.FlowtomateWidget.setConsent('denied');

The widget stops collecting data and clears the event queue. Stop calling identify and setTraits in your code as well: data passed to them after a refusal can be included in widget settings requests.

The unknown value removes the saved choice. In “Without requesting consent” mode, collection may continue afterward, so use denied for a refusal.

setConsent returns nothing. Adding await will not wait for the settings to take effect. See the consent guide for details.

Send the user's ID and email

Call identify after the user signs in:

await window.FlowtomateWidget.ready();

await window.FlowtomateWidget.identify('user_42', {
  email: 'anna@example.com',
  name: 'Anna',
  plan: 'pro',
  role: 'admin',
  company_id: 'company_17'
});

The first argument, user_42, is the user's ID in your system. Send the same ID when they sign in again or use another device. If you store the ID as a number, convert it to a string: String(user.id).

The other fields describe the user:

Field	What to send
email	The email address you will use to find the profile.
name	The name shown in the profile.
plan	The plan, such as pro.
role	The role in your product, such as admin.
company_id	The company ID. It is saved as a user field; no separate company profile is created.

You can add your own fields. Send all values as strings: seats: '12', onboarding_done: 'true'. Use Latin letters, digits, _, -, and . in field names. The flowtomate. prefix is reserved for system fields. The API does not accept nested objects.

Keep email in a separate field: it can change, while the ID must stay the same. Flowtomate does not merge profiles with different IDs based on a matching email address. Do not send passwords, tokens, or bank card details.

Once the data is saved successfully, you can find the user in “Audience” with the “Identified” status. Their profile also includes any activity the widget collected in this browser before sign-in.

Call identify after sign-in and on page reload, once your application has received the current user's details. If the application changes pages without reloading, you do not need to repeat the call on every navigation.

Update email, plan, or other fields

Use setTraits to update user details:

await window.FlowtomateWidget.setTraits({
  email: 'anna.new@example.com',
  plan: 'team'
});

Call identify first to associate the visitor with an ID. Then pass only the changed fields through setTraits. Other values remain unchanged. The widget also refreshes its content based on the new details.

Omitting a field does not delete it. This API has no separate method for deleting a field.

Record a user action

Call track after the relevant action. For example, after a report is successfully created:

window.FlowtomateWidget.track('report_created', {
  report_type: 'sales',
  rows: 120,
  shared: false
});

In this example, report_created is the event name, and the other fields contain report details. These values can be strings, numbers, true, false, null, and arrays of strings or numbers. Send email and name through identify or setTraits.

Use lowercase Latin letters, digits, and _ for the event name. Start with a letter and keep it within 100 characters. The prefixes flowtomate_, popup_, checklist_, tour_, page_, session_, survey_, feedback_, hint_, and onboarding_ are reserved for system events. See the events documentation for other limits.

The widget sends events in batches. The track method returns nothing, so a call alone does not tell you whether the data arrived. Check the event in the dashboard. In required-consent mode, events sent before consent are not saved for later delivery.

Call reset on sign-out

When the user signs out, run:

await window.FlowtomateWidget.reset();

The widget clears the current user ID and fields, starts a new anonymous session, and resets the state of displayed content. The profile and history in the dashboard are retained, as is the consent choice.

When switching accounts, wait for the reset, then send the new user's details:

await window.FlowtomateWidget.reset();
await window.FlowtomateWidget.identify('user_73', {
  email: 'pavel@example.com',
  name: 'Pavel'
});

If you need to request consent again, use await window.FlowtomateWidget.reset({ clearConsent: true }). In “Only with consent” mode, wait for new consent before calling identify.

Use reset() for sign-out. The destroy() method removes the widget from the page and does not clear saved user data.

Verify that the data arrived

Check the integration in a test project or with a test user:

1. Open the website listed in the project settings and wait for the widget to load. If needed, give consent through the banner.
2. Call identify with a test ID and email. In the dashboard, open “Audience” and find the profile. Check for the “Identified” status and the fields you sent on the “Overview” tab.
3. Change plan through setTraits. Reload the dashboard page and check the new plan.
4. Call track('report_created', { report_type: 'sales' }). After it is sent, find the event on the profile's “Events” tab.
5. Reload the website and sign in as the same user. They should retain the same profile. Then sign out and sign in with another test account: new actions should appear under that account.

A ready() call alone does not confirm that settings loaded or data was saved. Check the result in the dashboard.

If something is not working

Handle errors from calls using await with try/catch. For example, after the script loads and you obtain the required consent:

try {
  const widget = window.FlowtomateWidget;
  if (!widget) throw new Error('The Flowtomate script did not load');

  await widget.ready();
  await widget.identify('user_42', { email: 'anna@example.com' });
} catch {
  console.warn('Could not send user details to Flowtomate');
}

Problem	What to check
window.FlowtomateWidget is missing	Wait for widget.js to load. Check script order and CSP errors in the console.
The user remains anonymous	Check the identify call: the ID must be a nonempty string. Make sure collection is enabled, the website address is allowed, and the required consent has been obtained.
The email cannot be found	Check the email field in identify or setTraits, the selected project, and network errors.
One person has several profiles	Compare the IDs sent on different sign-ins and devices.
Actions are attributed to the previous user	Call reset() on sign-out and wait for it before the next identify.
An event is missing	Check consent, the event name and fields, and network errors.
Settings changed, but data is not arriving	Save the settings and reload the website page.

More checks are available in the troubleshooting guide. When asking for help, do not publish real user data or tokens.

Open popups, tours, and other content

The API can open content from buttons on your website. Pass the content ID; feedback also accepts a key.

Task	Call	Result
Open a popup	await window.FlowtomateWidget.openPopup('POPUP_ID')	true if it opens; otherwise false. Enable manual launch in the popup settings.
Start a tour	await window.FlowtomateWidget.startTour('TOUR_ID')	A started, pending, ineligible, or not_found status in the response object.
Open a checklist	window.FlowtomateWidget.openChecklist('CHECKLIST_ID')	Returns nothing.
Open feedback	window.FlowtomateWidget.openFeedback('FEEDBACK_ID')	Returns nothing.
Refresh settings and content	await window.FlowtomateWidget.refresh()	Wait for the refresh with await; handle errors in catch.
Get the version	window.FlowtomateWidget.version	The version number as a string.

The content must be published and loaded into the widget. Enable manual launch for a manual popup; tours follow their display rules. Wait for ready() before opening a checklist or feedback. See the manual launch guide for examples and reasons why content may not open.

The JavaScript API reference describes the full list of methods and the call queue available before the widget loads. There is currently no separate public REST API for sending audience data and events from your server.