Javascript API

How to leverage JavaScript to read and/or write data to Spara.

Subscribing to Spara conversion events

SparaActions exposes subscription methods for conversion events from any Spara widget — chat, voice, and AI Product Demo. This is the recommended way to feed Spara events into Google Tag Manager, GA4, Google Ads, or LinkedIn Ads conversion tracking.

SparaActions.onCtaClick(handler) — the visitor clicked a conversion CTA, e.g. Talk to Sales in a Product Demo. Payload: { label, url?, formFactor }
SparaActions.onMessageSent(handler) — the visitor sent a chat message. Payload: { text, formFactor }
SparaActions.onMeetingBooked(handler) — the visitor completed a calendar booking. Payload: { formFactor }
SparaActions.onEmailCaptured(handler) — the visitor's email address was captured and confirmed. Payload: { email, formFactor }
SparaActions.onDemoStarted(handler) — an AI Product Demo was opened. Payload: { formFactor }
SparaActions.onDemoEnded(handler) — the Product Demo closed. Payload: { formFactor, reason, durationSeconds }, where reason is call_ended (the demo ran to completion) or closed_early (the visitor closed it)

Every payload includes a formFactor field identifying which widget the event happened in: NAVIGATOR, SMARTBAR, FULLSCREEN, ASK_BAR, PRODUCT_DEMO, or SCHEDULING — the same form-factor vocabulary used across Spara analytics.

If a visitor closes the browser tab mid-demo, no onDemoEnded event fires, so started/ended counts won't reconcile exactly.

You can register handlers at any time — before or after the embed script loads — and register multiple handlers for the same event (e.g. one from your site code and one from a GTM tag). For example, pushing Product Demo conversions to the GTM data layer:

<script type="text/javascript" src="https://app.spara.co/embed-<app_id>.js"></script>
<script>
  SparaActions.onMeetingBooked(function (e) {
    window.dataLayer = window.dataLayer || [];
    window.dataLayer.push({ event: 'spara_meeting_booked', spara_form_factor: e.formFactor });
  });
  SparaActions.onCtaClick(function (e) {
    if (e.formFactor === 'PRODUCT_DEMO' && e.label === 'talk_to_sales') {
      window.dataLayer.push({ event: 'spara_demo_talk_to_sales' });
    }
  });
  SparaActions.onEmailCaptured(function (e) {
    window.dataLayer.push({ event: 'spara_email_captured', spara_form_factor: e.formFactor });
  });
</script>

Reading Javascript events from Spara

The window.Spara callbacks below still work, but they support only one handler each and don't identify which widget an event came from. Prefer the SparaActions.on* subscriptions for new integrations.

Spara's JavaScript API exposes three events to the DOM:

Spara.onSparaLoad() fires when Spara's embed script finishes executing
Spara.onUserMessageSent() fires when a lead sends message to Spara
Spara.onUserScheduled() fires when a lead schedules a call

These can be used however you like. For example, by pushing these events to your window's data layer for ingestion by Google Analytics.

To access these Javascript events, you will need to add an additional script to your website's <head>:

<script type="text/javascript" src="https://app.spara.co/embed-<app_id>.js"></script>
<script>
  Spara = {
    onSparaLoad: () => {
        console.log("Spara is loaded! 🎬");
    },
    onUserMessageSent: (text) => { 
        console.log("User sent a message to Spara 💬");
    },
    onUserScheduled: () => {
        console.log("User has scheduled a call");
    }
  }
</script>

Writing information to Spara using Javascript

Spara's Javascript API exposes methods to write information to Spara Lead objects. For more information on how leads are represented in our database see our documentation on Lead Schema.

SparaActions.setFields accepts a dictionary of arbitrary key/value pairs assigned to the current website visitor. For example:

SparaActions.setFields({
  acme_uuid: '1234567',  // This is an arbitrary field and value
  experiment_group: 'control'
}

To specifically send Spara information on page load, you will need to add an additional Javascript snippet immediately after initializing Spara's Javascript embed.

Here is a full example, which sets the current visitor's "ACME uuid" field:

    <script type="text/javascript" src="https://app.spara.co/embed-<app_id>.js"></script>
    <script>
      Spara = {
        fields: {
          acme_uuid: '1234567'  // This is an arbitrary field and value
        }
      }
    </script>

Note on Query Parameters

A reminder that Spara automatically ingests all query parameters from your webpages, as long as they are mapped in the Spara platform. See Query Parameters for more information.

Opening Spara using Javascript

Spara provides JS functions to dynamically open Spara Navigator, Smartbar, and Product Demo.

SparaActions.openChat() - opens Navigator
SparaActions.openSmartbarChat() - opens Smartbar
SparaActions.openProductDemo() - opens Product Demo

openChat and openSmartbarChat accept the same optional arguments:

userMessage - prefills and sends the lead's (i.e. user's) message
aiMessage - starts the chat with a Spara-generated (i.e. AI) message

For example, SparaActions.openChat({ userMessage: 'Hi' }) opens Spara Navigator with the user sending a message "Hi." See the FAQ for a full CTA-click walkthrough.

How to open Product Demo from a link or email CTA

Use SparaActions.openProductDemo() to launch a Product Demo session programmatically. A common use case is linking to your website from an email campaign and having the Product Demo open automatically when the visitor arrives.

To set this up:

Add a query parameter to your link (e.g., ?demo or ?open_product_demo=1)
On your website, include JavaScript that checks for this parameter and calls openProductDemo()

// Check for ?demo in the URL and open Product Demo if present
if (window.location.search.includes('demo')) {
  SparaActions.openProductDemo();
}

For email campaigns, append the query parameter to your landing page URL. For example, linking to https://yoursite.com/?demo will open the Product Demo when the visitor arrives.

UTM parameters like utm_source and utm_campaign are automatically captured by Spara when the page loads, so you can combine the demo trigger with your usual campaign tracking (e.g., https://yoursite.com/?demo&utm_source=newsletter).

How do I set up persistent ad tracking in Google Tag Manager?

To better attribute Spara conversions to your advertising campaigns (LinkedIn, Google, Facebook), you must capture and store "Click IDs" from the URL when a visitor first arrives.

A Click ID is a unique identifier that tracks a user’s click from an ad to your website.

Because users often browse multiple pages before engaging with the Spara AI agent, we cannot rely on the URL remaining the same. This guide shows you how to use Google Tag Manager (GTM) to save these IDs into a First-Party Cookie that follows the user for 90 days.

Supported Identifiers

This setup automatically handles the following industry-standard tracking parameters:

gclid (Google Click ID)
wbraid / gbraid (Google iOS Privacy-compliant IDs)
li_fat_id (LinkedIn First-Party Tracking)
fbclid (Facebook Click ID)

Step 1: The "Universal" Tracking Script

We will create a single tag that handles all major ad networks. This script checks the URL for any of the supported IDs and saves them as a secure cookie on your root domain.

Open Google Tag Manager.
Go to Tags > New.
Tag Type: Select Custom HTML.
Name: Script - Universal Ad Tracking.
HTML Content: Copy and paste the code block below.
Action Required: Edit the config.domain line to match your website's root domain (e.g., .spara.co).

<script>
/**
 * SPARA.CO UNIVERSAL TRACKING SCRIPT
 * Captures ad parameters from URL and stores them in 90-day cookies.
 */
(function() {
    // --- CONFIGURATION ---
    var config = {
        domain: '.yourdomain.com', // REPLACE with your root domain (with leading dot)
        expiryDays: 90,            // Attribution window
        path: '/'
    };


    // Mapping: URL Parameter -> Cookie Name
    var idMap = {
        'gclid':     'gclid',
        'wbraid':    'wbraid',
        'gbraid':    'gbraid',
        'li_fat_id': 'li_fat_id',
        'fbclid':    'fbclid'
    };
    // ---------------------


    // Helper: Get Query Param
    function getParam(name) {
        var match = RegExp('[?&]' + name + '=([^&]*)').exec(window.location.search);
        return match && decodeURIComponent(match[1].replace(/\+/g, ' '));
    }


    // Helper: Set Cookie
    function setCookie(name, value) {
        var date = new Date();
        date.setTime(date.getTime() + (config.expiryDays * 24 * 60 * 60 * 1000));
        var expires = "expires=" + date.toUTCString();
        document.cookie = name + "=" + value + ";" + expires + ";domain=" + config.domain + ";path=" + config.path;
    }


    // Execution Logic
    // We loop through the map. If a param exists in the URL, we save/overwrite the cookie.
    // If it does NOT exist, we do nothing (preserving any existing cookie).
    for (var paramKey in idMap) {
        var paramValue = getParam(paramKey);
        if (paramValue) {
            setCookie(idMap[paramKey], paramValue);
        }
    }
})();
</script>

Triggering:
1. Click Triggering.
2. Select All Pages (or Initialization - All Pages).
3. Why? This ensures that if a user lands on any page via an ad, the ID is captured immediately.
Save the tag.

Step 2: Create "Reader" Variables

Now that the cookies are being created, you need GTM variables to "read" them so you can pass the data to Spara or other tools.

Go to Variables.
Under User-Defined Variables, click New.
Variable Type: 1st Party Cookie.
Cookie Name: li_fat_id (Must match the name in the script map above).
URI Decode Cookie: ☑️Check this box.
Name: Cookie - li_fat_id.
Save.

Repeat this process for gclid, wbraid, and any others you need.

Variable Name

Cookie Name

Cookie - gclid

gclid

Cookie - wbraid

wbraid

Cookie - li_fat_id

li_fat_id

Step 3: Verification (QA)

Before publishing, verify the setup works using the GTM Preview mode or your browser's developer tools.

Visit your site with a fake ID:
https://www.yourdomain.com/?li_fat_id=TEST_123&gclid=TEST_456
Inspect the Cookies:
Right-click the page > Inspect.
Go to the Application tab (Chrome) or Storage tab (Firefox).
Expand Cookies on the left and select your domain.
Confirm the Data:
You should see li_fat_id with value TEST_123.
You should see gclid with value TEST_456.
Domain: Ensure it shows .yourdomain.com (this confirms it will work across subdomains).
Expires: Ensure the date is roughly 90 days in the future.

Step 4: Passing IDs to Spara

Once the variables are created, you can pass them into Spara via Spara's Javascript API.

If you are initializing Spara via GTM, update your Spara Initialization Tag to include these variables:

// Example Spara Identification Call
Spara.identify({
  email: '[email protected]',
  // Pass the GTM Variables we created in Step 2
  gclid: '{{Cookie - gclid}}', 
  li_fat_id: '{{Cookie - li_fat_id}}',
  wbraid: '{{Cookie - wbraid}}'
});

FAQ

How do I make a CTA button open Spara chat with a specific opening message?

A common pattern is to have a CTA on your page — for example, a "Request a Demo" button — that opens Spara Navigator with a page-specific opening message rather than the generic default. Use SparaActions.openChat() together with the aiMessage option to inject the opening message at click time.

For example, on a pricing page:

// Example assumes CTA button has id="request-demo"
document.getElementById('request-demo')?.addEventListener('click', () => {
  SparaActions.openChat({
    aiMessage: "Happy to walk you through pricing — what plan are you considering?"
  });
});

This lets each page provide contextual messaging — a pricing page can lead with a pricing question, a features page can lead with a product question — instead of every CTA opening to the same generic greeting.

To make this work, Navigator should be loaded in Preview Mode: Hidden so the chat only appears when the CTA is clicked.

Last updated 15 days ago