> For the complete documentation index, see [llms.txt](https://docs.spara.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.spara.com/developers/installation/query-parameters.md).

# 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](https://docs.spara.com/build/channels/chat) channel. 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 [HubSpot CRM](https://docs.spara.com/integrations/crm-integrations/hubspot-crm) or [Salesforce](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 a Spara [Chat](https://docs.spara.com/build/channels/chat) channel.

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

Query parameters are read from the page the visitor landed on as well as from the page where the chat starts, so a visitor who arrives from an ad and browses before chatting keeps their campaign tags. When both pages carry the same parameter, the chat page wins.

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](https://app.spara.co/settings/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. Only lead fields are offered: account and owner fields are filled by your CRM sync or the Leads API, not by query parameters.

<figure><img src="https://4187726466-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCvqVvd2zN1NKClKTrAOy%2Fuploads%2Fgit-blob-5296d22260c4d188c27d417295a304890fe741d5%2FScreenshot%202025-02-26%20at%201.23.32%E2%80%AFPM.png?alt=media" alt=""><figcaption></figcaption></figure>

## 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.

## Referrer

Spara also records the site a visitor came from, using the referrer their browser reports on the page they land on. It fills the `referrer` field and a normalized `traffic_source` field (for example `ChatGPT`, `Perplexity`, `Google`, or the referring domain). These browser-reported values are first-touch: they are set when the lead is first seen and are not overwritten by later visits.

If your site uses a cookie consent banner, the referrer is recorded only when the visitor grants Analytics consent. Consent given at any point during the visit counts, including after the visitor has started chatting: Spara holds the referrer in the browser for the visit and records it once consent arrives. Until then Spara keeps only `traffic_source`, and a site that is not a known source is recorded as `Other referral` instead of its domain. Query parameters on the page the visitor landed on are likewise carried to later pages only with Analytics consent.

If you pass your own referrer, by mapping a query parameter or a JavaScript field to `referrer`, your value is used and the browser's is ignored. A referrer you pass behaves like any other mapped field: it updates on every visit that carries it, and `traffic_source` is derived from it.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.spara.com/developers/installation/query-parameters.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
