Ctrlk

Query Parameters

How to pass information into Spara via query parameters.

Spara can ingest any query parameter on any webpage that loads a Spara Chat Agent. This is true at any point that Spara is loaded; the query parameters can be added even after Spara is instantiated.

Why use query parameters?

Query parameters are the simplest way to tell Spara who a lead is and where they came from. Passing them on page load unlocks a few key capabilities:

  • Identify the lead before the conversation starts. When a lead arrives with parameters like email or first_name, Spara recognizes them immediately rather than asking for the same information again.

  • Personalize the chat experience. Lead context is available to your chat agent from the very first message, so the conversation can be tailored to who the lead is, what page they came from, or what campaign brought them there.

  • Sync marketing data into your CRM. UTM parameters (utm_source, utm_campaign, etc.) and any custom lead fields you pass via query parameters flow into Spara fields, which can be mapped to CRM properties via https://docs.spara.com/integrations/crm-integrations/hubspot-crm or https://docs.spara.com/integrations/crm-integrations/salesforce.

  • Power attribution, routing, and downstream workflows. Once a lead's source and identity are known, Spara can route them to the right calendar, trigger the right workflow, and attribute the conversion back to the campaign that drove the visit.

Step 1: Add query parameters to URLs

Add query parameters to the URL of any webpage that loads Spara Chat Agents.

For example, let's say that ACME's sales journey is...

  • Leads submit a webform at acme.com/form. This form includes fields for first name and email address.

  • Upon form submission, the lead is redirected to acme.com/chat, which loads the Spara Fullscreen interface.

The correct way to handle this redirect is by including URL-encoded query parameters for form fields first name and email address:

https://acme.com/chat?FirstName=John&Email=john%40company.com

Spara Fullscreen is then loaded already knowing the lead's first name and email address.

Step 2: Map query parameters

Spara automatically maps the below standard marketing UTM parameters, along with key user fields:

  • utm_campaign

  • utm_source

  • utm_medium

  • utm_campaign

  • utm_term

  • utm_content

  • email

  • first_name

  • last_name

  • company_name

All other query parameters must be mapped to Spara fields. This is how Spara knows which query parameters are relevant and what they mean.

  • Navigate to Chat > Configuration

  • Click "Add Field +" to add a new mapping

  • In "Your field," type in the exact query parameter key

  • In "Spara field," select or add the field

How do Spara fields work?

Some notes on how Spara fields work:

  • Fields are persisted across all user sessions.

  • Each field may only have a single value.

  • Any field may be overwritten at any time. Fields are never deleted or overwritten by null or none.

For example, consider the following scenario in which Spara is loaded on every acme.com webpage:

  • Anonymous Lead 123 visits acme.com?utm_campaign=twitter and talks to Spara. Throughout the conversation, Lead 123 navigates to multiple acme.com webpages.

  • 24 hours later….Anonymous Lead 123 visits acme.com/pricing?utm_source=google. They do not talk to Spara.

  • 6 days later…Anonymous Lead 123 visits acme.com?utm_campaign=linkedin. They talk to Spara.

After all three sessions, Anonymous Lead 123 has the following fields set in Spara's database:

  • utm_campaign=linkedin

  • utm_source=google

Note that utm_campaign=twitter was set in at the start of the first session, but then overwritten to utm_campaign=linkedin by the third session.

Last updated