JavaScript API

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

Reading Javascript events from Spara

Spara's JavaScript API exposes two 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. So another way to See Query Parametersfor more information

Opening Spara Navigator using Javascript

In addition, Spara provides a JS function to dynamically open Spara Navigator: SparaAction.openChat It has 2 options: aiMessage & userMessage.

For example, SparaActions.openChat({ userMessage: 'Hi' }) opens Spara Navigator with the user sending a message "Hi."

In another example, SparaActions.openChat({ aiMessage: 'How can I help?' }) opens Spara Navigator with Spara's AI saying "How can I help" to start the thread. Note that aiMessage will only create a new message for an empty thread.

How to open Spara Navigator when a user clicks a CTA

A common interaction is for Spara Navigator to load in a "closed" state, but "magically" open when a website visitor clicks a CTA.

To accomplish this:

Set Navigator to load in Spara Navigator. Website visitors will only see the bottom right avatar on page load.
Write a brief Javascript snippet that opens Spara Navigator when a CTA is clicked.

// Example assumes CTA button has id="cta"
document.getElementById('cta')?.addEventListener('click', () => {
  SparaActions.openChat({ aiMessage: 'How can I help?' });
});

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}}'
});

Last updated 3 days ago

Good night

hashtagReading Javascript events from Spara

hashtagWriting information to Spara using Javascript

hashtagNote on Query Parameters

hashtagOpening Spara Navigator using Javascript

hashtagHow to open Spara Navigator when a user clicks a CTA

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

hashtagSupported Identifiers

hashtagStep 1: The "Universal" Tracking Script

hashtagStep 2: Create "Reader" Variables

hashtagStep 3: Verification (QA)

hashtagStep 4: Passing IDs to Spara