> This is part 1 of 2 of the full documentation (pages 1–100 of 142).
> The content is paginated: fetch every part to see all of it.
> Next part: https://docs.spara.com/llms-full.txt/1
> Page index: https://docs.spara.com/llms.txt

# 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
This site has an agentic ask interface you may use to query the documentation dynamically 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/index.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.

---

# Welcome to Spara

An introduction to Spara

Spara engages your leads in real-time to prequalify them, answer their personalized questions, and demo your product - **driving more qualified leads to your sales reps faster.**

We believe that every company should provide their leads with the ideal buying experience. We know what this looks like - companies with multimillion dollar enterprise contracts roll out the red carpet with multiple personalized touchpoints and demos. Spara makes this type of sale possible at scale, for every potential customer at any price point.

Spara is a complete solution for hybrid AI & human GTM motions. This includes:

* **Agents:** Spara is the first AI that actually sells to your buyers. It knows your pitch cold and it can elegantly handle any question thrown at it. Spara communicates to your buyers via chat, email, and voice channels.
  * [Chat](/build/channels/chat)
  * [Email](/build/channels/email)
  * [Phone](/build/channels/phone)
* **Platform:** An easy-to-use no-code platform for sales teams to manage, analyze, and test Spara's performance over time. Everything is SOC2 compliant and designed for large enterprises.
  * [Leads](/pipeline/leads) and [Accounts](/pipeline/accounts) pages for understanding engagement
  * [Analytics](/pipeline/analytics) for understanding performance
  * [Knowledge](/build/knowledge) and [Media](/build/channels/chat/media) are documents, videos, PDFs, etc. that your agent is trained on. Your agent will dynamically look up this information on an as-needed basis.
  * [Testing](/build/testing) interfaces let you easily test and play with your Spara agents before publishing.
  * [Settings](/platform/settings)
* **Scout:** The AI sales assistant for reps. Scout works each rep's whole book around the clock in Slack and by text: it watches their accounts, inbox and CRM, and hands them the next move already drafted in their own inbox. Nothing sends until the rep sends it. See the [Scout documentation](https://docs.spara.com/scout).

### What business problems does Spara solve?

Spara is built to work for many different use cases at the top of your sales funnel. Our AI's behavior, goals, information gathered from leads, and more are completely configurable. Most customers deploy Spara for multiple of these use cases, with multiple starting points in the sales journey.

### Real-time Prequalification

Spara is built to automate inbound prequalification, achieving higher conversion to an AE than a traditional SDR-led process. Simply insert Spara on your marketing website, either after or instead of your marketing web form.

Why does Spara achieve better prequalification conversion than a traditional SDR-led prequalification call? Because it's a better buying experience for your leads. Here's why:

<table><thead><tr><th width="276"></th><th>Traditional SDR Call</th><th>Spara</th></tr></thead><tbody><tr><td>How quickly can you answer a lead's questions?</td><td>~4 day delay to AE call</td><td>Immediate</td></tr><tr><td>How quickly can you show a lead how your product works?</td><td>~4 day delay to AE call...and even they may not show you a demo at first</td><td>Immediate</td></tr><tr><td>How quickly can you schedule a call with an AE?</td><td>~4 day delay to AE call</td><td>Immediate</td></tr></tbody></table>

All of that delay causes up to 50% dropoff at the top of your sales funnel. Spara is here to help!

As an example, let's say that ACME is using Spara for prequalification. ACME needs a lot of information from a lead to schedule an AE call, more than can be captured on a marketing web form. Here's how it works:

* The lead clicks "See a Demo" on ACME's marketing page.
* The lead lands on ACME's "Demo" page, which is powered by Spara.
* Spara walks through the demo, answering the lead's questions as they come up.
* Along the way, Spara asks ACME's required prequalification questions. Unlike in a web form, the lead is more likely to answer because she is getting the information and experience that she wants.
* After ascertaining that the lead qualifies, Spara shifts the conversation to scheduling a call with ACME's sales team. Spara shows the lead an embedded calendar form in its main media section.

### Schedule Calls

Spara can push leads to schedule a call with your sales team. This behavior is completely configurable - you can decide when Spara's AI should drive the conversation towards scheduling a call.

Calendars are embedded within Spara. Both [Chili Piper](/integrations/calendar-integrations/chili-piper-concierge) and [Calendly](/integrations/calendar-integrations/calendly) calendars are supported.

As an example, let's say that Gong.io only wants to schedule calls with companies >100 employees. The video below shows a normal progression with Spara:

* The lead lands on Gong's "Demo" page, which is powered by Spara.
* Spara (i.e. Katherine Moss) walks through the demo, answering the lead's questions as they come up.
* Along the way, Spara unearths the lead's intent. Why are they interested in Gong? What features are they excited about?
* After ascertaining that the lead qualifies, Spara shifts the conversation to scheduling a call with Gong's sales team. Spara shows the lead an embedded calendar form in its main media section.
* Upon successfully scheduling a call, Spara ends the conversation with a natural signoff message to the lead.

### Gather Intent

Spara is an effective tool for gathering lead intent data. This behavior is completely configurable - you can decide what types of signals Spara's AI should learn about. Some common intent signals:

* What problem is the lead trying to solve?
* Why are they interested in your solution?
* What features are they most excited about?
* What requirements do they have?

All of this is possible because Spara's AI is having a real sales conversation with the customer.

As an example, let's say that Acme Inc. wants data on leads' buying urgency. This could happen before, after, or instead of a sales rep speaking to the lead. The video below demonstrates this behavior:

* The lead lands on Acme's "Demo" page, which is powered by Spara.
* Spara walks through the demo, answering the lead's questions as they come up.
* Along the way, Spara asks the key intent question: "Are you currently dealing with a workplace investigation?"
* Spara parses the lead's response and continues with the conversation.
* Spara can then immediately notify Acme's sales team of a customer with urgent buying intent.

### Automated Demos

Spara can provide live, interactive demos to anyone who visits your site. This does not require complex point-and-click set up or engineering environment maintenance. Best of all, Spara gets better over time as it learns what elements of your pitch are most engaging to your leads.

As an example, Rho wants to demo their product to anyone who has just scheduled a call with their sales team. That way, leads show up to the call with a greater understanding of Rho's value prop and the sales rep has more information about what the lead is interested in. Here's how it works:

* The lead fills out Rho's marketing web form. (A sales rep will contact them via email to schedule a call)
* Immediately after web form submission, the lead is redirected to Rho's "Demo" page, which is powered by Spara.
* Spara (i.e. Katherine Moss) walks through the demo, showing how Rho's platform works and answering the lead's questions as they come up.
* Along the way, Spara unearths the lead's intent. Why are they interested in Rho? What features are they excited about?
* The demo may last as long as the lead is interested. Afterwards, Spara uploads the conversation into Salesforce for the sales rep to review before her call with the lead.


# Agents

How Spara Agents can solve a complete business problem.

An **Agent** in Spara solves a complete business problem: qualifying inbound leads, re-engaging form fills, running outbound follow-up, or delivering self-serve demos. Rather than configuring a single chatbot in isolation, you build one Agent that engages buyers across every channel and coordinates the work needed to move them through your funnel.

Each Agent is made up of two kinds of building blocks:

* [Channels](/build/channels): a real-time conversation channel. It's where a buyer directly interacts with an agent. Each capability is configured with its own trigger, instructions, tools, and A/B variants.
  * [Chat](/build/channels/chat), [Email](/build/channels/email), [Phone](/build/channels/phone), [SMS](/build/channels/sms), [Product Demo](/build/channels/product-demo)
* [Workflows](/build/workflows): a proactive playbook of steps your agent executes. It's triggered by an event, such as "Lead left the chat." Workflows chain multiple steps together: send an email, wait 24 hours, make a phone call, check a condition, etc.
  * [Send Email Step](/build/workflows/steps/send-email), [Send Text Step](/build/workflows/steps/send-text), [Call Phone Step](/build/workflows/steps/call-phone), [Notify Step](/build/workflows/steps/notify), [Wait Step](/build/workflows/steps/wait), [Condition Step](/build/workflows/steps/condition), [API Step](/build/workflows/steps/api), [Research Step](/build/workflows/steps/research)

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-7521cc43eabac7979ed34b2ee50f7c100f90d148%2FAgent%20Diagram.svg?alt=media" alt=""><figcaption><p>An Agent coordinates capabilities (the channels it engages buyers through) and workflows, its background automations.</p></figcaption></figure>

For example, an Agent built for **MQL conversion** could weave together Chat, Email, and Phone capabilities with multiple workflows to drive more qualified meeting bookings.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-8192b8f7a71f99510b6b0b689b8aaacf04ec719f%2FAgent%20Diagram%20Example.svg?alt=media" alt=""><figcaption><p>An MQL conversion Agent weaving together Chat, Email, and Phone capabilities with multiple workflows.</p></figcaption></figure>

However different the channels look, every capability is built and run the same way. See [Configuring Channels](/build/channels/configuring).

## The Agents page

The [**Agents**](https://app.spara.co/agents) page is where you create and manage every Agent in your account. Each Agent in the list shows its name and goal, the capabilities and workflows it contains, and how many are published versus still in draft, so you can see your whole go-to-market motion at a glance.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-4673dd5354cae4416994c08103b251f3246ccd00%2FAgents%20Overview.png?alt=media" alt=""><figcaption><p>The Agents page lists every Agent in your account, each solving a complete business problem across channels.</p></figcaption></figure>

## Creating an Agent

There are two ways to create an Agent:

* **Start from a template**: the fastest way to launch. Spara provides proven templates for common go-to-market motions, each pre-built with the capabilities, workflows, and starting instructions for that use case.
* **Start from scratch**: create an empty Agent, give it a Goal, and add capabilities and workflows yourself.

Once the Agent exists, open it to configure what's inside. For a step-by-step walkthrough, see [Guide: Building an Agent](https://docs.spara.com/guides/platform-guides/building-an-agent).

## Templates

Templates are complete, ready-to-edit Agents for the most common sales and marketing plays, for example **Inbound Lead Qualification**, **Event & Webinar Follow-Up**, **Expansion & Cross-Sell**, and **Inbound Phone Calls**. They're grouped by team (Sales, Marketing, Customer Success) so you can find the right starting point quickly.

Browse them on the **Templates** tab of the Agents page. Picking a template creates a new Agent pre-loaded with the relevant capabilities and workflows, along with starting AI instructions. A template is a starting point, not a finished product. Review and customize the instructions, triggers, and content to fit your business before publishing.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-d675777f96d9fbd6c76246fd1c24224ac236e8f2%2FAgent%20Templates.png?alt=media" alt=""><figcaption><p>Start a new Agent from a proven template, or build one from scratch.</p></figcaption></figure>

## Restricting who can edit an Agent

By default, anyone whose role has full access to Agents can change any Agent in your account. When one team owns an Agent, a Manager can restrict it so that only the people on its member list can edit or publish what's inside.

Open the Agent, click **Manage** in its overview, and find **Access**. Turning on the restriction and picking members takes effect immediately:

* **Members and Managers** can change every channel and workflow in the Agent, add new ones, and move channels or workflows in or out.
* **Everyone else** sees the Agent and its channels read-only, with a note that it is restricted. Moving a channel between two Agents needs access to both.
* A member's role is still the ceiling: restricting an Agent never gives a member more than their role allows. A Contributor on the list can edit but not publish.

A restricted Agent shows a **Restricted** badge on the Agents page. Roles themselves are managed in [**Settings > Team**](https://app.spara.co/settings/team); see [User Management](/platform/settings/user-management).

## FAQ

### What's the difference between an Agent and a capability?

An Agent is the business problem you're solving; a capability is one channel it uses to do that. A single "Inbound Sales" Agent might have a Chat capability on your pricing page, a Phone capability on your sales line, and an Email capability for follow-up — all working toward the same Goal.

### Can one Agent have multiple capabilities of the same type?

Yes. An Agent can have several Chat capabilities, each with its own trigger (for example, one for `/pricing` and one for `/demo`), or multiple variants of the same capability running as an [A/B Testing](/build/channels/configuring/a-b-testing).

### Do capabilities share context with each other?

Capabilities operate on the same lead record, so information a lead shares in one channel is available to the Agent in another. Chat interfaces in particular share a single conversational thread. See [Chat](/build/channels/chat).

### Do I have to use a template?

No. Templates are an optional head start. You can build any Agent from scratch and add exactly the capabilities and workflows you need.

### Will a template change my existing Agents?

No. Creating an Agent from a template adds a new Agent to your account. It doesn't modify anything you've already built.


# Channels

The channels an Agent engages buyers through, and the anatomy shared by all of them.

A **channel** is one way an [Agents](/build/agents) engages buyers. Spara offers five:

* [Chat](/build/channels/chat): website chat that qualifies visitors, surfaces content, and books meetings in real time.
* [Email](/build/channels/email): automated reply handling and outreach cadences.
* [Phone](/build/channels/phone): incoming and outgoing AI phone calls.
* [SMS](/build/channels/sms): text-message conversations.
* [Product Demo](/build/channels/product-demo): a live, voice-narrated product walkthrough with synchronized visuals.

An Agent can have several channels (even several of the same type), each activated by its own trigger. Together they let one Agent meet a buyer wherever they are.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-fdbc679f5812412cac7ae26dbece43414a72fdbb%2FChannel%20Overview.png?alt=media" alt=""><figcaption><p>A channel's Overview tab summarizes what makes it up.</p></figcaption></figure>

## How channels are built

However different the channels look to a buyer, every channel is configured and run the same way: the same editor, the same draft-and-publish lifecycle, the same testing and optimization tools. Those shared building blocks are covered under [Configuring Channels](/build/channels/configuring):

* [AI Instructions](/build/channels/configuring/ai-instructions): the prompt that defines how a channel behaves.
* [Abilities](/build/channels/configuring/abilities): tools it can use mid-conversation.
* [Testing](/build/channels/configuring/testing): validate a draft before going live.
* [Ask Spara](/platform/ask-spara): draft, analyze, and rewrite instructions from the editor.
* [Saving & Publishing](/build/channels/configuring/saving-and-publishing): drafts and the single live version.
* [A/B Testing](/build/channels/configuring/a-b-testing): split traffic across variants to optimize conversion.

## Starting criteria

Every channel has a **trigger** that determines when it activates: a Chat channel might appear only on certain pages, a Phone channel answers a specific phone number, an Email channel replies from a connected inbox. Triggers are also how Spara groups channels for [A/B Testing](/build/channels/configuring/a-b-testing): variants that share a trigger split its traffic.


# Chat

An overview of Spara's Chat channel and its interfaces.

The **Chat channel** is Spara's website AI. It engages visitors in real-time conversations, qualifies leads, surfaces relevant content, and books meetings. Unlike rule-based chatbots, Spara's Chat channel is powered by an LLM and responds naturally to whatever a visitor says.

Chat offers three interfaces:

* [Spara Navigator](/build/channels/chat/spara-navigator): the standard bottom-right chat widget
* [Spara Smartbar](/build/channels/chat/spara-smartbar): a ChatGPT-style experience embedded in your marketing pages
* [Spara Fullscreen](/build/channels/chat/spara-fullscreen): a fullscreen chat experience designed to load immediately after form submissions

Most Spara customers deploy all three interfaces. Leads who engage with more than one interface share a single conversational thread.

***

## Abilities

The Chat channel can invoke the following abilities during a live conversation. For a cross-channel overview, see [Abilities](/build/channels/configuring/abilities).

### Show Calendar

The channel can present a scheduling link to the lead. A calendar widget slides out alongside the conversation, letting the lead pick a time without leaving the page.

**How it works:** Calendar booking is enabled on all Chat channels by default. The channel decides when to show the calendar based on your [AI Instructions](/build/channels/configuring/ai-instructions) and the lead's intent. You don't need to explicitly call it out; instruct it on what buying signals or requests should trigger the calendar, and it handles the rest.

If calendar booking should be disabled for a channel, turn off the **Show calendar** toggle on the channel's **Settings** tab.

**Setting it up:** Connect a calendar via [Calendar Integrations](/integrations/calendar-integrations). Calendars are uploaded as media assets and made available to the channel. Add instructions for when to show the calendar, for example:

> When a lead is ready to book a meeting or asks about scheduling, show the calendar. Don't show it before you've confirmed interest.

**Multiple calendars:** If you have more than one calendar (e.g., different reps or meeting types), specify in instructions which calendar to use in which context.

### Show Media

The channel can surface a video, image, or PDF alongside the conversation. The media panel opens to the left of the chat so the lead can view it without losing the conversation thread.

**How it works:** Media display is opt-in. Enable it and upload assets on the [Media](/build/channels/chat/media) page. Each asset has a **Name**, **Description**, and **When to Show** field that the channel reads when deciding what to surface.

**Setting it up:** See [Guide: Using Media in Chat Agents](https://docs.spara.com/guides/platform-guides/using-media-in-chat-agents) for a step-by-step walkthrough.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-8e255e378f0213e10caffc82cb957903922b8908%2Fdocs%20-%20desktop%20-%20export.svg?alt=media" alt=""><figcaption><p>Spara Navigator showing a video alongside the conversation.</p></figcaption></figure>

### Send Email

The channel can send an email on behalf of your organization, for example, to follow up with a summary, send a PDF, or copy in a rep after a conversation.

**How it works:** It composes and sends an email using your connected email provider. You configure which email addresses are allowed recipients in the channel's settings. The lead's email address and any whitelisted addresses can be included.

**Requirements:** An active email connection (Gmail or Outlook) must be set up under [Email](/build/channels/email). The send\_email ability is not enabled by default; configure it by adding `send_email` to the channel's tool list and adding instructions for when and how to use it.

***

## Previews

The **Previews** tab in the Chat channel editor shows how your agent resolves and renders for visitors under different starting conditions — device type (desktop, mobile, tablet) and starting page URL.

Each row in the Previews list represents a combination of starting criteria. Click a row to open a live preview of the agent on that device and page, so you can verify the correct interface loads and appears as intended before publishing.

Live previews show how the agent appears before a visitor interacts with it. To see the opened chat — including the opening chat message and calls to action like Start Product Demo — select **Test Preview** above the desktop live preview, or click anywhere in a live preview, to start a conversation with the agent in the testing interface.

Testing a preview saves it first, and preview changes reach visitors as soon as they are saved, so **Test Preview** is only offered while the channel is still a draft. On a published channel, select **Expand** instead to view the live preview at full size.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-6f24fbd0ebd8cfc83d0110c00fb04a07d18251ec%2FPreviews.png?alt=media" alt=""><figcaption><p>The Previews tab showing agent rendering across device types and starting pages.</p></figcaption></figure>

***

## Technical details

For technical information about how the Spara chat widget loads on your website (iframe architecture, browser storage, and cookie consent), see [Developer: iFrame & Cookies](https://docs.spara.com/developers/installation/iframe-and-cookies).

***

## FAQ

### Can I give one Chat channel multiple calendars?

Yes. Upload each calendar as a separate asset, give them distinct names, and write instructions that specify which calendar to use for which scenario (e.g., "use the Sales calendar for prospects, the Support calendar for existing customers").

### Can it show media and a calendar in the same conversation?

Yes. The channel can show both in a single conversation, for example, playing a product video early and offering the calendar once interest is confirmed.

### Does sending an email create a lead record?

No. The send\_email ability sends to addresses you've configured (the lead's email, whitelisted addresses). It does not create new leads or alter the lead record.

### Do leads who chat on multiple widgets share the same conversation?

Yes. Leads that engage with more than one Spara interface (Navigator, Smartbar, or Fullscreen) experience a single continuous conversational thread. Context carries across widgets.


# Spara Navigator

An introduction to Spara's website chatbot.

Spara Navigator is a chatbot for marketing websites. It is built specifically to power MQL to SQL conversion by answering questions and proactively asking qualifying questions. Spara Navigator "floats" on the page so that it is viewable and accessible at all times.

Onboarding & installation instructions can be found here: [Guide: Installing Spara Navigator](https://docs.spara.com/guides/onboarding-guides/chat-agent-onboarding/installing-spara-navigator).

Spara Navigator's initial behavior can be customized based on a multitude of factors:

* What URL Spara is loaded on
* Any [Developer: Query Parameters](https://docs.spara.com/developers/spara-api/query-parameters) in the URL, including `utm` marketing parameters
* When Spara should appear: after a delay, or once the visitor scrolls down the page

Once a buyer is engaging with Spara Navigator, how Spara Navigator moves the lead through your sales funnel is fully configurable in [AI Instructions](/build/channels/configuring/ai-instructions).

Spara Navigator's UI and color scheme are highly configurable. Below is an explanation of UI Modes; Navigator may have different UI Modes for desktop versus mobile users.

## Previews

In addition to all the features outlined in [AI Instructions](/build/channels/configuring/ai-instructions), Previews lets you define how Spara Navigator looks to website visitors *before* they engage with it. Here's how it works:

* Each chat channel has its own set of one or more Previews.
  * This makes [A/B Testing](/build/channels/configuring/a-b-testing) different Previews easy to optimize engagement.
* Each Preview\...
  * Has a **Name** identifying it in the list. Spara names a new or duplicated Preview after its loading criteria when you save it, and you can edit the Name yourself at any time — once you do, Spara keeps the name you chose.
  * Is entirely configurable for Desktop vs. Mobile visitors.
  * Loading criteria determines which website visitors see it. The "default" Preview is a catch-all for any website visitors that don't fit the loading criteria of other Previews.
  * The **Scrolled distance** and **Element in view** loading criteria switch Navigator to that Preview as the visitor scrolls, instead of choosing it when the page loads. See [Switching Previews as visitors scroll](#switching-previews-as-visitors-scroll).
  * **Show Navigator** sets when website visitors first see Navigator:
    * **After a delay** waits the number of seconds you choose.
    * **After scrolling a distance** waits until the visitor has scrolled that many pixels down the page. On a page too short to scroll that far, Navigator appears once the page has loaded.
    * **When an element scrolls into view** waits until the element with the id you enter (for example `pricing` for `<section id="pricing">`) is visible on screen. If the page has no element with that id, Navigator appears after a moment instead.
    * Scrolling inside a page's own scroll container counts too, not only scrolling the browser window. A visitor who has already started a chat always sees Navigator right away.
    * Once a visitor has seen Navigator, it stays visible for the rest of their visit in that browser tab, including when they refresh or move to another page. A new tab or a later visit waits again.
  * Preview mode is what Navigator looks like. Different Preview modes require different inputs.
  * A **Call to action** section lists the buttons you can offer the visitors who see this Preview. Select **Start product demo** on the Previews where you want a demo offered — for example, only on your pricing page. The two surfaces are separate options, so you can offer a demo in one and not the other: **before Navigator is opened** puts the button on the Navigator itself, and **within Navigator chat** puts it above the message box once a visitor has opened the chat. Both options appear only if product demos are enabled for your account.
* Each Preview is rendered for you to "preview" in the bottom right of the screen so you can see exactly how each input works.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-6f24fbd0ebd8cfc83d0110c00fb04a07d18251ec%2FPreviews.png?alt=media" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
When the starting criteria is **URL**, enter the **path** of the page (e.g., `/pricing`, `/solutions/sales`), not a full URL with `https://` and a domain. Spara matches the visitor's current path against what you enter, including any sub-paths underneath it (so `/pricing` also matches `/pricing/enterprise`).

When the starting criteria is **Country**, you can select more than one country, and the Preview shows to visitors from any of them. One Preview can therefore cover a whole region or language — for example, a French-language Preview for visitors from France, Belgium, and Switzerland.
{% endhint %}

### Switching Previews as visitors scroll

A Preview whose loading criteria is **Scrolled distance** or **Element in view** takes over from the Preview a visitor already sees once they scroll to it. For example, to open your homepage with Navigator in the center of the screen and move it to the bottom-right corner once the visitor scrolls down:

1. Set the default Preview to the **Central** mode.
2. Add a Preview in a **Traditional** or **Avatar** mode, with the loading criteria **Scrolled distance** is at least `1000` pixels.

When the visitor scrolls 1,000 pixels down the page, Navigator changes to the second Preview: its mode, message, suggested responses, and calls to action.

* **Scrolled distance** switches once the visitor has scrolled that many pixels down the page. On a page too short to scroll that far, Navigator stays on the Preview it shows.
* **Element in view** switches once the element with the id you enter (for example `pricing` for `<section id="pricing">`) is visible on screen. Pages without that element keep the Preview they show.
* With several scroll Previews, Navigator switches to each one as the visitor reaches it. Scrolling back up doesn't switch back.
* Navigator doesn't switch while the visitor has the chat open or has minimized Navigator. It also doesn't switch once they've started a chat.
* Each page starts again from the Preview that matches when it loads.
* A scroll Preview applies on every page, since a Preview has one loading criteria. It only takes over from Previews listed above it, so a URL or country Preview listed below it keeps its visitors.
* **Show Navigator** doesn't apply to scroll Previews, since Navigator is already showing when they take over.

### Preview Mode: Central

The "Central" preview mode is a contemporary design that drives higher engagement that a traditional bottom right chatbot - you'll notice leading AI companies like [OpenAI](https://openai.com) using this design on their own marketing websites. We recommend using this mode.

Note that this mode may not be compatible with large cookie policy banners and is only supported on desktop - you must choose a different mode for mobile devices.

<div align="center" data-full-width="true"><figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-8e22763f683649d251f6cc722948fad3f420b9e0%2Ffloat.png?alt=media" alt=""><figcaption><p>Spara Navigator's modern, centrally-placed UI.</p></figcaption></figure></div>

### Preview Mode: Traditional

Traditional Mode places the chatbot in the bottom right corner of screens - where chatbots are traditional seen. There are three options within this mode:

* Traditional: Message - shows a message and/or suggested responses
* Traditional: Input - shows an input bar
* Traditional: Closed - shows just the bottom-right avatar

With **Start product demo — before Navigator is opened** selected, the demo button sits above the message or the input bar. Traditional: Closed shows only the avatar, so it can't offer a button — visitors get the demo once they open the chat instead.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-4b7692a2c05ce1f4cc3222198d392dea71329e93%2FPreview%20mode.svg?alt=media" alt=""><figcaption><p>Traditional: Message mode can show with a preview message and/or suggested responses.</p></figcaption></figure>

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-582f4ae74c373fb1f3de2773888e40f5521cf78b%2FClosed%20mode%20(1).svg?alt=media" alt=""><figcaption><p>Traditional: Closed mode only shows the bottom-right avatar.</p></figcaption></figure>

### Preview Mode: Opened

This mode loads Spara Navigator in its "opened" state.

### Preview Mode: Hidden

Does not show Spara Navigator at all. Useful for A/B testing having a chatbot on your webpages.

### Preview Mode: Avatar

The Avatar preview mode replaces the standard message bubble with a narrow portrait card. Desktop visitors see a looping avatar video, a greeting, a **Start product demo** button, and an input for typing their own question. Two additional buttons — book a meeting and request support — can be enabled per preview. The demo button follows the Preview's **Start product demo — before Navigator is opened** setting; without it the card opens chat instead.

#### Keeping the avatar in the opened chat

By default the avatar shrinks to the small portrait in the chat header once a visitor opens the chat. Turn on **Show avatar in chat**, under **After Spara Chat is Opened**, to keep it playing as a banner at the top of the conversation instead. Clicking the banner — or its **Start product demo** button — opens the product demo, so it replaces the demo button that otherwise sits above the message input.

Give the banner its own **Banner video** — a landscape clip. The avatar card's clip is portrait, so shown in the banner it has to be cropped to about a third of its height, which lands on the face alone; a landscape clip fills the banner as it was framed. Without one the banner falls back to the card's clip.

**Avatar placement** chooses how the banner sits:

* Immersive — the banner takes the chat header's place and carries the rep's name and title itself.
* In thread — the standard header stays and the banner enters as the conversation's first card, scrolling away as the chat grows.

This setting needs product demos enabled on your account, and appears only on previews using Avatar mode.

This mode is configured by Spara. Reach out to your account manager or <support@spara.co> to enable it for your account.


# Spara Smartbar

An introduction to Spara's embeddable Smartbar interface.

Spara Smartbar is a customer-facing interface embedded directly on your marketing website. It lets customers ask questions - like having mini ChatGPT about your company easily accessible to your marketing leads. Its AI is tuned to handle any lead scenario intelligently and elegantly, all without needing to maintain a complex set "if/else" rules.

Installation instructions can be found here: [Guide: Installing Smartbar](https://docs.spara.com/guides/onboarding-guides/chat-agent-onboarding/installing-smartbar).

Spara SmartBar and [Spara Navigator](/build/channels/chat/spara-navigator) work together! Both can load on a single page. Customers that engage with both interfaces will experience a single, coherent conversation.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-8dc8af46229e64faf611d22576adf507b140005e%2FSmartbar.png?alt=media" alt=""><figcaption><p>Tiny embeds Spara Smartbar on their marketing pages to engage visitors.</p></figcaption></figure>

Spara Smartbar's initial behavior can be customized based on a multitude of factors:

* What URL Spara is loaded on
* Any [Developer: Query Parameters](https://docs.spara.com/developers/spara-api/query-parameters) in the URL, including `utm` marketing parameters
* Any "wait" time before Spara should load

Once a buyer is engaging with Spara, how Spara behaves to move the buyer through your sales funnel is fully configurable in [AI Instructions](/build/channels/configuring/ai-instructions).


# Spara Fullscreen

An introduction to Spara's full screen interface.

Spara Fullscreen is exactly what it sounds like: a full screen chat interface powered by Spara's AI. This interface is deployed onto a single URL of your company's marketing website. It's most often used for post-web form submission flows.

Installation instructions can be found here: [Guide: Installing Spara Fullscreen](https://docs.spara.com/guides/onboarding-guides/chat-agent-onboarding/installing-spara-fullscreen).

Spara Fullscreen's behavior is completely configurable through [AI Instructions](/build/channels/configuring/ai-instructions). The Fullscreen interface is fully responsive for all device types.

<figure><img src="https://lh7-us.googleusercontent.com/docsz/AD_4nXeCNIPqPl7WSuCYEWXKETWoVjDom8OOUwzc8DeJAd_fWs9m-0ZWyOl54uuAzlBvrg9PBDCUeftCdkrAf87durQf7Ci7ae38i5wu5Ctkj_XuwaUD7DjxbBQtdousEV4_jGqvKpNHK41VOXuBqC5ZhgcKnww8?key=wYFiLmwCMeQ_9hs7ycmjDg" alt=""><figcaption><p>Spara's full screen interface on desktop deployed by Sendoso.</p></figcaption></figure>


# Chat Theme

Customize how Spara looks to your leads across all three chat interfaces: Navigator, Fullscreen, and Smartbar.

Navigate to [Chat > Theme](https://app.spara.co/settings/chat/theme) in the Spara platform to access these settings. The **Live preview** at the bottom of the page reflects any changes immediately, so this can be used to test and verify changes. Once you are happy with the preview, select the save changes button to apply them to your website.

#### Navigator / Fullscreen Settings

Navigator and Fullscreen settings are linked, so any changes you make in Navigator will reflect in Fullscreen as well. Outside of the chat theme, to edit the suggested responses and chat mode, refer to [Previews](/build/channels/chat/spara-navigator#previews), this allows you to define how Spara navigator looks before a visitor engages.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-c34e51d660bf078a8f1ebaa64a713e7f61e8d32e%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

* **Privacy message:** Shown at the bottom of every chat. Supports Markdown links - e.g. `[Privacy Policy](https://yoursite.com/privacy)`
* **Privacy text color:** Customize the text color of the privacy message. Useful when using a dark chat background where the default gray would be hard to read. Falls back to neutral gray when unset.
* **Chat Colors:** Customize the color of every visual element in the chat window - the top bar, chat background, send / media buttons, bot and lead message bubbles, text colors, link colors, and suggested responses color. Each field allows you to select a color visually or enter a hex color code.
* **Navigator border:** The outline around the Navigator as it sits on your site. Pick a color, or drag the picker's opacity slider to 0% to make the border invisible so the Navigator blends into the page.
* **Navigator text:** The text inside the open chat window when a preview has the new design enabled - what the visitor types, the typing dots, the privacy line, and the header controls. The assistant's replies keep the Bot text color. Near-black unless set; pick a light color if your chat background is dark. The Smartbar has its own text color under Smartbar Settings.
* **Collapse button:** The floating button that opens and closes the chat. **Background**, **Icon**, and **Border** style it while the chat is open; **Logo border** is the ring around your logo while the chat is closed.
* **Chat Channel Avatar:** Change the avatar or name. The avatar must be a 200x200 px image.
* **Online dot:** The small green dot in the corner of the avatar. Turn it off when your avatar is your company logo and the dot distracts from it. It applies everywhere the avatar appears - the collapse button, the chat header, and every preview.

#### Smartbar Settings

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-ce3bc4afafd8c3b1534a1334528b7fdb616c5416%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

* **Title & Input placeholder:** This is the text the lead sees before they start typing
* **Placeholder media title & CTA:** Once a lead clicks into the Smartbar, on the left side the you have the option to add a placeholder media CTA which links to a media asset.
* **Suggested responses:** Enter one response per line. These appear as clickable bubbles below the bar the lead can start typing.
* **Appearance:** Customize the primary color, background color, text color, padding, and an optional background image.


# Media

Upload and configure visual media that Spara chat agents show to leads during conversations.

Chat agents read your media library during every conversation and proactively surface the most relevant file at the right moment — without you scripting every interaction. When a lead asks for a product demo, a case study, or a pricing overview, the agent pulls up the right asset and presents it naturally, the same way a rep would reach for the right slide deck.

{% hint style="info" %}
Media is currently supported by Chat agents only (Spara Navigator, Smartbar, and Fullscreen).
{% endhint %}

## How media appears in chat

When an agent shows a file, a media panel slides out to the left of the conversation. The lead can view the media while continuing to chat — videos, PDFs, and images all render inline in this panel, so leads never have to leave the page.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-ab87f0639f805429e3020219155ee6540e728717%2Fmedia.png?alt=media" alt=""><figcaption><p>Spara Navigator with a media panel open alongside the chat window.</p></figcaption></figure>

## Setting up your media library

Navigate to [**Settings > Chat > Media**](https://app.spara.co/settings/chat/media) and click **Upload File**. Each asset has three fields the agent uses to decide when and whether to show it:

**Name** — The label displayed to the lead when the file is shown. Use something clear and human-readable, like "Product Overview" or "Q3 Case Study — Enterprise."

**Description** — A detailed explanation of what the asset contains. The agent reads this to understand the file's content. The more specific, the better the agent's decision-making — describe the topics covered, the audience it's best for, and any key proof points.

**When to Show** — A plain-language description of the situations in which this file is relevant. The agent reads this to know when to surface the asset (see [#writing-effective-when-to-show-descriptions](#writing-effective-when-to-show-descriptions "mention")).

**Visibility** — Set to **Visible** to make the file active. Set to **Hidden** to remove it from the agent's options without deleting it.

### Writing effective "When to Show" descriptions

The "When to Show" field is what tells the agent the right moment to surface a file. Write it as a bulleted list of intent signals — what would a lead say or ask that makes this asset relevant?

**Good example** for a product demo video:

* Lead asks to see a product demo or walkthrough
* Lead expresses interest in understanding how the platform works
* Lead asks "what does it look like" or "can you show me"

**Good example** for a pricing overview PDF:

* Lead asks about pricing, cost, or plans
* Lead asks to compare tiers or packages
* Lead is ready to move forward and wants to understand the investment

**Tips:**

* Use plain language, not exact-match phrases. The agent understands intent, not just keywords.
* One file per specific use case. Focused conditions perform better than a single catch-all file.
* Revisit conditions after reviewing conversations. If a file is appearing at the wrong moment, tighten the description.

### Keeping your library current

Because the agent reads asset details directly from the Media library, you can update what it shows without touching your agent's prompt:

* **Add a new asset** with a clear description and "When to Show" — the agent picks it up automatically
* **Update an existing asset's description** to shift when and how the agent uses it
* **Set an asset to Hidden** to remove it from the agent's options immediately

## Guiding media from the agent prompt

You can give your chat agent explicit instructions in its prompt about how to handle media — which assets to prioritize, when to proactively offer them, how to introduce them, and when to hold back. For details and examples, see [Guide: Using Media in Chat Agents](https://docs.spara.com/guides/platform-guides/using-media-in-chat-agents).

## Supported file formats

| Type                  | Common uses                                        |
| --------------------- | -------------------------------------------------- |
| Video (mp4, mov)      | Product demos, explainers, customer testimonials   |
| Image (png, jpg, gif) | Feature screenshots, comparison charts, one-pagers |
| PDF                   | Pricing sheets, case studies, whitepapers          |

## FAQ

### How many media files can I have?

There is no hard cap. Use Hidden to archive files you no longer need rather than deleting them, so you can reactivate them later.

### Can the same file be shown by multiple agents?

Yes. Media files are shared across all chat agents in your account. Any Visible file can be shown by any active chat agent when its "When to Show" conditions are met.

### How do I know if a media file is working?

Test it in the [Testing](/build/testing) interface: start a conversation and steer it toward a trigger condition you defined. If the media panel opens, the condition matched. If it doesn't appear, try expanding or rephrasing the "When to Show" description.

### Can I control which agent shows which file?

Not directly by agent — Visible files are available to all chat agents. If you need a file to be agent-specific, set it to Hidden and coordinate with your prompt instructions to guide which agent uses it and when.

For a step-by-step walkthrough of setting up media from scratch, see [Guide: Using Media in Chat Agents](https://docs.spara.com/guides/platform-guides/using-media-in-chat-agents).


# Email

How the Email channel automates sales email outreach and replies.

The **Email channel** automates sales interactions over email, both sending automated outreach sequences and replying intelligently to incoming responses. It works alongside your Agent's other channels to move leads through your pipeline.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-16fa79a72bcfcc6d66dd2ecd56df6f3c3a26cbf6%2FEmail%20Agents.png?alt=media" alt=""><figcaption><p>Email channel configuration with cadences, reply handling, and provider settings.</p></figcaption></figure>

Spara does not send cold outbound emails. The Email channel is triggered by lead actions (like submitting a webform or engaging in chat) and responds to incoming emails from leads already in your pipeline.

## Email Cadences

Email cadences are automated sequences of emails sent to leads based on trigger conditions. Each cadence consists of one or more steps with configurable delays between them.

### How cadences work

1. A trigger condition is met (e.g., "Lead submitted webform but hasn't scheduled a call")
2. Spara sends the first email in the cadence
3. After a configurable delay (minutes, hours, days, or weeks), the next step sends
4. The sequence continues until all steps are sent or the lead takes a desired action

### Configuring a cadence

Each cadence step includes:

* **Subject line**: Supports variables like `{{ first_name }}` for personalization
* **Email body**: Rich text with variable insertion, AI instructions, and calendar links via the ⚡ Insert Menu. See [Guide: How to Use Spara's Text Editor](https://docs.spara.com/guides/platform-guides/how-to-use-sparas-text-editor) for details.
* **Delay**: How long to wait before sending this step (configurable in minutes, hours, days, or weeks)
* **Preview**: Preview the email with sample lead data to see how personalization renders

## Reply handling

The Email channel handles incoming email responses from leads. When a lead replies to a cadence email or writes in directly, it:

* Reads and understands the lead's message
* Responds following your [AI Instructions](/build/channels/configuring/ai-instructions) and knowledge base
* Can escalate to a sales rep when the lead is qualified

Replies use the same [AI Instructions](/build/channels/configuring/ai-instructions) and testing tools as every other channel.

### Reply safeguards

Several automatic protections prevent the Email channel from sending replies that could create problems:

**Machine mail filtering.** The channel skips automated mail — out-of-office auto-replies, bounces, no-reply sender addresses, and mailing list messages — and never replies to them. This prevents accidental reply loops with mail automation.

**Teammate replies are left alone.** If someone on your own team replies on a lead's thread — for example, an assigned rep who was CC'd steps in to take the conversation — Spara recognizes the reply as internal and stays quiet instead of answering it as though the lead wrote in. Your team can stay CC'd so Spara still covers the lead's own replies, such as after hours. Spara identifies teammates by their Spara user account or your company's email domain.

**Loop circuit breaker.** If a thread accumulates more than 50 total replies, or 3 or more replies within a 5-minute window, the channel stops replying on that thread. This prevents runaway reply chains in cases where machine mail slips through or a misconfiguration causes rapid back-and-forth.

**Per-recipient daily frequency cap.** Spara enforces an absolute daily ceiling on the number of emails sent to any single lead. This cap applies across all email activity — cadences, workflow Send Email steps, and Reply Agent responses — so no single lead receives an excessive volume of email in a day.

### Testing replies

To test how the channel responds, open it and click **New test**. Select a workflow and a **Send Email step**. Spara renders that email as the first message in the test thread, giving your simulated reply the same context a real lead would have. Type a reply and click **Send Reply** to see how it responds.

If no workflows exist yet, the test panel shows a link to create one. The test session persists in the URL (`?testId=...`) so you can refresh and return to the same thread. Click **New test** at any time to start fresh.

## Configuration

The Configuration tab controls your email setup:

### Email Provider

Connect your email provider to send emails from your domain:

* **Gmail**: Connect via Google OAuth
* **Outlook**: Connect via Microsoft OAuth

{% hint style="info" %}
An email connection is required to publish. It's the mailbox the channel sends from and answers replies in. Several Email channels can share one mailbox, each used by different workflows; a reply is always answered by the channel that sent the email the lead replied to.
{% endhint %}

### Daily Send Limits

Control how many emails Spara sends per day: 5, 10, 25, 100, or No Limit. Start with a lower limit and increase as you verify email quality.

### Email Tracking

Control whether Spara tracks open and link-click engagement on outgoing emails:

* **On (default)** — outgoing emails include an open-tracking pixel and rewritten links so Spara records when a lead opens an email or clicks a link. These events populate the **Email opened at** and **Email link clicked at** fields on the lead record and can trigger workflows. Many companies run email security tools that open every link in an incoming email automatically; Spara tells those automated fetches apart from the lead's own opens and clicks and does not count them, so an open or click appears about a minute after it happens.
* **Off** — outgoing emails carry no tracking pixel and links are not rewritten. The **Email opened at** and **Email link clicked at** fields will not be populated. Workflow triggers that depend on email open or click events will not fire.

Toggle this setting off if your organization is subject to regulations (e.g., GDPR in France or Italy) that require opt-in consent before deploying tracking pixels or rewriting links.

### Email Modes

* **Cadence emails**: Toggle automated cadence sequences on or off
* **Reply emails**: Toggle automated replies to incoming emails on or off

Both can be disabled independently. For example, you might want to automate cadence sends but handle replies manually.

## Unsubscribes and deliverability

Every Spara email includes an unsubscribe link in the footer, in compliance with CAN-SPAM and the major mailbox providers' requirements (Gmail, Yahoo). The link opens a page with a single **Confirm unsubscribe** button, and the opt-out is recorded when the lead clicks it. Spara also reads every reply a lead sends for an opt-out request, whether it is a one-word "unsubscribe" or a sentence like "please stop emailing me" or "take me off your list". This is built in and always on; you do not need to add anything to your agent's instructions. When a lead clicks unsubscribe or asks to stop in a reply, Spara:

* Records the opt-out against the email address, so it shows on the lead's record and in exports.
* Immediately stops all future emails to that address, across cadences, workflow Send Email steps, and Reply Agent responses. Because the opt-out belongs to the address rather than to a single lead record, it also covers any other lead in your workspace with the same email address.
* Stops Spara from generating any further outbound email content for them, even if a workflow would have triggered one. A reply that asks to stop is not answered.
* By default, also stops texts and calls to the lead's phone number. To have an email unsubscribe cover email only, turn off **Cross Channel Opt-Outs** in [Settings](/platform/settings).

Capturing unsubscribes this way actually **protects** your deliverability rather than harming it. Mailbox providers track recipient complaints and unsubscribe rates; honoring opt-outs immediately keeps your sender reputation healthy. The opposite, continuing to send to a recipient who tried to unsubscribe, is what triggers spam complaints and degrades inbox placement.

{% hint style="info" %}
Spara's email evaluator also ensures every email body contains exactly one unsubscribe link. Duplicate links can confuse leads and trigger spam filters.
{% endhint %}

## FAQ

### What types of emails does Spara send?

Spara sends two types: cadence emails (automated sequences triggered by lead actions) and reply emails (responses to incoming messages). Spara does not send cold outbound emails to leads who haven't interacted with your brand.

### Which Google account do I use to connect Gmail?

Connect with any Google account that has **Send As** permission for the mailbox you want Spara to send from. You do not need to authenticate as the shared mailbox itself. For example, if Spara should send from `sales@yourcompany.com`, you can authenticate with your personal work account (e.g., `you@yourcompany.com`) as long as you have been granted Send As access to that address in Google Workspace. After connecting, Spara will send from whichever address is configured as your primary or delegated sending address. Contact your Google Workspace admin if you're unsure whether your account has the right permissions.

### Can I personalize emails with lead data?

Yes. Use the ⚡ Insert Menu in any email text field to insert variables like `{{ first_name }}`, `{{ company_name }}`, or any field from the [Data Model](/build/data-model). You can also insert AI instructions that tell the channel to dynamically personalize sections of the email.

### Can replies mention the campaign a workflow is about?

Yes, when the workflow's trigger filters on exactly one Salesforce Campaign. Add `{{ workflow_campaign_name }}` or `{{ workflow_campaign_description }}` to the email channel's AI Instructions, and replies to that workflow's emails see the Campaign. On other threads they're blank. See [Developer: Salesforce Campaigns & Campaign Members](https://docs.spara.com/developers/data-model/data-model/campaign#using-a-campaigns-details-in-messages).

### How do cadences interact with workflows?

[Workflows](/build/workflows) Send Email steps and email cadences are separate features. Cadences are configured on the Email channel and have their own trigger conditions. Workflow Send Email steps are individual emails within a workflow sequence. Both can reference the same lead data and both respect the lead's email preferences.


# Phone

How the Phone channel handles AI phone calls to engage, qualify, and convert leads.

The **Phone channel** conducts real-time AI phone conversations with leads, handling incoming sales calls and making outgoing follow-up calls. It engages leads immediately, 24/7, without requiring a human rep on every call.

For live, voice-narrated product walkthroughs with synchronized visuals, see the separate [Product Demo](/build/channels/product-demo) channel.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-03fffc995fe36051176ec777af21f181cd7f50d3%2FPhone%20Channel.png?alt=media" alt=""><figcaption><p>A Phone channel's Configuration tab: phone number, call settings, and voice.</p></figcaption></figure>

## Use cases

### Outgoing follow-up calls

Spara can call leads automatically when they complete — or fail to complete — a key action. A common example: a lead submits a marketing form but never schedules a meeting. Spara calls immediately to move them through the next step while interest is high.

Outgoing calls are triggered through [Workflows](/build/workflows) using the [Call Phone Step](/build/workflows/steps/call-phone).

### Incoming calls

Spara handles incoming sales calls end-to-end, answering questions, qualifying leads, and booking meetings. When a lead calls your assigned phone number, the Phone channel answers immediately, identifies the caller if possible, and conducts the conversation using the lead's available context (fields, conversation history, and CRM data).

### Callback on outgoing numbers

All outgoing phone numbers automatically accept incoming calls. If a lead misses your outgoing call and calls the number back, the same Phone channel that was dispatched picks up and continues the conversation with the lead's full context intact. No additional configuration is required; this behavior is enabled by default on all outgoing numbers.

***

## Phone number management

Phone numbers are managed centrally in your account's settings and then assigned to individual channels or workflows.

### Adding phone numbers

Navigate to **Settings > Voice > Configuration** to view and manage your account's phone numbers. From here you can register new numbers that become available across your account for use with Phone channels, [SMS](/build/channels/sms), and workflows.

Each phone number can serve as:

* **An incoming number for a Phone channel.** Assign it on the channel's Configuration tab. Leads who call that number reach this channel.
* **An incoming number for an** [SMS](/build/channels/sms)**.** Assign it on the SMS channel's Configuration tab.
* **An outgoing number for workflows.** Select it in a [Call Phone Step](/build/workflows/steps/call-phone) or [Send Text Step](/build/workflows/steps/send-text) step.

### Phone number ownership

Phone numbers used by Spara are hosted in Spara's telephony account. There are two common ways to get a number live:

* **Spara provisions a new number for you.** The most common path. Spara registers a fresh number in the country and area code you choose.
* **You port an existing number into Spara.** If you already own a phone number and want to keep it, you can transfer it into Spara's telephony account. Spara coordinates the port with your current provider.

{% hint style="info" %}
Bring-your-own-number (where you retain ownership of the number and Spara routes calls from your carrier directly) is on the Spara roadmap but is not currently under development. Today, the number must live in Spara's telephony account.
{% endhint %}

### Connecting your phone numbers to Spara

If you want a phone number you already publish on your website or marketing materials to reach a Spara Phone channel, there are two ways to wire it up.

**Option 1: Forward calls to a Spara-provided number.**

The simplest path. Configure your existing phone system to forward incoming calls to a number Spara has provisioned for you. From your customers' perspective they dial the same number they always have; behind the scenes the call forwards to Spara and the Phone channel picks up.

This works with any phone system that supports call forwarding to an external number. No technical integration required; your Spara representative can help you set this up.

**Option 2: Route calls directly to Spara over SIP.**

If your phone system supports SIP (Session Initiation Protocol) — common in business telephony platforms like Genesys, RingCentral, and similar — you can route incoming calls straight to Spara's SIP endpoint, skipping the intermediate forward.

This option is more efficient (one less hop) but requires technical coordination. Spara needs to share its SIP endpoint with your telephony team and allow-list your routing IPs. Expect a brief technical setup session between your team and Spara to get this working.

Most customers use Option 1 because it requires no engineering effort. Choose Option 2 when your telephony stack already speaks SIP and you want a tighter integration.

### Assigning numbers

Each Phone channel can be assigned a phone number on the **Configuration** tab. This is the number it answers incoming calls on and uses as the caller ID for outgoing calls. Each phone number can only be assigned to one published Phone channel at a time.

You can run multiple Phone channels on separate phone numbers. For example, one number for sales inquiries and another for support routing. Each operates independently with its own instructions, abilities, and phone number.

{% hint style="info" %}
Spara does not make cold or unsolicited outgoing calls to leads outside of your [Workflows](/build/workflows).
{% endhint %}

### Branded caller ID for outgoing calls

Branded caller ID displays your business name (instead of just a phone number) on the lead's screen when an outgoing call rings, which significantly improves answer rates. Spara handles the registration with the telephony network on your behalf, but it requires information from you (business name, use case, sample call scripts) and **typically takes several days to complete**.

Whether carriers flag your outgoing calls as "Potential Spam" depends primarily on the carrier verifications Twilio requires: A2P 10DLC for SMS-paired numbers, business identity verification, and similar registrations. Branded calling is an additional layer on top of those verifications. It is not, on its own, what prevents the spam label. Completing the required Twilio verifications is the prerequisite; branded calling then improves how your number presents on the recipient's screen.

{% hint style="warning" %}
If you plan to use a Phone channel for outgoing calls, ask your Spara account team to kick off the required carrier verifications and branded-calling onboarding as early as possible. Calls placed before verifications complete may show as "Potential Spam" on the recipient's phone, which materially hurts answer rates.
{% endhint %}

***

## Abilities

Abilities are tools the channel can use during a live call. They are configured on the **Abilities** tab. For a cross-channel overview, see [Abilities](/build/channels/configuring/abilities).

| Ability          | Description                                                                                        |
| ---------------- | -------------------------------------------------------------------------------------------------- |
| **Book meeting** | Checks your calendar, reads available slots aloud, and books the meeting through conversation      |
| **Transfer**     | Cold or warm transfer to a rep or team when the lead is qualified and ready to speak with someone  |
| **API request**  | Call an external API endpoint during a call, for order lookups, inventory checks, or internal data |

### Book meeting

The Phone channel books meetings through conversation, not by showing a calendar widget. The flow works like this:

1. It asks the lead when they're available and checks your calendar for open slots
2. It reads the available times aloud (e.g., "I have Tuesday at 2pm or Wednesday at 10am")
3. The lead picks a time
4. It confirms the details (name, email) and books the meeting

It can filter slots by time of day based on the lead's preferences (morning vs. afternoon, weekdays only, etc.).

Booking requires a [Calendar Integrations](/integrations/calendar-integrations) connection. Spara supports [Cal.com](/integrations/calendar-integrations/cal.com), [Calendly](/integrations/calendar-integrations/calendly), [Chili Piper Concierge](/integrations/calendar-integrations/chili-piper-concierge), and others.

{% hint style="info" %}
When you create a new Phone channel, Spara automatically creates a Calendly calendar integration for it. You can change the calendar provider or customize the integration on the Abilities tab.
{% endhint %}

### Transfer

The Phone channel can transfer calls to a rep or team when the moment is right, for example, when a lead is qualified and ready to speak with sales.

#### Cold vs warm transfer

* **Cold transfer.** It says goodbye and forwards the call. The lead hears ringing and connects with the rep (or voicemail). If nobody picks up, the call ends. Use this for general routing where the receiving team is reliably staffed.
* **Warm transfer.** It connects your rep first, briefs them on the conversation, then drops off. The lead stays on the line throughout. **If nobody picks up the warm transfer, the Phone channel stays on the call with the lead**: it can continue answering questions, capture follow-up details, or end gracefully rather than dropping the caller. Use this for high-value leads where a missed handoff would be costly.

Spara recommends warm transfers by default. The recovery behavior (staying on if the handoff misses) keeps the lead engaged even when your rep is unavailable.

#### Transfer destination types

You can configure multiple named destinations (e.g., "Sales", "Support", a specific rep) on the Abilities tab. The channel chooses the right destination based on the conversation and your instructions. Each destination can be one of two types:

* **A phone number.** A standard phone number, whether a rep's cell phone, a desk line, or a routing number at another service. Phone-number transfers work out of the box; no extra setup needed.
* **A SIP endpoint.** A SIP address belonging to another voice system (such as your support center's SIP-based platform). SIP transfers require a brief technical setup session between Spara and the receiving system so they accept calls from us. Use this only when your downstream system explicitly requires it.

If you're unsure which type a destination is, ask the team running that destination "is this a phone number or a SIP endpoint?" The answer determines whether the setup is plug-and-play or requires a coordination call.

### API request

The Phone channel can make HTTP requests to external services during a call, for example, to look up a lead's account status or pull pricing details for the service they're asking about. You configure the URL, HTTP method, any required headers, query parameters, and a request body ahead of time. It triggers the request at the right moment in the conversation and reads the response.

***

## Configuration

The [AI Instructions](/build/channels/configuring/ai-instructions) tab defines the channel's persona, tone, and how it handles common scenarios. The **Configuration** tab covers phone number assignment, voice selection, and call behavior.

For a step-by-step walkthrough, see [Guide: Setting Up Voice Agents](https://docs.spara.com/guides/platform-guides/setting-up-voice-agents).

### Voice and call settings

* **Voice provider.** Choose from supported text-to-speech providers, including ElevenLabs. Each provider offers a different range of voices and characteristics.
* **Voice.** Pick a voice that matches your brand. Depending on the provider, you can fine-tune characteristics like speed, stability, and similarity to control how natural and consistent it sounds. Customers often try a handful of voices on test calls before settling on one; the right voice has a noticeable impact on perceived quality.
* **Voicemail.** Leave a scripted voicemail when a lead doesn't answer an outgoing call. If the lead picks up mid-delivery, the voicemail is interrupted and the call continues as a live conversation.
* **Interruption handling.** Control whether the lead can interrupt mid-sentence, and how sensitive the detection is. More sensitive settings feel more conversational but can cause it to stop talking when the lead is just acknowledging ("uh-huh"). Less sensitive settings feel more steady but can sound robotic.
* **Re-engagement.** When enabled, it speaks again if the lead goes silent, keeping the conversation moving. Useful for keeping momentum on calls where the lead is distracted.
* **Max call duration.** Optionally set a time limit for calls. If a limit is set, it wraps up gracefully as the limit approaches, then the call ends. If you leave this unset, calls run as long as the conversation does.
* **Per-recipient call frequency cap.** Spara enforces a daily limit on outgoing calls to any single lead. When the cap is reached, further outgoing calls to that lead are skipped for the remainder of the day.
* **Nudge to business email.** When enabled alongside email capture, the channel asks callers who provide a personal email address (e.g. @gmail.com) whether they'd prefer to share their business email. The caller can confirm their personal address if they prefer. Off by default.

### Privacy warning

Configure a custom call recording or privacy disclosure that plays at the start of each call before the conversation begins. You can customize the warning text to meet local compliance requirements, and select a specific voice for the disclosure that's different from the main voice.

For outgoing calls, you can also embed the disclosure directly in the instructions instead of using this toggle. See [#how-do-i-handle-the-recording-disclosure-on-outgoing-calls](#how-do-i-handle-the-recording-disclosure-on-outgoing-calls "mention") for both options.

### Pronunciations

Custom pronunciations control how every Phone channel in your account speaks and recognizes specific words. They are configured account-wide under [**Settings > Voice**](/platform/settings/voice) and apply to all Phone channels.

### Publishing and version history

When you publish, the current draft becomes the live version. Spara tracks every published version in version history, so you can see what changed and when. This is useful for auditing prompt changes, rolling back if something breaks, and coordinating updates across your team.

See [Saving & Publishing](/build/channels/configuring/saving-and-publishing) for details on the draft/publish workflow.

### Do Not Call

Spara automatically prevents outgoing calls to leads who have opted out. When a lead requests not to be called during a conversation, the Phone channel records this preference. Once marked as Do Not Call, no outgoing calls will be placed to their number, including calls triggered by [Workflows](/build/workflows). [Call Phone Step](/build/workflows/steps/call-phone) steps in a workflow are skipped for opted-out leads, and the workflow continues to the next step.

By default, a Do Not Call request also stops texts to the number and emails to the lead's address. To have it cover calls only, turn off **Cross Channel Opt-Outs** in [Settings](/platform/settings).

Leads with an active Do Not Call preference are marked with a visible badge on the [Leads](/pipeline/leads) page, so your team can see at a glance which leads have opted out.

***

## Voice events in webhooks

When a voice call ends, Spara emits a `lead.updated` webhook with `source: "voice"`. Voice calls appear in a `calls` array on the payload (one entry per call) with start/end timestamps, whether it was incoming or outgoing, the Phone channel that handled the call, a short summary, and the transcript. See [Developer: Webhooks](https://docs.spara.com/developers/spara-api/webhooks) for the full webhook payload spec.

***

## A/B testing

You can run two variants of a Phone channel (different prompts, voices, or abilities) in parallel and compare outcomes. Variants are grouped by the phone number they share, and traffic is split between them, for incoming calls and outgoing workflow calls alike. See [A/B Testing](/build/channels/configuring/a-b-testing) for how to create variants and set the traffic split.

***

## Ask Spara

[Ask Spara](/platform/ask-spara) opens beside the editor and lets you chat with an AI assistant about the channel's behavior. Use it to debug why it said something unexpected, understand how your instructions are being interpreted, or get suggestions for improving your prompt. This is the fastest way to diagnose issues without re-reading your full instruction set.

***

## Testing

Click **Test** to start a test web call directly in your browser. This lets you have a live conversation to verify it sounds right.

You can also test outgoing calls from the voice testing dashboard. This sends a real outgoing call to a phone number you specify, letting you experience the call exactly as a lead would, including caller ID, voicemail behavior, and the full call flow.

Test calls use the **draft** version; any unpublished changes will be reflected. This means you can iterate on your prompt and abilities without affecting live calls. Test calls are recorded and appear in the call history for review.

See [Testing](/build/channels/configuring/testing) for more details.

***

## FAQ

### How does calendar booking work on voice calls?

The channel reads available slots aloud and books the meeting through conversation. It does not show a calendar widget; the entire flow is verbal. When you create a new Phone channel, a Calendly integration is automatically set up. You can change the provider or customize it on the Abilities tab. See [#book-meeting](#book-meeting "mention") above for details.

### How do transfers work?

Configure one or more named destinations (e.g., "Sales", "Support") on the Abilities tab. Cold transfer forwards the call directly; warm transfer brings your rep onto the line first, where it gives them a short verbal summary of the conversation before dropping off. It picks the destination based on your instructions and the conversation. See [#transfer](#transfer "mention") above.

### Can I have multiple Phone channels on different phone numbers?

Yes. Register multiple phone numbers in **Settings > Voice > Configuration**, then assign each number to a different Phone channel on its Configuration tab. For example, you could run a sales qualification channel on one number and a support routing channel on another. Each phone number can only be assigned to one published Phone channel at a time.

### Can it leave voicemails?

Yes. If a lead doesn't answer an outgoing call, the Phone channel can leave a voicemail using a script you configure under **Voice and call settings**.

### What happens if a lead calls back an outgoing number?

The same Phone channel that placed the outgoing call automatically answers. It has the lead's full context from the original call attempt, so the conversation picks up naturally.

### Where do I see call outcomes?

Call results appear on the lead's timeline in [Leads](/pipeline/leads), including whether the call was answered, transferred, or resulted in a booked meeting. You can use these outcomes as [Workflows](/build/workflows) triggers and conditions.

### Does it know about the lead before the call?

Yes. If the lead has existing fields (from a CRM sync, prior chat conversation, or previous calls), the Phone channel has access to that context. This includes data from [Salesforce](/integrations/crm-integrations/salesforce) and [HubSpot (CRM)](/integrations/crm-integrations/hubspot-crm) integrations.

### Are voice calls recorded?

Yes. All voice calls are recorded and transcribed. You can play back recordings and review transcripts from the lead's timeline on the [Leads](/pipeline/leads) page. The privacy warning plays at the start of the recording. See [#privacy-warning](#privacy-warning "mention") to customize it.

### How do I set up the privacy warning?

Go to the **Configuration** tab and find the privacy warning section under Voice and call settings. Enter your custom disclosure message and optionally select a different voice for the warning. The disclosure plays automatically at the start of each call before the conversation begins.

### How do I handle the recording disclosure on outgoing calls?

You have two options, and you can choose whichever feels more natural for your use case:

* **Use the privacy warning toggle.** A consistent pre-recorded disclosure plays at the start of every call, regardless of direction. The advantage is consistency and a clear separation between the disclosure and the conversation; you can even use a different voice for the warning.
* **Embed the disclosure in your instructions.** Have the channel say it as part of the opening greeting, for example: *"Hi, this is Jenna from Acme. Please note this call may be recorded for quality purposes. I'm calling because…"* The advantage is a more conversational feel on outgoing calls, where some recipients are more likely to stay engaged when the disclosure flows naturally with the greeting rather than playing as a separate prompt.

Both approaches satisfy the compliance requirement that the disclosure be delivered at the start of the call. Pick the one that fits your brand, and whichever you choose, make sure every recorded call includes the disclosure in some form.

### What happens when the call hits the time limit?

If you've set a max call duration, it wraps up gracefully as the limit approaches and the call ends when it hits. You can also leave the limit unset, in which case calls run as long as the conversation does. See **Max call duration** under [#voice-and-call-settings](#voice-and-call-settings "mention").

### What happens for incoming calls outside business hours?

Spara doesn't currently offer a platform-wide business hours setting, but the channel can behave differently depending on the time of day. For example, if a lead calls outside your hours, you can instruct it to skip the live transfer and instead book a meeting with a rep through the calendar. It has access to the current time and timezone and can branch on it.

### Can the Phone channel send SMS or text messages?

Not directly. To follow up by text, use a workflow with a [Send Text Step](/build/workflows/steps/send-text) step. Outgoing SMS requires Twilio A2P registration; your Spara account team can guide you through the registration process.

### Will Spara reuse the same lead record when the same phone number calls back?

Yes. Spara associates calls from the same phone number with the same lead, so conversation history, captured fields, and CRM context carry across repeat calls instead of creating duplicates.


# SMS

How the SMS channel automates sales conversations over text.

The **SMS channel** automates sales interactions over text message, handling incoming texts from leads and sending outgoing texts through [Workflows](/build/workflows).

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-47656467af3105dcc1d1e09ccf2c66b37a581759%2FText%20Agents.png?alt=media" alt=""><figcaption><p>The SMS channel configuration.</p></figcaption></figure>

* **Incoming replies**: Spara responds to incoming text messages from leads, answering questions and moving them through your sales funnel without rep involvement.
* **Automated outgoing texts**: Spara sends texts to leads as part of a workflow. For example, after a lead submits a form, a workflow can send an immediate text to prompt them to schedule a meeting.

Spara does not send cold or unsolicited outgoing texts outside of your workflows.

## Configuration

### Instructions

The SMS channel is configured through its [AI Instructions](/build/channels/configuring/ai-instructions), the same way every channel is built. Use them to define the channel's persona, tone, and how it should handle common scenarios like questions, objections, and handoffs to a rep.

### Phone number setup

Each SMS channel can be assigned an incoming phone number on the **Configuration** tab. This is the number it answers texts on and sends outgoing texts from. Phone numbers are provisioned through Twilio. Contact your Spara account manager to enable texting and provision numbers for your account.

{% hint style="warning" %}
**Twilio registration required.** Before your SMS channel can send or receive messages, your brand and messaging campaign must be registered and approved through Twilio's A2P 10DLC process. This industry-wide requirement verifies your business and ensures your messaging complies with carrier standards. Your Spara CSM handles the registration, but you'll need to provide a campaign description, links to your Terms of Service and Privacy Policy (with SMS opt-in language), and sample messages. See [Guide: Text Agent Onboarding](https://docs.spara.com/guides/onboarding-guides/text-agent-onboarding) for full details.

Until registration is approved, Spara will not send texts from the number. A text the agent or a workflow would have sent appears in the lead's conversation marked **Not sent**, and **Settings → Phone Numbers** shows the number's registration status. A text agent on an unregistered number also can't be published, and neither can a workflow with text steps — publish either once registration is approved.
{% endhint %}

{% hint style="info" %}
A phone number is required to publish — the number is what routes incoming texts to the channel, so an SMS channel can't go live without one. Each phone number can only be assigned to one published SMS channel at a time. If you try to publish one with a number already in use, you'll see a conflict error.
{% endhint %}

## Outgoing texts with workflows

The [Send Text Step](/build/workflows/steps/send-text) step in workflows lets you send personalized outgoing texts to leads as part of a broader automated sequence. Pair it with **Wait** and **Condition** steps to build multi-touch SMS follow-up flows.

{% hint style="info" %}
**Per-recipient frequency cap.** Spara enforces a daily ceiling on outgoing texts sent to any single lead. When the cap is reached, further outgoing texts to that lead are skipped for the remainder of the day.
{% endhint %}

## Opt-outs

Spara stops texting a number as soon as its owner asks. A reply of **STOP**, **UNSUBSCRIBE**, **CANCEL**, **END**, or **QUIT** opts the number out, and your carrier confirms it automatically. Spara also reads every other text a lead sends for an opt-out request, whether it is a sentence like "please stop texting me", a note that you have the wrong number, like "this isn't Emma's phone", or a "yes please" to the agent's own offer to stop. If a lead asks the agent to stop in the middle of a conversation, the agent records the opt-out itself and sends one short confirmation, then nothing more. This is built in and always on; you do not need to add anything to your SMS channel's instructions.

When a lead asks to stop, Spara:

* Records the opt-out against the phone number, for your whole workspace.
* Skips every later [Send Text Step](/build/workflows/steps/send-text) step to that number, and the workflow continues to the next step.
* Does not answer the text that asked to stop (other than the agent's one confirmation when the lead asked the agent directly).

By default, a text opt-out also stops calls to the number and emails to the lead's address. A reply of **START** opts the lead back in on all three. To have a text opt-out cover texts only, turn off **Cross Channel Opt-Outs** in [Settings](/platform/settings).


# Product Demo

How Spara's Product Demo channel delivers live, voice-narrated product demos to prospects.

The **Product Demo channel** delivers live, interactive product demos over voice. It narrates your product's key features, shows matching screenshots on screen, answers questions naturally, and books a follow-up meeting at the end, all without a rep on the call. It lets every interested visitor get a fast, personalized walkthrough the moment they want one, instead of waiting for a human demo slot.

{% hint style="info" %}
The Spara team can help with initial setup for your Product Demo channel, including a starting prompt, features, screenshots, and opening visual. Once you're live, you have full control over the prompt and all sections described below.
{% endhint %}

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-d935bb1cdc9fb5cd33c2b7299e7d67325f483f7e%2FProduct%20Demo.png?alt=media" alt=""><figcaption><p>A Product Demo channel's Overview: its instructions, features, and visuals.</p></figcaption></figure>

## Editing the AI Instructions

The [AI Instructions](/build/channels/configuring/ai-instructions) are the natural-language prompt that drives the channel's behavior: how it introduces itself, which features it covers, how it handles pricing questions, and how it wraps up the call. To edit them, open [**Agents**](https://app.spara.co/agents), click into your Product Demo channel, and go to the **Instructions** tab.

The prompt is broken into sections with clear headers. You have full control over all sections.

### Sections

* **IDENTITY AND PRIMARY OBJECTIVE**: who the channel is and what it's trying to accomplish on the call
* **DEMO FLOW**: the order, pacing, and state transitions of the demo
* **DEMO FEATURE PRIORITIES**: default feature order and which features to proactively introduce vs. wait for the prospect to raise
* **FEATURE GUIDANCE**: how the channel navigates visuals within a feature and transitions between features
* **PRICING**: how the channel talks about pricing when a prospect asks
* **DISQUALIFICATION HANDLER**: how the channel responds when a prospect is not a good fit
* **EXISTING CUSTOMER HANDLER**: how the channel handles someone who is already a customer
* **OFF TOPIC AND DISENGAGED VISITOR HANDLER**: how the channel handles off-topic or disengaged visitors
* **BOOKING LOGIC**: when and how the channel nudges toward booking a meeting
* **POST BOOKING FLOW**: qualification questions collected after a meeting is booked
* **WRAP-UP**: how the channel closes the conversation when a meeting is not booked

### Saving and publishing

Save changes to the prompt by clicking **Save draft**. Drafts are safe to iterate on. They don't affect prospects until you publish them, and you can test a draft using the demo link described in [#testing-your-channel](#testing-your-channel "mention").

Click **Publish** when you're happy with the results. The published version is the one your prospects interact with. For more on the draft/publish flow, see [Saving & Publishing](/build/channels/configuring/saving-and-publishing).

## Features

A **feature** is a single unit of your demo (one product channel, value proposition, or story) along with the screenshots shown while narrating it. The channel chooses which features to cover and in what order based on what the prospect is interested in, so good feature content is what makes the difference between a generic pitch and a tailored walkthrough.

Features are shared across all Product Demo channels in your account.

### Creating and deleting features

Open your Product Demo channel from [**Agents**](https://app.spara.co/agents), click the **Features** tab, and click **Create new** to add a feature. Click an existing feature to edit it, or use the delete action to remove one you no longer need.

One feature is the demo's **default**: the one the agent leads with when a prospect opens with something broad like "show me the demo" or "what does your product do?". When Spara generates features for you, it also writes an **Overview** feature that tours the whole product and pins it as the default, shown first in the Features tab. To pick a different default, open a feature's menu and choose **Make Default Feature**.

### Editing a feature

Each feature has a **Description** (markdown content the channel reads) and one or more **Visuals** (screenshots or images it can show on screen during the demo).

**Description.** The description is what the language model reads when deciding how to narrate this feature. Keep it dense and concrete. Think "notes for a rep", not marketing copy. Spell out the exact proof points, objection-handling lines, and examples you want it to draw from.

The base prompt is tuned to look for a specific markdown structure in every feature, so sticking with these headers gives the best results:

```markdown
### Hook
### Key Talking Points
### Proof    <!-- optional -->
### Q&A
```

Add as much guidance under each header as you need. The more specific, the better the narration will be.

**Visuals.** Every feature should have **at least one visual**. Visuals are the screenshots displayed while narrating this feature. Add more than one if you want to walk through multiple screens for the same feature; leave it at one if the feature is mostly conceptual. Use the visual selector on the feature page to attach assets. To make a visual clickable, give it a guided walkthrough, or add links that let prospects steer the demo from the screen, see [Visuals and Interactivity](/build/channels/product-demo/visuals-and-interactivity).

{% hint style="info" %}
A feature without a visual will still work, but there will be nothing to show on screen while it's talking. Prospects get a much better experience when every feature has at least one image tied to it. To capture screenshots from your product, use the [Spara Scanner](/build/channels/product-demo/spara-scanner) Chrome extension.
{% endhint %}

## Documents

The **Documents** tab in Product Demo settings lets you upload source documents (PDF, DOCX, or Markdown files) that the demo's ingestion pipeline uses to build knowledge for the channel. Use this for demo-specific reference material (white papers, battlecards, detailed feature specs) that you don't want appearing in the main Knowledge Base. Documents uploaded here are excluded from the Knowledge > Documents tab.

To upload a document, open your Product Demo channel from [**Agents**](https://app.spara.co/agents) and go to the **Documents** tab. Click **Upload** and select a PDF, DOCX, or Markdown file. The document is processed in the background once uploaded. To edit or remove a document, click it in the list to open the edit drawer.

## Theme

Each Product Demo carries its own branding, so two demos in the same workspace can look completely different. Open the demo from [**Agents**](https://app.spara.co/agents) and go to the **Theme** tab.

* **Typography:** The font used throughout the demo. Any Google Font is available.
* **Background:** The page behind the demo canvas and the transcript panel. It is a soft animated backdrop — a gradient, a glow, drifting orbs and a dot grid — and your color re-tints all of it, so pick the hue you want the demo to sit in rather than a flat fill. Leave it empty for Spara's default purple.
* **Chat background:** The transcript panel that sits to the right of the demo canvas (below the canvas on mobile).
* **Bot bubble / Bot text:** The agent's messages in the transcript.
* **Lead bubble / Lead text:** The prospect's own messages in the transcript.
* **CTA background / CTA text:** The call-to-action buttons, such as **Talk to Sales**.
* **Disclosure text:** The messages Spara shows in the demo area itself — "Your demo will appear here" before the first visual, "Your call has ended" afterwards.
* **Border:** Every border on the demo — the visual canvas, the transcript panel, and the chat input.

The **Live preview** below the fields updates as you pick colors, so you can check that your bubble and text colors stay readable together before anyone sees them.

{% hint style="info" %}
The theme is not part of the demo's draft. **Save changes** applies it to the live demo immediately — there is no publish step, and **Discard draft** will not revert it.
{% endhint %}

Duplicating a demo copies its theme. A new demo starts unthemed, which renders in Spara's default colors.

## Opening visual

The opening visual is the first image or video shown to the prospect when the demo call starts, before the channel begins speaking. To set it, go to your Product Demo channel's details page, open the **Settings** tab, and use the **Opening Visual** picker to search for and select a visual. If no opening visual is set, prospects will see a blank screen until the channel shows a visual during the demo.

For how to produce one, including the screenshots to gather and the prompt to use, see [Opening Visual](/build/channels/product-demo/opening-visual).

## Opening suggested responses

After the greeting, a prospect faces an empty chat panel until they think of something to say. **Opening suggested responses** gives them up to three buttons to click instead, shown alongside the agent's greeting. Set them on the channel's **Settings** tab, up to three responses of 64 characters each, for example "Give me an overview.", "What does your product do?", or "How does pricing work?".

The agent offers exactly what you type, in order, and only with the greeting. Later in the demo it suggests its own replies based on the conversation. Leave the field empty to show no opening buttons. Like the rest of the channel's settings, changes take effect when you publish.

## What prospects see

A prospect joins the demo over voice, with your visuals on a stage and a transcript panel beside it. They can mute the agent's voice, type instead of talking if their microphone is unavailable, step through any walkthrough you have authored, and click **Talk to Sales** to open your booking calendar in place of the visual, then **Back to demo** to pick up where they left off. None of this needs configuration; see [Visuals and Interactivity](/build/channels/product-demo/visuals-and-interactivity#what-prospects-can-do) for the full list.

## Auto-open links

Add **`?spara_demo_open`** to any URL on a page that already loads the Spara script, and the demo opens by itself when a visitor arrives:

```
https://yoursite.com/?spara_demo_open
```

That is the whole setup — nothing to configure in the platform and no code to add to your site. Use these links in cold emails, LinkedIn messages, SMS campaigns, or a QR code on a conference booth. The parameter sits alongside your existing ones, so campaign tracking keeps working:

```
https://yoursite.com/pricing?utm_source=email&spara_demo_open
```

To open one specific demo instead of your account's default selection, give the parameter a value:

```
https://yoursite.com/?spara_demo_open=xyz123
```

The value can be either your **agent ID** (splitting traffic across that agent's variants if you run an A/B test) or a **demo ID** (pinning one variant). Spara recognizes both, so you don't need to say which you're using. The agent ID is on the folder icon in the channel header; the demo ID is the last segment of the public demo link, from the copy-link button. If the value matches neither, the demo still opens using your account's published Product Demo channels.

A few things worth knowing:

* The link works on **any** page that loads the Spara script, including pages you've excluded from the chat launcher. A recipient who clicked an auto-open link is asking for the demo, so page rules don't apply.
* While the demo is open the chat launcher is hidden, and it comes back when the visitor closes the demo.
* The demo opens once per page load. A visitor who closes it can reopen it by reloading the link.
* The parameter name is exactly `spara_demo_open`, lowercase.

## Testing your channel

To test a Product Demo channel end-to-end, open it from the [**Agents**](https://app.spara.co/agents) page and click **Open demo**. This launches the demo in a new tab in test mode, running exactly as a prospect would experience it: voice, visuals, calendar booking, and all.

Use it to review your changes before publishing, and share the link with teammates on your Spara account for feedback. The workflow is: click **Save draft**, open the demo, talk through your changes, then click **Publish** once you're happy with how it sounds.

## FAQ

### Who controls what?

The Spara team can help with initial onboarding: a starting prompt, the first set of features, the screenshots tied to each feature, and the opening visual. After that, you have full control over the AI Instructions, the feature descriptions and visuals, the documents, and when to publish changes.

### How do I know if a feature is working?

Open the demo with **Open demo** and ask about that feature directly. Listen for whether it mentions the hook, covers the key points you listed, and uses the right proof. If it's skipping things, tighten up the description and try again.

### Can I test a draft before publishing?

Yes. Click **Save draft**, then click **Open demo**. The demo runs in test mode against your latest saved state, so you can iterate on the prompt and features before clicking **Publish**.

### Can I link directly to the Product Demo from an email or CTA?

Yes. Add `?spara_demo_open` to any page on your site that already loads the Spara script, and the demo opens on its own when the visitor arrives — `https://yoursite.com/?spara_demo_open`. Nothing to install and no code to write. See [Auto-open links](#auto-open-links) above. For a button on your site, call `SparaActions.openProductDemo()` from its click handler instead.

See [Guide: Product Demo Use Cases](https://docs.spara.com/guides/platform-guides/product-demo-use-cases) for step-by-step setup for website CTAs, outgoing email campaigns, chat-to-demo transitions, and more. For the full JavaScript reference, see [Developer: Javascript API](https://docs.spara.com/developers/spara-api/javascript-api).


# Opening Visual

How to create the opening visual for a Product Demo: gather source screenshots, prompt an image tool, and set the result on your demo.

The opening visual is the first thing a prospect sees when a demo starts, before the agent says a word. It holds the screen during the few seconds where a visitor decides whether to stay, so it is worth treating as a title slide for the demo rather than as decoration.

A good opening visual answers one question immediately: what is this company, and what am I about to be shown? This page covers how to produce one with an AI image tool and how to put it live on your demo. For everything else about the channel, see [Product Demo](/build/channels/product-demo).

## What makes a good opening visual

The best results come from treating the slide as a piece of brand collateral, not a copy of your website:

* **One logo, shown exactly as it appears in your brand assets.** No redrawing, no recoloring.
* **One headline**, usually the positioning line already on your homepage.
* **One product visual** that shows what the product actually does.
* **A restrained amount of customer proof**, such as three or four logos or a single rating.
* **No website chrome.** No navigation bars, buttons, forms, cookie banners, or calls to action. A prospect cannot click them, and they make the slide look like a screenshot instead of a slide.

Design for 16:9. The demo scales the image to fit the stage without cropping it, and the stage is wide, so a 1920 x 1080 image fills the space. A square or portrait image is shown with empty space on either side.

## Gather your source screenshots

Image tools blend their reference images together by default. If you attach four screenshots and say "use these as source material," the model averages them and you get a generic slide with an approximated logo. The fix is to tell the model which screenshot owns which part of the output.

Collect at least four screenshots, each one the authoritative source for a different element:

1. **Logo or brand mark.** Crop tight on the logo, from your site header or brand page.
2. **Hero messaging.** The top of your homepage, with the headline and supporting copy readable.
3. **Product or visual system.** The clearest shot of the real product UI, an architecture diagram, or a key workflow.
4. **Customer proof.** The customer logo strip, a testimonial, or a ratings badge.

Add more screenshots if you want the model to pick up secondary brand colors, iconography, textures, photography treatment, or spacing patterns. To capture clean screenshots of your own product, use the [Spara Scanner](/build/channels/product-demo/spara-scanner) Chrome extension.

## Write the prompt

Use an image generation tool that accepts several reference images in one prompt. The prompt itself has two parts: the run block changes for every company and goes first, and the standard instructions stay the same every time and go underneath. Attach the screenshots to the same message, in the order the run block names.

### The run block

Edit this for the company you are building the demo for:

```
COMPANY: [company name]

HEADLINE SOURCE: Screenshot 2
PRODUCT VISUAL SOURCE: Screenshot 3
LOGO SOURCE: Screenshot 1
CUSTOMER LOGOS SOURCE: Screenshot 4

PRIMARY VISUAL IDEA:
[one sentence naming the steps the product moves a user through, in order]

BRAND CHARACTER:
[background tone, typography color and weight, accent color, overall design feel]

DO NOT INCLUDE:
Buttons, navigation, forms, website chrome, CTAs.
```

Two fields do most of the work. **PRIMARY VISUAL IDEA** is what keeps the slide from being a logo on a gradient: it tells the model what story the product visual should tell. **BRAND CHARACTER** is what keeps the result from defaulting to generic SaaS blue.

The source lines are the attachment order you actually used, so you do not have to reorder your screenshots to match the standard instructions. If the run block and the standard mapping disagree, the run block wins.

### The standard instructions

Paste this underneath the run block, unchanged:

```
Create a single title slide for a product demo.

OUTPUT
- One 16:9 image, 1920 x 1080.
- A title slide, not a web page.
- Legible at a glance: one headline, one product visual, minimal supporting copy.

## Source Screenshot Mapping

Use every attached screenshot intentionally. Treat the screenshots as separate
sources for different parts of the final slide rather than as layouts to reproduce.

[Screenshot 1 - Logo / Brand Mark]
Use this as the authoritative source for:
- company logo
- logo proportions
- primary brand colors

[Screenshot 2 - Hero Messaging]
Use this as the authoritative source for:
- headline
- supporting copy
- primary positioning
- typography character

[Screenshot 3 - Product / Visual System]
Use this as the authoritative source for:
- product UI
- product architecture
- key workflows
- illustrations or photography
- visual motifs

[Screenshot 4 - Customer Proof]
Use this as the authoritative source for:
- customer logos
- trust statement
- ratings or proof points, if useful

[Additional Screenshots]
Use these to understand:
- secondary brand colors
- UI styling
- textures
- photography treatment
- gradients
- iconography
- spacing and composition patterns

PRIORITY RULES
1. Preserve the logo and brand identity exactly from the supplied screenshots.
2. Preserve the core headline and message unless explicitly instructed to rewrite it.
3. Use product visuals to explain what the company actually does.
4. Use only a restrained subset of customer proof.
5. Do not copy the website layout itself.
6. Resolve conflicts by favoring the screenshot that most directly represents that element.
7. If the run block above names a different screenshot for an element than this
   mapping does, follow the run block.
```

### Example: a PandaDoc run block

```
COMPANY: PandaDoc

HEADLINE SOURCE: Screenshot 2
PRODUCT VISUAL SOURCE: Screenshot 4
LOGO SOURCE: Screenshot 1
CUSTOMER LOGOS SOURCE: Screenshot 3

PRIMARY VISUAL IDEA:
Agreement creation, then fillable fields, then signature, then completed deal.

BRAND CHARACTER:
Warm off-white, dark charcoal typography, restrained PandaDoc green, clean
editorial B2B design.

DO NOT INCLUDE:
Buttons, navigation, forms, website chrome, CTAs.
```

## Check the result before you use it

Most first attempts are close but need one correction. Look for these:

* **The logo is redrawn, recolored, or slightly wrong.** Re-attach the logo screenshot on its own and repeat that it must be preserved exactly.
* **Navigation, buttons, or a browser frame appeared.** Repeat the DO NOT INCLUDE line.
* **The slide is a copy of your homepage.** Repeat priority rule 5 and describe the composition you want instead.
* **The headline was rewritten into marketing filler.** Quote the exact headline in the run block and say to use it verbatim.
* **Ten customer logos crowd the slide.** Name the specific number you want.
* **Invented text or fake product UI.** Point at the product screenshot again and say every screen element must come from it.

Read every word in the generated image before you publish it. Image models misspell product names and invent plausible-looking copy, and this slide is the first thing a prospect sees.

## Add the visual to your demo

{% stepper %}
{% step %}

### Upload the image

Go to [**Settings > Product Demo > Visuals**](https://app.spara.co/settings/product-demo/visuals) and click **Upload visual**. Accepted formats are PNG, JPG, GIF, SVG, and MP4, up to 25 MB. Give it a name you will recognize in the picker, such as "Opening visual".
{% endstep %}

{% step %}

### Select it on the demo

Open your Product Demo channel from [**Agents**](https://app.spara.co/agents), go to the **Settings** tab, and use the **Opening Visual** picker to search for the visual you just uploaded.
{% endstep %}

{% step %}

### Save and publish

Click **Save draft**, click **Open demo** to see it in place, then click **Publish**. The opening visual is part of the versioned configuration, so prospects keep seeing the old one until you publish. See [Saving & Publishing](/build/channels/configuring/saving-and-publishing).
{% endstep %}
{% endstepper %}

## FAQ

### Can I use a video instead of an image?

Yes. The opening visual can be an MP4 as well as an image, up to 25 MB and 30 seconds. It plays once, automatically and without sound. Make sure the last frame stands on its own, because that is what the prospect looks at for the rest of the introduction.

### Does every demo need its own opening visual?

Each Product Demo channel has its own opening visual setting, so demos aimed at different segments or industries can open differently. If you run an A/B test, each variant carries its own setting too, which makes the opening visual something you can test.

### What happens if I do not set one?

Prospects see a blank canvas until the agent shows its first visual during the demo. The Settings tab flags this with a warning.

### Can Spara create the opening visual for me?

Yes. The Spara team can help with initial setup for a Product Demo channel, including the opening visual. After onboarding you can replace it at any time by following the steps above.


# Visuals and Interactivity

Manage the screenshots and videos a Product Demo shows, and make them interactive with clickable regions, guided walkthroughs, and links.

Visuals are the screenshots, images, and short videos a Product Demo shows on screen while the agent talks. Out of the box a visual is a picture the agent narrates over. This page covers how to manage your visual library and, when it helps the demo, how to let prospects click, follow a guided tour, or steer the demo from the visual itself.

For how features choose their visuals, see [Product Demo](/build/channels/product-demo). For the first thing a prospect sees, see [Opening Visual](/build/channels/product-demo/opening-visual).

## The visual library

All of your demo visuals live in one library at [**Settings > Product Demo > Visuals**](https://app.spara.co/settings/product-demo/visuals), shared across every Product Demo channel in your account. From there you can:

* **Upload** a PNG, JPG, GIF, SVG, or MP4 up to 25 MB. Videos must be 30 seconds or shorter.
* **Capture** screenshots of your own product with the [Spara Scanner](/build/channels/product-demo/spara-scanner) Chrome extension.
* **Filter** the library to visuals that are **In use**, **Unused**, or used by one particular demo, which is the quickest way to review one channel's screens.
* **Select several** visuals at once to download or delete them.

Click a visual to open its edit drawer, where you set its name, description, interactivity, and links, and see which features use it.

**Name and description.** The description tells the agent when this visual is worth showing on its own, independently of any feature it is assigned to. Spara writes one for each image automatically; edit it if you want to steer the agent.

## Interactivity

By default a visual is inert: the agent shows it, and nothing on it reacts. Turning interactivity on is a choice you make per visual in the edit drawer, under **Interactivity**:

* **None**: The screenshot is shown and no highlight reacts. Links, below, are set separately.
* **Clickable**: Regions of the screenshot outline on hover and take a click. A prospect can click a region to ask about that part of the screen.
* **Walkthrough**: Clickable, plus a guided tour the prospect can start, with the agent highlighting one part of the screen at a time.

Interactivity never changes what the agent says about a visual. Leave it on **None** for title cards, diagrams, and anything that should not look clickable.

### Walkthroughs

A walkthrough is an ordered set of highlights on one visual, each with a name and a line the agent says while it is highlighted. Prospects can step through it at their own pace with **Next step**, or pause and ask a question part way through.

You can build one in two ways from the visual's edit drawer:

* **Create walkthrough** draws the highlights from scratch. Give each highlight a name and what the agent should say, in order. A walkthrough needs at least two steps.
* **Generate walkthrough** asks Spara to write one for you. It is available once the visual has regions and a page URL to work from, which Spara Scanner captures provide automatically.

Walkthroughs work on uploaded visuals as well as Scanner captures. Open the walkthrough with the pencil icon to edit the steps, and use **Edit walkthrough** to reorder or remove them.

### Links

A screenshot often contains things that look clickable, such as a navigation bar, a tab strip, or an agenda slide. Links make those boxes do something: when a prospect clicks one, it sends a request to the agent in the prospect's own words, and the agent answers it like any other question, usually by showing the screen behind it.

To add links, open the visual's edit drawer, click **Add links** under **Links**, and draw a box over each area. Give every box a request written the way a prospect would ask for it, for example "Show me how pipeline automation works" or "What does pricing look like?". Every link needs a request before you can save.

The **Active** switch under **Links** turns a visual's links on and off without deleting them, so you can prepare links in advance or pause them while you rework a feature. Links are independent of the **Interactivity** setting: a title card with interactivity set to **None** can still carry the links that act as the demo's menu.

{% hint style="info" %}
Links describe what to ask for, not which feature to open. That keeps them working when you rename, split, or reorder features, and lets one shared visual behave correctly in several demos.
{% endhint %}

## What prospects can do

Beyond talking, a prospect in a demo has a few controls of their own. There is nothing to configure for these.

* **Mute the agent's voice.** A speaker button beside the microphone silences the agent without ending the call or muting the prospect, for example in an open office or on a shared screen. The agent keeps listening and the transcript keeps updating.
* **Type instead of talk.** If their microphone is blocked, missing, or in use by another app, the demo tells them so and they can keep going by typing in the chat panel. The agent answers in voice and text as usual.
* **Book a meeting without leaving the demo.** **Talk to Sales** opens your booking calendar in place of the visual, and **Back to demo** returns to it where they left off.
* **Follow or skip a walkthrough.** Prospects step through a walkthrough with **Next step**, pause it, or ask a question at any point.

## FAQ

### Why are my visuals suddenly not clickable?

Interactivity is opt-in. Visuals start as **None**, and a visual only becomes clickable when someone sets it to **Clickable** or **Walkthrough** in its edit drawer. Check the setting on the visual, not on the feature.

### Can one visual have different links in different demos?

No. Links belong to the visual, and the visual library is shared across your Product Demo channels. Because a link is a request in words rather than a pointer to a feature, the same link works in every demo that shows the visual: each agent answers it from its own features.

### Do I need Spara Scanner to build a walkthrough?

No. Scanner captures let you **Generate walkthrough** automatically, but any uploaded image can have a walkthrough drawn by hand with **Create walkthrough**.

### Does a walkthrough change what the agent narrates?

Only while the prospect is inside it. The walkthrough's step text is what the agent says during the tour. Outside the tour, the agent narrates from the feature's description as usual.


# Spara Scanner

Download and install the Spara Scanner Chrome extension to capture your product for AI-powered demos.

The **Spara Scanner** is a Chrome extension that captures screenshots and page content from your product. These captures power the visuals your [Product Demo](/build/channels/product-demo) agent shows to prospects during live demos.

## Download

Download the latest version directly, or visit the [Scanner page](https://app.spara.co/settings/product-demo/scanner) in your Spara settings for previous releases.

## Installation

1. **Unzip** the downloaded file
2. Open Chrome and go to `chrome://extensions`
3. Toggle on **Developer mode** (top-right corner)
4. Click **Load unpacked** and select the unzipped folder
5. **Pin** the Spara Scanner icon in your Chrome toolbar for easy access

{% hint style="info" %}
The extension requires Chrome. It is not available on the Chrome Web Store — install it using the steps above.
{% endhint %}

## Getting started

Click the Spara Scanner icon in your toolbar to open the side panel. All controls live here.

### Quick capture

To capture a single page:

1. Navigate to the page you want to capture
2. Click **Capture** in the side panel
3. The screenshot and page metadata download automatically

### Snap (capture a specific state)

For scroll positions, open modals, expanded dropdowns, or other UI states:

1. Get the page into the exact state you want
2. Click **Snap** and enter a short label (e.g., `modal-open`, `below-fold`)
3. The capture downloads with your label as a suffix

### Site exploration

For capturing multiple pages at once, the scanner has a two-phase workflow:

**Phase 1 — Discover.** Enter a client name, set the crawl depth, and click **Discover**. The scanner follows links from the current page and builds a site map of discovered URLs. No screenshots are taken during this phase.

Review the site map and check or uncheck pages to control what gets captured. You can add **exclude patterns** (e.g., `/help*`, `/docs*`) to automatically skip matching paths.

**Phase 2 — Capture All.** Click **Capture All** to screenshot every included page. The scanner navigates to each page, captures a high-resolution screenshot along with page content, and automatically discovers and captures tab states within each page.

You can run Discover again from a different starting page to find pages the first run missed. The site map accumulates across runs.

## Output

Captures download as a folder structure organized by client:

```
{client}/
├── manifest.json          # Capture history
├── sitemap.json           # Site map
├── dashboard/
│   ├── screenshot.png
│   └── capture.json
├── settings/
│   ├── screenshot.png
│   └── capture.json
└── settings--billing/     # Tab capture
    ├── screenshot.png
    └── capture.json
```

Each page gets a `screenshot.png` (3020x1494 pixels) and a `capture.json` with the page title, URL, accessibility tree, and clean text content.

## Updating

When a new version is available, download and unzip it, then go to `chrome://extensions` and click the refresh icon on the Spara Scanner card. Your site maps and capture history are preserved across updates.

## Troubleshooting

**Side panel doesn't open** — Go to `chrome://extensions` and click the reload button on the Spara Scanner card.

**Discover misses pages** — Try a higher depth, or navigate to a different section of the app and run Discover again.

**Capture All skips pages** — Check the manifest from a prior run. Click **Clear All** in the side panel to reset capture history.

**Screenshots show loading spinners** — Some pages take longer to render. Try capturing those pages individually with the **Capture** button, which gives more time for the page to settle.


# Configuring Channels

The building blocks shared by every channel: instructions, abilities, testing, and the draft-and-publish lifecycle.

Every [Channels](/build/channels), whether [Chat](/build/channels/chat), [Email](/build/channels/email), [Phone](/build/channels/phone), [SMS](/build/channels/sms), or [Product Demo](/build/channels/product-demo), is built and run the same way. You write its instructions, give it abilities, test a draft, and publish when it's ready. The pages here cover those shared building blocks once, so each channel page can focus on what's specific to its channel.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-e66c5fbbf6a7ab5abe6a9ef40b83b8de1744341c%2FConfiguring%20Channels.png?alt=media" alt=""><figcaption><p>Every channel is built in the same split-screen editor: instructions on the left, testing on the right.</p></figcaption></figure>

| Building block                                                           | What it does                                                                                                       |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| [AI Instructions](/build/channels/configuring/ai-instructions)           | The natural-language prompt that defines how the channel behaves.                                                  |
| [Abilities](/build/channels/configuring/abilities)                       | Tools the channel can use mid-conversation (calendar, transfer, media, and more).                                  |
| [Testing](/build/channels/configuring/testing)                           | A built-in interface and automated [Testing](/build/channels/configuring/testing#simulations) to validate a draft. |
| [Saving & Publishing](/build/channels/configuring/saving-and-publishing) | A private draft and a single live version per channel.                                                             |
| [A/B Testing](/build/channels/configuring/a-b-testing)                   | Duplicate a channel into variants and split traffic to optimize conversion.                                        |

Not every channel supports every ability. Chat and Phone have the richest toolsets, while Email and SMS operate on text alone. Each channel page covers what's specific to that channel.

## The lifecycle

The same loop applies to every channel:

1. **Write** its [AI Instructions](/build/channels/configuring/ai-instructions) and configure its [Abilities](/build/channels/configuring/abilities).
2. **Test** the draft in the built-in interface or with automated [Testing](/build/channels/configuring/testing), using [Ask Spara](/platform/ask-spara) to diagnose and refine.
3. **Publish** when you're satisfied. See [Saving & Publishing](/build/channels/configuring/saving-and-publishing). Leads only ever interact with the published version.
4. **Optimize** by running an [A/B Testing](/build/channels/configuring/a-b-testing) between variants.

## Ask Spara

The fastest way to build and refine a channel is with [Ask Spara](/platform/ask-spara), the AI assistant built into the platform. It opens in a panel right beside the editor, so you can get help without leaving your work.

While configuring a channel, use Ask Spara to:

* **Draft and rewrite instructions** — describe what you want the channel to do and let it write or revise the prompt for you.
* **Diagnose behavior** — ask why the agent replied a certain way in testing, or point it at a specific message to debug.
* **Audit the prompt** — check for gaps, conflicts, or missing scenarios before you publish.

Every suggested change appears as an **edit card** you review and apply to your draft, so nothing goes live until you publish. Spara recommends keeping Ask Spara open whenever you configure a channel — it turns prompt-writing from a blank-page problem into a conversation. See the full [Ask Spara](/platform/ask-spara) page for everything it can do across the platform.

## Knowledge and analytics

Two more things are shared by every channel, with no per-channel setup required:

* **Knowledge**: channels draw on your [Knowledge](/build/knowledge) base (scraped webpages, uploaded documents) to answer factual questions about your product.
* **Analytics**: every channel automatically tracks its conversion metrics in [Analytics](/pipeline/analytics).


# AI Instructions

How to write and structure the AI instructions that define every channel's behavior.

**AI Instructions** (also called the prompt) are the natural language instructions that define how a channel behaves. Every Spara channel is powered by a large language model, and the instructions you write are the primary way you shape its personality, goals, and responses.

Instructions are available on every channel: [Chat](/build/channels/chat), [Email](/build/channels/email), [Phone](/build/channels/phone), [SMS](/build/channels/sms), and [Product Demo](/build/channels/product-demo).

## What instructions cover

Instructions can cover anything the channel needs to know or do:

* **Persona and tone**: who it is, how it speaks, what company it represents
* **Goals**: what it's trying to accomplish in a conversation (book a meeting, answer a question, qualify a lead)
* **Handling specific scenarios**: objections, pricing questions, competitor mentions, support requests
* **Escalation**: when and how to hand off to a human rep
* **Gathering information**: what fields to collect from the lead, and how to ask for them
* **Content constraints**: what to say and what to avoid

Channels also draw on [Knowledge](/build/knowledge) (scraped webpages and uploaded documents) to answer factual questions about your product. Instructions tell the channel *how* to use that knowledge; the knowledge base provides the facts.

## Structure of the instructions

Instructions are free-form text. You write them in plain language, like briefing a new rep. There's no required format, but a few patterns work well:

**Role and goal up front.** Start with who the channel is and what it's trying to do in one or two sentences. This orients every response the model generates.

**Use sections for distinct scenarios.** Group related instructions under headers (e.g., `## Handling objections`, `## Qualifying questions`). Sections help the model apply the right instructions at the right moment.

**Be specific and literal.** Vague instructions like "be helpful" are less effective than specific ones like "if a lead asks about pricing, share the three-tier overview before asking about their team size."

**Use conditionals for branching behavior.** Instructions like "if the lead mentions a competitor, acknowledge it briefly and pivot to our differentiated value" guide behavior in named situations.

For a deeper walkthrough, see [Guide: Writing Effective Agent Prompts](https://docs.spara.com/guides/platform-guides/writing-effective-agent-prompts).

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-476f396c257cb6cde825fe812d3617e2bb413809%2FAI%20Instructions.png?alt=media" alt=""><figcaption><p>The AI Instructions panel in the editor.</p></figcaption></figure>

## The instructions editor

Chat, Email, and SMS channels, and your account FAQ, are edited in a document editor that treats each header as a section. Every section can be collapsed, dragged to a new position, made a subsection of the one above it, or deleted from its menu, so you can reorganize a long prompt without cutting and pasting. **Expand all** and **Collapse all** sit above the document, and the toolbar covers basic formatting such as bulleted lists.

Anyone who can edit the channel sees the editor. Team members with view-only access see the same sections read-only.

### Inserting fields

To have the agent use a value from the lead's record, insert the field rather than describing it. Type `/` at the start of a line or after a space to open the field menu, search for the field, and pick it. It appears in the text as a chip with the field's display name, for example **First Name** or **Company**, and the agent reads the lead's value when it runs. Click a chip to see which field it is; fields are defined in your [Data Model](/build/data-model). Typing `/` inside a word, such as a URL, just types a slash.

The same menu works in the workflow text editor for Send Email and Send Text steps.

## Writing instructions with Ask Spara

You don't have to write instructions from a blank page. [Ask Spara](/platform/ask-spara), the AI assistant built into the platform, drafts and refines instructions for you from a plain-language description of what you want the channel to do.

Open it beside the editor and ask it to write a first draft, rewrite a specific section, or check your instructions for gaps and conflicts. It cites the exact lines it's referring to and proposes each change as an **edit card** you apply to your draft. Using Ask Spara is the fastest way to get from an idea to well-structured instructions — and to keep them sharp as your goals change. See the full [Ask Spara](/platform/ask-spara) page for everything it can do.

## FAQ

### How long should instructions be?

As long as necessary, but no longer. Most well-configured channels have instructions between 200 and 800 words. If instructions are very long, break them into clearly labeled sections so the model can navigate them. Excessively long or redundant instructions can reduce coherence.

### Can I use markdown formatting?

Yes. Headers, bullet points, and bold text are all supported and help the model parse structure. Avoid tables, since they're rarely rendered correctly in prompt context.

### What's the difference between instructions and Knowledge?

Instructions tell the channel *how* to behave: its goals, tone, and handling of scenarios. Knowledge provides factual content it can draw on when answering questions. In practice: put product facts, FAQs, and support content in Knowledge. Put goals, tone, and scenario handling in instructions.


# Abilities

Tools channels can call during a conversation: calendars, transfers, media, email, and more.

**Abilities** are tools a channel can invoke during a live conversation. While [AI Instructions](/build/channels/configuring/ai-instructions) define what a channel says, abilities define what it can *do*: show a calendar, transfer a call, surface a video, send an email, or call an external API.

Not every channel supports abilities. [Chat](/build/channels/chat) and [Phone](/build/channels/phone) have the richest toolsets, while [Email](/build/channels/email) and [SMS](/build/channels/sms) operate on static content and do not have real-time tool access.

Abilities are configured on the **Abilities** tab of a channel's editor.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-66e166a67c6e1854a1259827c93dda8bb84d022c%2FAbilities.png?alt=media" alt=""><figcaption><p>The Abilities tab, where you configure what a channel can do during a conversation.</p></figcaption></figure>

## Abilities by channel

| Ability                        | Chat | Phone | Email | SMS |
| ------------------------------ | :--: | :---: | :---: | :-: |
| Show calendar                  |   ✅  |   ✅   |   No  |  No |
| Show media (video, PDF, image) |   ✅  |   No  |   No  |  No |
| Send email                     |   ✅  |   No  |   No  |  No |
| Transfer (cold or warm)        |  No  |   ✅   |   No  |  No |
| API request                    |  No  |   ✅   |   No  |  No |

***

## Chat abilities

The Chat channel can show calendars, surface media (video, PDF, image), and send emails during a live conversation. Calendar booking is enabled by default and can be turned off per channel on its Settings tab; media display and email sending are opt-in.

See [Chat](/build/channels/chat) for setup instructions.

***

## Phone abilities

The Phone channel supports calendar booking, call transfers (cold and warm), and external API requests, all without leaving the phone call.

Phone abilities are configured on the **Abilities** tab.

See [Phone](/build/channels/phone) for setup instructions.

***

## FAQ

### How does a channel decide when to use an ability?

Channels use their [AI Instructions](/build/channels/configuring/ai-instructions) as the primary guide. You specify the conditions under which each tool should be used, such as "show the calendar when the lead is ready to book" or "transfer to sales when the lead is qualified and asking to speak with someone." The model reasons about whether those conditions are met at each point in the conversation.

### Can I give one Chat channel multiple calendars?

Yes. Upload each calendar as a separate asset, give them distinct names, and write instructions that specify which calendar to use for which scenario (e.g., "use the Sales calendar for prospects, the Support calendar for existing customers").

### Can a Phone channel transfer to a specific rep by name?

Yes. Configure multiple named transfer destinations in the Abilities tab and instruct it on which destination to use in which context.


# Testing

How to test channels using the built-in testing interface and automated Simulations.

Every Spara channel has a built-in testing interface that lets you interact with a draft before it goes live. Testing always runs against your **current draft** (not the published version), so you can iterate freely without affecting real leads.

The testing interface is accessible in two places:

* **In the editor**: the test panel, opened from the editor toolbar
* **On the** [Testing](/build/testing) **page**: a standalone view for side-by-side comparison of multiple channels

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-4920d47e2b1ce6296a27af57c503db28ff178382%2FTesting%20Interface.png?alt=media" alt=""><figcaption><p>The Testing panel in the editor showing a simulated chat conversation.</p></figcaption></figure>

***

## Test interface by channel

| Channel | Test interface                                                                                                        |
| ------- | --------------------------------------------------------------------------------------------------------------------- |
| Chat    | Simulated chat conversation in the editor, or in the Navigator, Mobile, or Fullscreen interface from the Testing page |
| Phone   | Simulated call in your browser, or a real call to your phone                                                          |
| Email   | Send a simulated incoming email, review the draft reply                                                               |
| SMS     | Simulated SMS exchange                                                                                                |

***

## Using the test interface

### Running a test

Open the right-hand panel in any editor and start interacting. For Chat, type messages as if you're a lead. For Phone, click to start a test call. The channel responds using your current draft instructions.

**Test conversations are isolated.** Test leads are kept out of your Leads list, workflows, notifications, CRM sync, and analytics.

**Test settings.** Click the gear icon to set **Known Fields**: values the test lead starts with, such as `first_name`, `company_name`, UTM fields, or any custom field. You can also type a field key that isn't in the dropdown. To test a rule that depends on the visitor's location, add `ip_country` with a two-letter country code (for example `AU`). This sets both IP Country Code and IP Country Name and takes precedence over your own location, so you don't need a VPN. IP Region, IP City, and Timezone still reflect where you are testing from unless you set them too.

**View fields.** Open **View fields** at the bottom of the panel to see what the agent currently knows about the test lead, including the location fields, so you can confirm the context the agent will have.

### Reviewing a response

Each response can be inspected inline:

* **Lightbulb icon**: Explains why it responded the way it did, citing specific instructions it followed.
* **Thumbs down icon**: Flags the response as incorrect or unhelpful, and offers line-by-line suggestions for improving the prompt to prevent the issue.

Use these tools to understand model reasoning, especially when a response doesn't match your expectations.

### Resetting the test

Click the refresh or clear button to start a new test conversation. Each test session begins with a fresh test lead: no prior messages, and only the Known Fields you set in Test settings.

***

## Simulations

Simulations let you define automated test scenarios and run them in batch, a faster way to validate a channel against a set of known interactions without manually testing each one.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-789f4aa4b170a08dc78678ae8ec1ebefe42ea45f%2FSimulations.png?alt=media" alt=""><figcaption><p>The Simulations tab showing three passing simulations and a 100% pass rate.</p></figcaption></figure>

### Creating a simulation

Each simulation has two parts:

1. **Simulated user behavior**: A plain-language description of how the simulated lead should act. For example: "The lead is interested in enterprise pricing and wants to know if there's a volume discount."
2. **Success criteria**: A list of outcomes the channel must achieve for the simulation to pass. For example: "It asks for the lead's team size before providing pricing details."

Simulations can be as narrow (testing a single objection) or as broad (testing a full qualification flow) as you need.

### Running simulations

Simulations can be run individually from their detail view, or in batch from the Simulations list. Batch runs execute all simulations concurrently.

Each simulation run generates a **pass** or **fail** result. Failed simulations include an explanation of what went wrong and, where relevant, point to the specific instruction that wasn't followed, or flag when the simulation's expected behavior conflicts with the instructions.

### When to use simulations

Simulations are especially useful when:

* You've made a significant change to your instructions and want to verify it didn't break existing behavior
* You want to test edge cases (unusual questions, hostile leads, out-of-scope requests) without relying on live traffic
* You're onboarding and want confidence before going live

***

## FAQ

### Does testing affect my analytics or workflow triggers?

No. Test conversations are isolated from production. Test leads stay out of your Leads list, don't trigger workflows, and don't appear in analytics.

### Can I test with a specific lead's context?

Set the lead's fields in **Test settings** before you start (e.g., `first_name`, `company_name`, `ip_country`) to simulate a personalized experience. Workflow tests can also start from an existing lead. For automated coverage, use [Simulations](#simulations).

### Can I run simulations against a published version?

Simulations always run against the current draft. If there's no draft, a copy of the published version is used as the starting point.

### How do I use Ask Spara during testing?

Use the **?** or thumbs-down button on any agent message to open [Ask Spara](/platform/ask-spara) with that message in context. It can explain why the agent replied that way, or suggest prompt edits to fix a behavior you saw in testing. Ask Spara opens beside the test panel, so you can keep testing while you read the answer.


# Saving & Publishing

How drafts, publishing, and version history work across all channels.

Every Spara channel has two states at any given time: a **draft** and a **published version**. They work independently: your team edits and tests the draft while leads only ever interact with the published version.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-18f92a8847ded328fc56f8e2bd07f45131e9bcbc%2FSaving%20and%20Publishing.png?alt=media" alt=""><figcaption><p>Version History lists every published version, so you can restore any one to roll back.</p></figcaption></figure>

## Drafts

Any change you make in the editor (to the instructions, abilities, or configuration) is saved to the draft. Drafts are private. They do not affect live conversations until you explicitly publish.

To save changes to your draft, click **Save draft** in the editor header. You can save as often as you like. The draft persists between sessions, so you can make changes over multiple sittings before publishing.

**Testing always uses the draft.** The built-in [Testing](/build/channels/configuring/testing) interface and [Simulations](/build/channels/configuring/testing#simulations) always run against the current draft, so you can validate changes before going live.

## Publishing

When you're satisfied with your draft, click **Publish** in the editor header. Publishing makes the draft the new live version, and all new conversations immediately use the updated channel.

Each channel has exactly one published version at a time. The previously published version is retained in Version History.

Only Editors and Managers can publish. Contributors can save and test drafts, but their Publish button is disabled, so ask an Editor or Manager to publish for you. See [User Management](/platform/settings/user-management) for the full list of roles.

{% hint style="info" %}
**Chat channels** require at least one activation trigger on any non-default channel before publishing. If a non-default channel has no triggers, the publish button will show an error.
{% endhint %}

## Version History

Click **Version History** in the editor header to see a list of all previously published versions, newest first. Each entry shows who published it and when.

Select any version to preview its instructions. Click **Restore** to create a new draft from that version. Restoring does not publish; it gives you a draft to review and test before going live again.

## Unpublishing

To pause a live channel without deleting it, click **Unpublish**. Unpublished channels are not shown to leads. If the one you're unpublishing is the default for its channel, Spara will prompt you to confirm, since incoming traffic will have no channel to handle it until you publish a replacement.

## FAQ

### Do saved drafts affect live leads?

No. Saving a draft never affects live conversations. Only publishing changes what leads see.

### What happens if I publish and then notice a bug?

Open Version History, select the previous version, and click **Restore**. This creates a draft from the old version. Publish it to roll back immediately.

### Can multiple people edit the same draft?

Yes, but changes are not merged; the last save wins. Coordinate with your team to avoid overwriting each other's edits.


# A/B Testing

How Spara supports A/B and multivariate testing of channels to optimize conversion.

Spara lets you test multiple versions of a channel side by side to measure which performs better before rolling out changes to all your traffic. This helps you iterate on your sales conversations with confidence, without risking your funnel performance.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-c7b19ca64e695ed9f110e4808a7f83ada7aee7eb%2FA-B%20Testing.png?alt=media" alt=""><figcaption><p>The A/B Tests tab: add variants to a trigger group and split traffic between them.</p></figcaption></figure>

## What can be tested

Anything unique to a channel can be tested, including:

* **AI instructions** (prompt): Test different conversational styles, objection handling, or qualification approaches
* **Preview messages**: Test different pop-up messages to see which drives more engagement
* **Suggested responses**: Test different suggested reply buttons
* **Media and calendars**: Test whether showing a video or calendar at different points improves conversion

Since each variant has its own configuration, you can test any combination of these variables.

## How variants are grouped

A/B tests are organized by **trigger**, the condition that activates a channel. Variants that share a trigger split that trigger's traffic between them:

* [Chat](/build/channels/chat) variants share a URL trigger (the `when` condition that decides when the channel activates).
* [Phone](/build/channels/phone) and [SMS](/build/channels/sms) variants share a phone number.

This means creating a variant is as simple as duplicating a channel: the variant inherits the original's trigger automatically and joins the same test group.

## How to set up an A/B test

A/B tests are managed through the **Experiments** panel on a channel's **Overview** tab. No setup from the Spara team is required.

### Create a variant

1. Open the channel you want to test from the [**Agents**](https://app.spara.co/agents) page.
2. In the **Experiments** panel, click **Create variant**. The variant inherits the control's trigger automatically.
3. Configure the variant's prompt, preview message, suggested responses, media, or calendar, whatever you're testing.
4. Use the **breadcrumb switcher** at the top of any channel in the experiment to jump between the control and all variants. Each shows a **Published** or **Draft** badge so you can see what's live at a glance.

### Set the traffic split

In the **Experiments** panel, adjust the traffic percentage for each variant. The control receives whatever traffic isn't allocated to variants. Traffic is split deterministically, so the same visitor always sees the same variant.

For Phone and SMS variants, the split covers every conversation on the shared number: incoming calls and texts, and outgoing calls and texts sent by a workflow. A variant at 0% never places a call or sends a text.

### Manage variants

* **Archive** a variant to stop it receiving traffic without deleting it. Archived variants can be restored later.
* **Promote** a variant to control if it outperforms the original. The promoted variant takes over the control role and the former control becomes a variant.
* Each channel's **Overview** tab shows its current role (control, variant, or archived), its inherited trigger, and its share of traffic.

### How traffic splitting works

Spara deterministically assigns each visitor to a variant using a hash of the visitor's unique identifier. This means:

* The same visitor always sees the same variant (no mid-conversation switching)
* The split is random and evenly distributed
* You control the percentages using the traffic controls in the Experiments panel

### Assigning leads to groups

To track which group each lead was in, configure each variant to assign a field value when it activates. For example:

* Control assigns `experiment_group = "control"`
* Variant assigns `experiment_group = "experiment"`

This field persists on the lead record, so you can filter analytics and exports by group even after the experiment ends.

## Measuring results

Use the [Analytics](/pipeline/analytics) page to compare performance between variants. Use the **Agent** filter to view metrics for each variant individually, then compare:

* **Leads engaged**: Which variant drives more conversations?
* **Calls scheduled**: Which variant converts more leads to meetings?
* **Emails collected**: Which variant captures more contact information?
* **Conversation length**: Are leads more or less engaged with each variant?

### How long to run a test

Run your test until you have enough data to be confident in the results. As a general guideline, aim for at least 100 engaged leads per variant before drawing conclusions. High-traffic sites may reach significance in days; lower-traffic sites may need several weeks.

## Using third-party analytics tools

{% hint style="warning" %}
Spara does not natively integrate with third-party A/B testing tools. The approach below describes a custom integration using Spara's APIs.
{% endhint %}

You can use Spara's [Developer: Web API](https://docs.spara.com/developers/spara-api/web-api) or [Developer: Javascript API](https://docs.spara.com/developers/spara-api/javascript-api) to connect an external experimentation platform (e.g., Amplitude, LaunchDarkly) with Spara's routing:

1. Set up your experiment in the third-party tool, assigning visitors to groups
2. Use the Spara Javascript API to set a field on each visitor (e.g., `experiment_group = "control"`)
3. Configure your channels to activate based on that field value

{% hint style="info" %}
Do not switch a visitor's channel mid-conversation. Only assign the experiment group before the first interaction.
{% endhint %}

## Loading Spara for only some visitors

To show Spara to only a percentage of website visitors, you can conditionally load the embed snippet:

```javascript
<script>
var SPARA_TRAFFIC_PERCENTAGE = 10; // 10 = 10%, 100 = always show

(function() {
  var k = 'spara_traffic', d = 30;
  var s = localStorage.getItem(k);
  var run = SPARA_TRAFFIC_PERCENTAGE >= 100 || (s ? JSON.parse(s).i && Date.now() < JSON.parse(s).e : Math.random() * 100 < SPARA_TRAFFIC_PERCENTAGE);

  if (!s || Date.now() > JSON.parse(s).e) {
    localStorage.setItem(k, JSON.stringify({i: run, e: Date.now() + d * 864e5}));
  }

  if (run) {
    var script = document.createElement('script');
    script.src = 'https://app.spara.co/embed-<app_id>.js';
    document.head.appendChild(script);
  }
})();
</script>
```

Set `SPARA_TRAFFIC_PERCENTAGE` to control the percentage. The assignment persists for 30 days so returning visitors stay in the same group.

{% hint style="info" %}
It is usually simpler to load Spara for 100% of visitors and use the variant-based A/B testing approach instead. Configure a "control" that shows only the avatar (no preview message) and a variant that shows a pop-up. This achieves the same result without needing to modify your embed code.
{% endhint %}


# Workflows

How to deploy agents to run a proactive GTM playbook.

Workflows define a proactive GTM playbook for your agents to execute. Instead of waiting for leads to reach out, workflows let Spara take action: sending emails, making calls, and routing leads through multi-step sequences based on their data and behavior. Workflows live inside an Agent, alongside its capabilities.

For example, a [Phone](/build/channels/phone) capability deployed to a phone number picks up incoming calls. Add a **Call Phone** step to a workflow and that same capability dials leads proactively, turning an incoming tool into an outgoing engine.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-3faa4ae77cd27bce2ea1cae85e22a8e4af5ea36a%2FWorkflow%20Editor.png?alt=media" alt=""><figcaption><p>A workflow with triggers, conditions, branching logic, calls, emails, and waits.</p></figcaption></figure>

## How workflows are built

A workflow is a **Trigger** (the criteria that decides which leads enter) followed by a sequence of **Steps** that run in order, all assembled on a canvas in the Workflow editor:

* [Configuring Workflows](/build/workflows/configuring): the editor, triggers, settings, and how a published workflow runs.
* [Workflow Steps](/build/workflows/steps): the individual actions a workflow can run, from sending an email to branching on a condition.

### Outgoing time windows

Outgoing time windows let you control when each channel is allowed to send. You can configure separate windows for email, SMS, and outgoing calls in **Settings**. When a Send Email, Send Text, or Call Phone step fires outside its configured window, the lead is **held** at that step — not dropped — and the step retries automatically once the window reopens.

This means a lead can progress through earlier steps (like a Wait or Condition) and only pause when it reaches a channel step that falls outside its window.

Calls and texts always run inside a window; email windows are optional.

#### Whose timezone the window uses

Each window is read in one of two clocks:

* **The lead's local time** (the default for calls and texts): 9:00 AM–8:00 PM means 9:00 AM–8:00 PM *where the lead is*. For calls and texts, Spara places the lead from their phone number's country and area code, even when the lead has a timezone of their own; for email, from the lead's own timezone. If neither is known, the window falls back to the **Fallback timezone** shown beneath the options — so set that to wherever most of your unplaceable leads are. When a phone number's prefix covers several timezones — an Australian mobile, for instance — the step only sends when the time is acceptable in **all** of them.
* **A specific timezone**: every lead is evaluated against the one timezone you choose, wherever they are.

#### Per-step overrides

A Send Email, Send Text, or Call Phone step can define its own window instead of following your organization's. Open the step and choose **Send during custom times for this step** under Outgoing times — useful when one workflow targets a single region while the rest of your account keeps the account-wide window.

Send Email and Send Text steps offer a third choice, **Send immediately**, which ignores the window for that step alone — for time-sensitive messages that should go out the moment the lead reaches the step. On email it also skips [Send Email Step](/build/workflows/steps/send-email).

## FAQ

### Why did my workflow step not fire at the expected time?

If you have outgoing time windows configured (Settings > Email or Settings > Phone Numbers > Outgoing Times), a Send Email, Send Text, or Call Phone step will not fire outside the allowed window. Remember the window may be read in the lead's local time rather than yours, and that a step can carry its own window that overrides the account-wide one. Leads are held at that step and retried automatically when the window reopens — so the step will still fire, just later than immediately scheduled. A held lead's step activity shows which timezone Spara placed that lead in and why, for example *in America/Chicago (CDT), from this lead's phone area code*. A Send Email or Send Text step that must not wait can be set to **Send immediately** instead.

Check the lead's timeline in the Leads table to see where it is in the workflow and whether it's waiting on a time window.


# Workflow Steps

The individual actions a workflow can run, from sending an email to branching on a condition.

**Steps** are the individual actions in a [Workflows](/build/workflows). Each step executes in sequence: when one finishes, the next begins. Use **Wait** steps to control timing, and **Condition** steps to branch the logic.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-3faa4ae77cd27bce2ea1cae85e22a8e4af5ea36a%2FWorkflow%20Editor.png?alt=media" alt=""><figcaption><p>A workflow assembled from steps, with branching logic.</p></figcaption></figure>

| Step                                                 | What it does                                                                                                                 |
| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| [Send Email Step](/build/workflows/steps/send-email) | Sends a personalized email to the lead or their assigned rep.                                                                |
| [Send Text Step](/build/workflows/steps/send-text)   | Sends an SMS to the lead's phone number.                                                                                     |
| [Call Phone Step](/build/workflows/steps/call-phone) | Uses the Phone capability to call the lead's phone number.                                                                   |
| [Notify Step](/build/workflows/steps/notify)         | Sends a Slack or Microsoft Teams notification to your team.                                                                  |
| [Wait Step](/build/workflows/steps/wait)             | Pauses execution for a set duration (up to 30 days).                                                                         |
| [Condition Step](/build/workflows/steps/condition)   | Branches workflow logic based on lead data.                                                                                  |
| [API Step](/build/workflows/steps/api)               | Makes an HTTP request to an external system and can extract data.                                                            |
| [CRM API Step](/build/workflows/steps/crm-api)       | Calls your connected CRM (Salesforce, HubSpot, or Marketo) using Spara's stored connection and can extract data. Admin only. |
| [Set Field Step](/build/workflows/steps/set-field)   | Writes a value you specify to a field on the lead.                                                                           |
| [Research Step](/build/workflows/steps/research)     | Researches a lead or company with an AI prompt (with web search) and extracts structured data.                               |

{% hint style="warning" %}
If a step cannot execute (e.g., a **Call Phone** step for a lead with no phone number), the workflow skips it and continues to the next step.
{% endhint %}


# Send Email Step

Send a personalized email from your AI agent.

The **Send Email** step sends an email on behalf of your AI agent to a lead or their assigned sales rep.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-62e40dc4675e095a43614c428b74ab0ecfe12c26%2FWorkflow%20Send%20Email%20Step.png?alt=media" alt=""><figcaption><p>The Send Email step configuration panel.</p></figcaption></figure>

## Configuration

### Email channel and sending mailbox

Each workflow sends as one Email channel, picked under **Settings > Email Channel** in the workflow editor. The workflow sends from that channel's mailbox, shown next to its name. The Email channel's instructions shape the email, and the same channel answers the lead's replies once it's published.

* **Several channels on one mailbox**: supported. Each workflow sends as the channel it picks, and the mailbox's daily send limit and pacing are shared across them.
* **Changing a channel's mailbox**: moves every workflow that sends as it to the new mailbox.

### Recipients

| Field                    | Description                                                                             |
| ------------------------ | --------------------------------------------------------------------------------------- |
| **Send to lead**         | Sends to the lead's email address.                                                      |
| **Send to assigned rep** | Sends to the rep assigned to the lead in Salesforce. Requires a Salesforce integration. |
| **CC**                   | Additional email addresses to CC. Accepts static addresses, variables, or both.         |
| **BCC**                  | Additional email addresses to BCC. Accepts static addresses, variables, or both.        |

At least one of **Send to lead** or **Send to assigned rep** must be enabled.

### Variables in CC and BCC

CC and BCC take a comma-separated list, and each entry can be either a static address or a variable holding one — so a step can copy in an address that differs per lead, like the account owner or an account manager stored on the lead record. Insert a variable the same way you would in the subject: click the insert button (`</>`) at the end of the field, or type `{{`.

A variable can also hold several comma-separated addresses; each becomes its own recipient.

If a variable is empty for a given lead, or holds something that isn't an email address, that recipient is skipped and the email still goes to its main recipients. Nothing is sent to a malformed address.

### Send immediately

By default, Spara paces workflow emails: each connected mailbox sends at most one email every few minutes, so a large batch goes out gradually instead of all at once. This protects your mailbox's sending reputation. Under **Outgoing times** in the step panel, choose **Send immediately** to skip pacing — and any configured outgoing window — for that step only. Use it for time-sensitive emails, like a follow-up right after a call or a booking confirmation. It is one of three choices there, so a step either follows a send window or ignores it, never both.

### Subject and Body

Both the subject line and body support variables. In the subject, click the insert button (`</>`) at the end of the field or type `{{`; in the body, use the **Insert menu** (⚡) to browse and insert available lead data fields.

The body editor supports standard markdown formatting: bold, italics, lists, links, and code blocks.

Use the **Preview** button to see how the email will render with sample lead data before publishing.

## Tips

{% hint style="info" %}
**Personalization drives results.** At minimum, include `{{ first_name }}` in the subject or opening line. Referencing account-specific data (e.g., `{{ company_name }}`, `{{ last_page_visited }}`) significantly improves reply rates.
{% endhint %}

{% hint style="warning" %}
**Missing email address.** If a lead has no email address on record, this step is skipped and the workflow continues to the next step.
{% endhint %}

{% hint style="info" %}
**Missing variable values.** Name variables such as `{{ first_name }}` fall back to the best available identity for the lead rather than rendering blank. All other variables render empty when a value hasn't been captured. Use a [Condition Step](/build/workflows/steps/condition) before this step if you want to branch on whether a field is populated.
{% endhint %}

{% hint style="info" %}
**Outgoing time windows.** If your organization has an email outgoing window configured (Settings > Email), this step only fires during that window — either in the lead's own timezone or in a specific one you choose. Leads that reach this step outside the window are held — not dropped — and the step retries automatically once the window reopens. To use a different window for this step alone, choose **Send during custom times for this step** under Outgoing times in the step panel. Steps with **Send immediately** enabled ignore the window entirely.
{% endhint %}

{% hint style="info" %}
**Send pacing.** Emails that reach this step around the same time are queued and sent a few minutes apart per mailbox. In the workflow's activity view, a queued email shows as "Queued — sending at a safe pace" until it goes out. The mailbox's **Max daily sends** (Settings > Email > Manage) sets the pace: up to 500 a day sends every few minutes, and the higher limits send faster so the day's allowance is reachable. Only raise it above 500 on a warmed-up domain with an established sending history.
{% endhint %}

{% hint style="warning" %}
**Template syntax errors are caught at publish time.** If a subject line or body contains a Jinja syntax error (for example, a mistyped tag like `{ % if ... %}`), publishing the workflow will show a validation error. Fix the template before publishing to avoid delivery failures.
{% endhint %}


# Send Text Step

Send a personalized SMS to a lead's phone number.

The **Send Text** step sends an SMS message to a lead's phone number.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-4f636b8efd50f110ec4422a2f545c4007c29063c%2FWorkflow%20Send%20Text%20Step.png?alt=media" alt=""><figcaption><p>The Send Text step configuration panel.</p></figcaption></figure>

## Configuration

### Message Body

Write the SMS content in the message body field. Use the **Insert menu** (⚡) to add:

* **Variables** — lead data fields like `{{ first_name }}`, which resolve when the text is sent.
* **AI instructions** — a short instruction the agent replaces with wording of its own, for the part of the message you want personalized.
* **Booking links** — a calendar link the agent invites the lead to book with.

A body with an AI instruction or a booking link is written by the agent when the step runs, so the exact wording varies per lead. **Preview** shows you one example of that wording for a sample lead; the real message is written per lead at send time. A body with neither is sent exactly as you wrote it, and previews exactly as you wrote it.

Keep messages concise. SMS best practices recommend staying under 160 characters to avoid message splitting — tell the agent so in your AI instruction (for example, "one short sentence") if you use one.

### Send immediately

Under **Outgoing times** in the step panel, choose **Send immediately** to skip your outgoing text window for this step only. Use it for time-sensitive texts, like a follow-up right after a lead is scanned at an event or checks in at your front desk. It is one of three choices there, so a step either follows a send window or ignores it, never both.

### From Number

The outgoing phone number is configured on the text agent's **Configuration** tab. It is shown read-only in this step. To change it, open the text agent settings; a link is shown at the bottom of this step's configuration panel.

## Tips

{% hint style="info" %}
**Opt-out compliance.** Ensure your SMS program complies with applicable regulations (TCPA, GDPR, etc.). Leads should have opted in to receive SMS messages from your account.
{% endhint %}

{% hint style="warning" %}
**Missing phone number.** If a lead has no phone number on record, this step is skipped and the workflow continues to the next step.
{% endhint %}

{% hint style="info" %}
**Outgoing time windows.** Texts only fire inside your outgoing text window (Settings > Phone Numbers > Outgoing Times), which by default is read in the lead's own local time. Leads that reach this step outside the window are held — not dropped — and the step retries automatically once the window reopens. To use a different window for this step alone, choose **Send during custom times for this step** under Outgoing times in the step panel. Steps set to **Send immediately** ignore the window entirely.
{% endhint %}


# Call Phone Step

Have a Voice agent call a lead's phone number.

The **Call Phone** step initiates an outgoing call to a lead's phone number using one of your Voice agents.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-88e9e6077517a19561bd1ab9fd083e28ce2339cb%2FWorkflow%20Call%20Phone%20Step.png?alt=media" alt=""><figcaption><p>The Call Phone step configuration panel.</p></figcaption></figure>

## Configuration

Choose the outgoing number on the workflow's **Settings** tab, under **Voice Agent**. Each option is one of your phone numbers with the Voice agent published on it. The lead sees this number on their caller ID, and the Voice agent published on it places the call.

The agent's persona, instructions, and tools are managed on the Voice agent itself, not here. A summary of the agent is shown in the step panel for reference.

If more than one Voice agent is published on the number, they are an A/B test, and the number's traffic split decides which agent calls each lead. The split applies to incoming calls and outgoing workflow calls alike, so an agent set to 0% never places a call. See [A/B Testing](/build/channels/configuring/a-b-testing) to adjust the split.

## Tips

{% hint style="info" %}
**Best practice: pair with a Wait step.** Place a **Wait** step before **Call Phone** to give the lead time to complete an action before calling. For example: wait 30 minutes after a form submission before calling.
{% endhint %}

{% hint style="warning" %}
**Missing phone number.** If a lead has no phone number on record, this step is skipped and the workflow continues to the next step.
{% endhint %}

{% hint style="warning" %}
**Do Not Call.** If the lead has opted out of calls, this step is skipped and the workflow continues to the next step. See [Phone](/build/channels/phone#do-not-call).
{% endhint %}

{% hint style="warning" %}
**Outgoing calls only.** Workflows initiate outgoing calls. Incoming call handling is configured directly on the Voice agent, not in workflows.
{% endhint %}

{% hint style="info" %}
**Outgoing time windows.** Calls only fire inside your outgoing call window (Settings > Phone Numbers > Outgoing Times), which by default is read in the lead's own local time. Leads that reach this step outside the window are held — not dropped — and the step retries automatically once the window reopens. To use a different window for this step alone, choose **Send during custom times for this step** under Outgoing times in the step panel.
{% endhint %}


# Notify Step

Send an internal notification via email, Slack, Teams, or Webex.

The **Notify** step sends an internal notification via email, Slack, Microsoft Teams, or Webex — to a channel or room, to specific email addresses, or directly to the lead's assigned sales rep. Use it to alert your sales team when a lead takes a specific action — for example, when an assigned lead schedules a meeting, a high-value lead completes a form, or a lead replies to a workflow email.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-c0a25c45a3f05ebadbb4878ba6be0ba018db25f6%2FWorkflow%20Notify%20Step.png?alt=media" alt=""><figcaption><p>The Notify step configuration panel with Slack channel and message.</p></figcaption></figure>

## Configuration

### Platform

Choose **Slack**, **Microsoft Teams**, **Webex**, or **Email**. Slack, Teams, and Webex require the corresponding integration enabled under [**Settings > Integrations**](https://app.spara.co/settings/integrations); email notifications need no integration and are sent from Spara.

### Channel / Room (Slack, Teams, and Webex)

Select the channel, team, or Webex room to post the notification to. The available options are loaded from your connected workspace. Optional when **Direct Message** is enabled.

### To and Subject (Email)

Enter one or more recipient email addresses, separated by commas. The subject line is optional and supports variables (see [Guide: How to Use Spara's Text Editor](https://docs.spara.com/guides/platform-guides/how-to-use-sparas-text-editor)), just like the message.

### Direct Message / Assigned sales rep

Check **Assigned sales rep** to notify the lead's assigned sales rep directly — a direct message on Slack, Teams, or Webex, or an additional recipient on email. The assigned rep comes from your connected CRM (Salesforce or HubSpot); for direct messages, the rep must have an account in your workspace that uses the same email address as their CRM user. You can combine this with a channel or other recipients — the notification is sent to all of them.

Webex direct messages are sent from the Webex account that connected the integration, so the rep sees them in their one-on-one space with that account. Webex can't deliver a message from an account to itself: when a lead's assigned rep is the account that connected Webex, that direct message is skipped and the rep is listed under **Not reached**. Connect Webex from a shared or admin account if every rep needs these messages.

At least one destination — a channel or room, an email recipient, or the assigned sales rep — must be selected.

### When a notification can't be delivered

A step that reaches only some of its destinations still completes, and the Activity tab names the ones it skipped under **Not reached**.

A step that reaches nobody is marked **Not delivered** with the reason. What happens to the lead depends on the reason:

* **A problem with this lead**, such as no assigned sales rep in your CRM, or a rep who is not in your Slack, Teams, or Webex workspace: the lead continues to the later steps. Only this lead's notification is affected, so the workflow keeps running for everyone else.
* **A problem with your setup**, such as an unfinished step, no connected CRM, or no connected Slack, Teams, or Webex workspace: the lead stops there. The step cannot reach anyone for any lead until you fix it, and the leads resume once you do.

To make sure a notification always reaches someone, add a channel or another recipient alongside **Assigned sales rep**.

### Message

Write the notification message. Supports variables: use the **Insert menu** (⚡) to insert lead data.

Use the **Preview** button to see how the message renders with sample data.

## Global notification settings

The Notify step is best for targeted, conditional alerts: notifications that should only fire when leads match specific workflow criteria. For account-wide alerts that fire every time a lead event occurs (such as deanonymization, enrichment, or emails sent), use the global [Notifications](/platform/settings/notifications) settings instead.


# Wait Step

Pause workflow execution for a set amount of time.

The **Wait** step pauses a lead's progression through the workflow for a fixed duration before continuing to the next step.

The wait starts once the previous step finishes. For example, if an email is held by the mailbox's daily send limit, the wait starts when that email actually sends.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-2ca3d91ef33e086f3a8309e54c0cb496b2a6c98f%2FWorkflow%20Wait%20Step.png?alt=media" alt=""><figcaption><p>The Wait step configuration panel.</p></figcaption></figure>

## Configuration

Set the **duration** and **unit**:

* **Minutes**: e.g., 30 minutes
* **Hours**: e.g., 4 hours
* **Days**: e.g., 2 days

The minimum duration is 1 unit (1 minute, 1 hour, or 1 day). The maximum is **30 days**.

{% hint style="info" %}
For scheduling a send at a specific clock time rather than a relative delay, configure an outgoing window on the sending step instead — see [Send Email Step](/build/workflows/steps/send-email).
{% endhint %}

## Common Patterns

{% columns %}
{% column %}
**Give leads time to act**

Place a Wait before a follow-up step. For example: send an email, wait 2 days, then call phone if no reply.
{% endcolumn %}

{% column %}
**Space out outreach**

Avoid contacting leads too frequently by adding Wait steps between Send Email, Send Text, and Call Phone steps.
{% endcolumn %}
{% endcolumns %}

## Behavior During Unpublish/Republish

If a workflow is unpublished while a lead is mid-wait, that lead's timer is paused. When the workflow is republished, the timer resumes from where it left off.


# Time of Day Step

Retired step that held workflow execution until a specific time of day was reached.

{% hint style="warning" %}
**The Time of Day step has been retired.** It can no longer be added to a workflow, and one left in an existing workflow no longer holds anyone — leads that reach it continue straight to the next step. The editor shows the step as an error, and the workflow can't be saved or published until the step is deleted. Use an [Send Email Step](/build/workflows/steps/send-email) instead — it holds a send until the window reopens, in the lead's own timezone or one you choose.
{% endhint %}

The **Time of Day** step held a lead at a point in the workflow until a configured clock time was reached. [Send Email Step](/build/workflows/steps/send-email) replace it: they apply the same restriction to the step that actually sends, in the lead's own timezone or one you choose, and hold the send until the window reopens instead of releasing the lead at a fixed hour.

If a workflow of yours still has one, open the step and delete it, then save and publish.


# Condition Step

Branch your workflow based on lead data.

The **Condition** step splits workflow execution into multiple branches based on criteria you define. Each lead follows the first branch whose criteria they match.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-3459ee58516459db0801321cd5550297b5bd6900%2FWorkflow%20Condition%20Step.png?alt=media" alt=""><figcaption><p>The Condition step configuration panel with criteria and branch routing.</p></figcaption></figure>

## How It Works

A Condition step has one or more **branches**. Each branch has its own set of criteria. When a lead reaches a Condition step:

1. Spara evaluates each branch's criteria in order, top to bottom.
2. The lead follows the **first branch** whose criteria they satisfy.
3. If no branch matches, the lead exits the workflow at this point.

## Configuration

### Adding Branches

Click **Add branch** to create a new branch. Each branch can be named and has its own independent criteria and downstream steps.

### Criteria

Each branch supports one or more criteria rows. Multiple criteria within a branch are evaluated with **AND** logic: the lead must satisfy all of them to match that branch.

| Data Type      | Available Operators                                                                                          |
| -------------- | ------------------------------------------------------------------------------------------------------------ |
| **Text**       | equals, is not, is defined, is not defined                                                                   |
| **Picklist**   | equals, is not, is any of, is defined, is not defined                                                        |
| **Number**     | equals, greater than, less than, is defined, is not defined                                                  |
| **True/False** | is true, is false                                                                                            |
| **List**       | contains, does not contain, is defined, is not defined, length equals, length greater than, length less than |
| **Date/Time**  | relative and absolute comparisons                                                                            |

{% hint style="info" %}
**"is not" includes leads with no value.** `Industry is not Finance` matches leads whose industry is anything other than Finance, *and* leads with no industry recorded at all. To require a value, add `Industry is defined` to the same branch.
{% endhint %}

{% hint style="info" %}
**Matching several values of one field.** Pick **is any of** on a picklist field to select as many of its options as you need in a single criteria row — the lead matches if their value is any one of them. Use it instead of duplicating a branch per value: `Parent Industry is any of Services, Other` is one row, where `equals` would need two branches.
{% endhint %}

{% hint style="info" %}
**Fields from earlier workflow steps.** Fields defined in earlier Prompt or API steps in this workflow are available as criteria here. This lets you branch based on data your workflow just extracted — for example, routing leads by a `tier` field that a Research step populated.
{% endhint %}

### Engagement with this workflow's outreach

Some criteria are scoped to this workflow's own activity rather than the lead's overall record: **Lead replied to email**, **Lead replied to text**, **Lead answered call**, **Latest email open count** — the number of times the lead opened the most recent email a Send Email step in this workflow sent them — and **Latest email click count** — the number of times they clicked a link in that same email. Because they always reflect the latest step's email, a Condition placed after a Send Email step branches on that step's own email, and a workflow with several Send Email steps re-scopes at each one. Use them after a Send Email step (typically following a Wait), e.g. `Latest email open count greater than 2` to follow up only with leads who keep coming back to the email, or `Latest email click count greater than 0` to route leads who visited a link. Both stay unset until a Send Email step has emailed the lead, and they require **Email Tracking** (on by default) under **Settings → Email Configuration**.

Three companion criteria total the workflow's email activity instead of tracking just the latest email: **Count of emails sent** — how many emails this workflow's Send Email steps have sent the lead — **Count of email opens** — the lead's opens across all of those emails — and **Count of email clicks** — their link clicks across all of those emails. Use them to branch on overall engagement across a sequence, e.g. `Count of emails sent greater than 2` to cap follow-ups, or `Count of email opens equals 0` to switch channels after several unopened emails. Like the latest-email criteria, all three stay unset until a Send Email step has emailed the lead; from then on the open and click totals start at 0. Note that with **Email Tracking** turned off, opens and clicks are never recorded, so those two totals stay at 0 regardless of what the lead does — avoid branching on them in that case.

### Connecting Steps

Each branch connects to its own downstream step (or sequence of steps). Click the **+** on any branch output to add the next step for that path. You can nest multiple steps under a single branch — for example, a branch that sends an email and then waits two days before sending a follow-up text. Branches without any steps skip directly to whatever follows the Condition step.

When building workflows with **Ask Spara**, you can describe the full sequence you want inside each branch and Ask Spara will build the nested steps automatically. Invented field names in branch criteria are flagged before publish so you can correct them.

## Example: Tiered Follow-up

```
Condition
├── Branch 1: employee_count > 500
│   └── Call Phone (high-touch outreach)
├── Branch 2: employee_count > 50
│   └── Send Email (mid-touch outreach)
└── Branch 3: (no criteria, catch-all)
    └── Send Text (low-touch outreach)
```

{% hint style="info" %}
**Tip: use a catch-all branch.** Add a final branch with no criteria to handle leads that don't match any earlier branch. Without a catch-all, unmatched leads exit the workflow silently.
{% endhint %}

## Warnings

If a branch requires a field (e.g., `email`) but the workflow's Audience criteria don't guarantee that field is present, Spara will show a warning on the step. This doesn't prevent publishing, but it means some leads may skip that branch at runtime due to a missing value.


# API Step

Make an HTTP request to an external system and extract data from the response.

The **API** step makes an HTTP request to any external endpoint and optionally extracts data from the response into lead fields for use in downstream steps.

An API step runs once per lead, per workflow. If you need a continuous stream of every event on a lead instead, see [Guide: Webhook, Web API, or Workflow API Step?](https://docs.spara.com/guides/integration-guides/webhook-web-api-or-workflow-api-step).

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-333cc7a97f74d99ba447410bb2b10f93bdd4bcea%2FWorkflow%20API%20Step.png?alt=media" alt=""><figcaption><p>The API step configuration panel with method, URL, JSON body, and field extraction.</p></figcaption></figure>

## Configuration

### Method and URL

Select the HTTP method (**GET**, **POST**, or **PUT**) and enter the full endpoint URL.

The URL supports variables, so you can build the path or query string from lead data. Insert them from the **Insert menu** (⚡) or by typing `{{`. For example:

```
https://api.example.com/enrich?email={{ email }}
https://api.example.com/users/{{ email }}
```

Variable values are URL-encoded automatically, so characters like `@`, `+`, and spaces are sent safely and a value can't change the rest of the URL. A field with no value for the lead is left blank.

{% hint style="info" %}
Variables can only appear after the domain. The scheme and domain (e.g., `https://api.example.com/`) must be typed out in full, so a request always goes to the server you configured.
{% endhint %}

### Authentication

Use the **Authentication** section to send an API key or token with the request without exposing it to other users. Choose how the credential is sent:

* **Bearer token** — sent as `Authorization: Bearer <secret>`
* **Custom header** — sent under a header name you choose (e.g., `X-API-Key`)

Then select a **secret** from your organization's secrets library, or choose **+ Create new secret** to add one without leaving the workflow builder.

Secrets are encrypted, and their values can never be viewed after saving — in the workflow builder they appear masked (e.g., `••••ab12`). You can manage secrets (rename, replace a value, or delete) under **Settings → API & Webhooks → Secrets**.

{% hint style="success" %}
**Security:** Always use the Authentication section for API keys and tokens. Values placed in plain headers are visible to anyone who can edit the workflow.
{% endhint %}

### Headers

Add additional request headers as key/value pairs — for example, `Content-Type: application/json`.

Click **Add header** to add rows and the trash icon to remove them.

### Body

For **POST** and **PUT** requests, enter the request body as JSON. The editor provides:

* **Syntax highlighting**: JSON keys, strings, and values are color-coded
* **Inline validation**: errors are underlined with a description
* **Format button**: auto-formats and pretty-prints your JSON

The body also supports variables via the **Insert menu** (⚡). For example:

```json
{
  "email": "{{ email }}",
  "company": "{{ company_name }}",
  "source": "spara-workflow"
}
```

### Field Extraction

After the API call completes, Spara can extract values from the response and save them as lead fields. These extracted fields are then available as workflow-scoped variables in downstream steps.

Add one or more **Fields**:

| Field           | Description                                                                  |
| --------------- | ---------------------------------------------------------------------------- |
| **Name**        | The field name (e.g., `intent_score`). Use snake\_case.                      |
| **Description** | Tell the AI what this field represents and where to find it in the response. |

Spara uses the description to intelligently extract the correct value from the API response, even if the response structure is nested or complex.

## Example: Enrich a Lead

```
POST https://api.clearbit.com/v1/people/find
Authentication: Bearer token → secret "Clearbit API key"
Body:
{
  "email": "{{ email }}"
}

Field Extraction:
- Name: job_seniority
  Description: The lead's seniority level from the "seniority" field in the response
- Name: linkedin_url
  Description: The lead's LinkedIn profile URL from "linkedin.handle"
```

Downstream steps can then use `{{ job_seniority }}` and `{{ linkedin_url }}` in their content.


# CRM API Step

Call your connected CRM's API with Spara's stored connection and extract data from the response.

The **CRM API** step makes an authenticated request to your connected CRM — **Salesforce**, **HubSpot**, or **Marketo** — and optionally extracts data from the response into lead fields for use in downstream steps.

It works like the [API Step](/build/workflows/steps/api) step, but you don't manage credentials or build the full URL. Spara uses the CRM connection you already set up under **Settings → Integrations**, refreshes the access token when it expires, and prepends the CRM's base URL to the endpoint you enter.

{% hint style="info" %}
Only organization admins can add a CRM API step to a workflow.
{% endhint %}

## Configuration

### CRM

Choose the CRM to call. Only CRMs your organization has connected are selectable; a CRM that needs to be reconnected is flagged, and the step won't run until it is reconnected in **Settings → Integrations**.

### Method and endpoint

Select the HTTP method (**GET**, **POST**, **PUT**, or **PATCH**) and enter the endpoint **path**. Spara prepends the CRM's base URL:

| CRM        | Base URL                                                              |
| ---------- | --------------------------------------------------------------------- |
| Salesforce | Your Salesforce instance URL (e.g., `https://acme.my.salesforce.com`) |
| HubSpot    | `https://api.hubapi.com`                                              |
| Marketo    | Your Marketo REST host (e.g., `https://123-ABC-456.mktorest.com`)     |

The endpoint supports variables, so you can address a specific record using lead data. Insert them from the **Insert menu** (⚡) or by typing `{{`. For example:

```
/crm/v3/objects/contacts/{{ hubspot_contact_id }}
```

Variable values are URL-encoded automatically, so characters like `@`, `+`, and spaces are sent safely and a value can't change the rest of the endpoint. A field with no value for the lead is left blank.

The endpoint must be a path relative to the CRM's base URL — a full URL or a path that navigates above the base is rejected.

### Headers

Add request headers as key/value pairs. Spara sets the `Authorization` header from your CRM connection, so you never enter a token here.

### Body

For **POST**, **PUT**, and **PATCH** requests, enter the request body as JSON. The editor provides syntax highlighting, inline validation, a **Format** button, and the **Insert menu** (⚡) for variables — the same as the API step.

```json
{
  "properties": {
    "lifecyclestage": "salesqualifiedlead",
    "spara_intent_score": "{{ intent_score }}"
  }
}
```

### Field Extraction

After the request completes, Spara can extract values from the response and save them as lead fields, available as variables in downstream steps.

| Field           | Description                                                                  |
| --------------- | ---------------------------------------------------------------------------- |
| **Name**        | The field name (e.g., `owner_email`). Use snake\_case.                       |
| **Description** | Tell the AI what this field represents and where to find it in the response. |

## Example: Look up a HubSpot contact's owner

```
CRM: HubSpot
GET /crm/v3/objects/contacts/{{ hubspot_contact_id }}?properties=hubspot_owner_id,lifecyclestage

Field Extraction:
- Name: hubspot_owner_id
  Description: The contact's owner ID from "properties.hubspot_owner_id"
- Name: lifecycle_stage
  Description: The contact's lifecycle stage from "properties.lifecyclestage"
```

Downstream steps can then branch on `{{ lifecycle_stage }}` or include `{{ hubspot_owner_id }}` in a notification.


# Set Field Step

Write a value to a field on the lead partway through a workflow.

The **Set Field** step writes a value to a field on the lead when the workflow reaches it. Use it to stamp the outcome of an engagement onto the lead record — a status, a tag, a flag your CRM or your team reads later.

Unlike the [API Step](/build/workflows/steps/api), [CRM API Step](/build/workflows/steps/crm-api), and [Research Step](/build/workflows/steps/research) steps, which save fields as a side effect of calling out to something, Set Field does nothing but write. The value it writes is fixed by you, not discovered.

## Configuration

### Field

Pick the field to write. The list covers your [Data Model](https://app.spara.co/data-model) fields plus any fields produced by API or Research steps earlier in the same workflow. You can also type a name that isn't in the list — useful for a CRM field Spara doesn't track yet.

Read-only fields are not selectable, and a write to one is ignored.

### Value

The value to write. It supports variables, so you can compose it from lead data:

```
{{ first_name }} — engaged via {{ channel }}
```

## Behavior

* **The step always runs.** Set Field has no conditions of its own. To make a write conditional, put a [Condition Step](/build/workflows/steps/condition) step in front of it.
* **The trust hierarchy still applies.** A Set Field write is trusted at the same level as self-reported and CRM data, so it will not overwrite a value that came from a more trusted source — see [Data Model](/build/data-model).
* **It syncs like any other field.** If the field is mapped to your CRM, the new value is pushed there. Test leads are the exception: a test run writes the field in Spara but never pushes it to your connected systems.

## Example: Flag leads the agent finished with

```
Condition: engagement_outcome is defined
  → Set Field
      Field: spara_engagement_status
      Value: Complete
```

A downstream Condition step, a CRM sync, or a Leads filter can then act on `spara_engagement_status`.


# Research Step

Run an AI prompt to reason over lead data, research accounts on the web, and extract structured results.

The **Research** step runs a custom instruction against an LLM, with the lead's data as context. It can search the web to learn about a lead or their company, then classify leads, generate personalized content, or extract structured information for use in downstream steps.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-ff28d35c5c4c7a93e15c255e1df16ab91fb500bb%2FWorkflow%20Research%20Step.png?alt=media" alt=""><figcaption><p>The Research step configuration panel with instructions, field definitions, and tools.</p></figcaption></figure>

## Configuration

### Instructions

Write the prompt that the LLM will execute. Instructions support variables: use the **Insert menu** (⚡, Variables tab only) to reference lead data fields.

Be specific about what you want the model to produce. If you're extracting structured data, describe the expected output clearly.

**Example instruction:**

```
Based on the lead's job title ({{ job_title }}), company size ({{ employee_count }} employees),
and the pages they visited on our website ({{ pages_visited }}), classify their buying intent
as one of: HIGH, MEDIUM, or LOW.

Return only the classification word with no explanation.
```

### Tools

Optionally enable one or both tools to give the LLM access to live information:

| Tool           | What it does                                                                |
| -------------- | --------------------------------------------------------------------------- |
| **Web Search** | Allows the LLM to search the internet to research the lead or their company |
| **Fetch URL**  | Allows the LLM to retrieve the contents of a specific URL                   |

These tools are useful for account research steps, for example looking up a company's recent news or fetching their pricing page.

### Field Extraction

Save the LLM's output (or parts of it) into lead fields for use in downstream steps. These become available as workflow-scoped variables.

Add one or more **Fields**:

| Field           | Description                                                  |
| --------------- | ------------------------------------------------------------ |
| **Name**        | The field name (e.g., `buyer_intent`). Use snake\_case.      |
| **Description** | Describe what value should be extracted from the LLM output. |

## Example: Intent Classification + Personalized Email

{% stepper %}
{% step %}

#### Research step: classify intent

**Instructions:**

```
Review {{ first_name }}'s activity: they work at {{ company_name }} ({{ employee_count }} employees)
as a {{ job_title }} and visited {{ pages_visited }}. Rate their buying intent: HIGH, MEDIUM, or LOW.
```

**Field Extraction:**

* Name: `buyer_intent`
* Description: The intent classification (HIGH, MEDIUM, or LOW)
  {% endstep %}

{% step %}

#### Condition step: branch by intent

* Branch 1: `buyer_intent` equals `HIGH` → Call Phone
* Branch 2: `buyer_intent` equals `MEDIUM` → Send Email
* Branch 3: (catch-all) → Wait 7 days, then Send Email
  {% endstep %}

{% step %}

#### Send Email step: reference the extracted field

Subject: `Following up, {{ first_name }}`

Body: `Hi {{ first_name }}, based on your interest in our platform...`

The email content can vary per branch, using `{{ buyer_intent }}` if needed.
{% endstep %}
{% endstepper %}

## Tips

{% hint style="info" %}
**Be explicit in instructions.** LLMs produce more reliable structured output when you specify the exact format you expect. For classification tasks, provide the list of valid values.
{% endhint %}

{% hint style="info" %}
**Use Web Search for account research.** Enabling Web Search lets the model pull current information about a lead's company (recent funding, news, tech stack) to personalize downstream messaging.
{% endhint %}


# Configuring Workflows

How to use the Workflow editor, covering triggers, steps, settings, and the publish lifecycle.

Every [Workflows](/build/workflows) is built in the **Workflow editor**, a canvas where you define a **Trigger** (which leads enter the workflow) and a sequence of **Steps** (what happens to them once they do). This page covers the editor, its settings, and how a published workflow runs.

## Triggers

Every workflow starts with a **Trigger**, the criteria that defines which leads enter the workflow. Triggers can include multiple condition groups combined with AND/OR logic, giving you precise control over which leads are enrolled.

Any field in Spara's [Data Model](/build/data-model) is available as trigger criteria, including fields captured by your agents, synced from your CRM, or tracked from website activity.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-0bf166e09bd82ff8c84ef4d075963dd23844a2e4%2FWorkflow%20Triggers.png?alt=media" alt=""><figcaption><p>Trigger criteria with multiple conditions combined using AND logic.</p></figcaption></figure>

{% hint style="info" %}
A workflow continues to operate on a lead even if that lead no longer matches the trigger criteria after entering. Triggers only control entry.
{% endhint %}

{% hint style="info" %}
Spara evaluates leads who have been active within the **past 2 years** for new-lead workflows. A lead active in the last year but not the last month will still be eligible to enter.
{% endhint %}

### Phone call event triggers

In addition to field-based criteria, workflows can trigger on phone call events. Use the **On navigator call ended** event to fire a workflow after a web-based (Navigator) voice call ends — for example, to send a follow-up email or enroll the lead in a next-step sequence. This is separate from the SIP-based incoming and outgoing call triggers used with standard phone numbers.

### Product demo event triggers

The **On product demo ended** event fires after a lead completes an AI product demo, so you can follow up while the demo is still fresh.

## Adding steps

After the trigger, add [Workflow Steps](/build/workflows/steps) to the canvas. Each step executes in sequence: when one finishes, the next begins. Use **Wait** steps to control timing, and **Condition** steps to branch the logic. See [Workflow Steps](/build/workflows/steps) for the full list of step types and how each is configured.

{% hint style="warning" %}
If a step cannot execute (e.g., a **Call Phone** step for a lead with no phone number), the workflow skips it and continues to the next step.
{% endhint %}

## Workflow settings

Workflow settings control when a lead should automatically exit a workflow based on engagement. These are configurable per workflow:

* **End on email reply**: Lead exits when they reply to an email from a Send Email step
* **End on text reply**: Lead exits when they respond to a text from a Send Text step
* **End on call answer**: Lead exits when they pick up a call from a Call Phone step

All three are enabled by default. Disable them if you want leads to continue through the workflow even after engaging.

## Testing and publishing

Save the workflow as a draft to test it before going live. When you open the **Test** panel from the editor, Spara automatically generates a test lead pre-filled with values that satisfy your trigger criteria and any condition branches on the happy path, so you can start a test immediately without filling in fields manually. You can adjust individual field values before running the test. When you're ready, **Publish** to start enrolling leads.

Only Editors and Managers can publish a workflow. Contributors can save and test drafts, but their Publish button is disabled. See [User Management](/platform/settings/user-management) for the full list of roles.

### Send real messages during a test

By default, test runs simulate all outbound messages — emails, texts, calls, and notifications (Slack, Teams) are not actually sent. Workflow editors can enable **Send real messages** in the Test panel to verify that messages truly land: pick which channels should really deliver, provide a destination email address and/or phone number, and Spara sends live messages to those addresses instead of the test lead's contact info. Channels you don't pick stay simulated. The test lead itself stays in Test Mode; nothing is written to your CRM and analytics are excluded.

{% hint style="warning" %}
**Send real messages** is available to anyone who can edit the workflow. Each test run is capped at 10 real sends; additional steps beyond the cap fall back to simulation automatically. Notifications (Slack, Teams) only really send if you pick them as one of the channels, and they go to your configured channels rather than a test destination — confirm where notifications will post in the confirmation step before running.
{% endhint %}

### Send windows during a test

If a test reaches a Send Email, Send Text, or Call Phone step outside its allowed window (see [Workflows](/build/workflows#outgoing-time-windows)), the run pauses on a **Send window** banner instead of waiting for the window to open. Click **Skip send window** to send that step now and keep going. The step shows a **Window skipped** badge and notes when it would send once published. Only test leads can skip a window; a published workflow always waits.

{% hint style="info" %}
For a step-by-step walkthrough of building a workflow, see [Guide: Building Your First Workflow](https://docs.spara.com/guides/platform-guides/building-your-first-workflow).
{% endhint %}

## How a published workflow runs

**A lead only enters a workflow once.** Updating trigger criteria does not cause leads who already entered to re-enter.

**Unpublishing pauses execution.** Leads already in the workflow will not continue until you republish. Republishing resumes from where each lead left off; it does not restart the workflow.

**Misconfigured steps don't stop the whole workflow.** If a published step becomes misconfigured (e.g., a disconnected Twilio account), leads that reach that step are paused there. Other steps continue to execute normally. Fix the configuration and paused leads will resume.

**Engagement-based exits.** When workflow settings are enabled, leads automatically exit the workflow when they reply to an email, respond to a text, or answer a call from a workflow step.

## FAQ

### Can a lead be in multiple workflows at the same time?

Yes. A lead can be enrolled in multiple workflows simultaneously. Each workflow operates independently.

### What happens if I change a workflow that already has leads in it?

Unpublished changes do not affect leads currently in the workflow. When you publish, new leads will follow the updated workflow. Leads already in progress continue from their current step.

### Can workflows send messages to the assigned sales rep?

Yes. The **Send Email** and **Notify** steps can target the lead's assigned sales rep. Use **Send Email** to CC or send directly to the rep, and **Notify** to alert them via Slack, Teams, or Webex.


# Knowledge

How to train Spara agents on your company's knowledge base.

Spara agents are trained on your company's knowledge base — product information, marketing content, and key talking points. The [Knowledge page](https://app.spara.co/knowledge) is where you manage all of the sources your agents use to answer lead questions accurately.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-00b4c0ae2ad5987a8f2f11083dc0d8723a30b23c%2FKnowledge%20Page.png?alt=media" alt=""><figcaption><p>The Knowledge page showing indexed webpages and documents.</p></figcaption></figure>

Knowledge is different from your agent's prompt. The prompt defines *how* the agent behaves; knowledge defines *what* the agent knows.

## Knowledge Sources

### Webpages

Spara indexes your publicly available marketing website, including multiple subdomains (e.g., your product documentation site). This is where agents learn the bulk of information about your company.

The Webpages tab shows a domain hierarchy of all indexed pages. You can:

* **Toggle training** — Enable or disable individual pages or entire domains. Some pages are off by default because they rarely help an agent: privacy and cookie policies, login pages, tag and category listings, RSS feeds, and site files such as scripts and stylesheets. You can turn any of them back on here.
* **Search** — Find specific pages by URL or content
* **Review content** — View what Spara has indexed from each page

How a page is built affects how much of it Spara can read. If your web team wants to make pages easier for agents to read accurately, see [Developer: Optimizing Your Webpages for Spara Scraping](https://docs.spara.com/developers/installation/optimizing-your-webpages-for-spara-scraping).

### Documents

Upload files for Spara to learn from. Supported formats:

* PDF
* DOCX
* Markdown

Maximum file size is 25MB. Documents can be uploaded via drag-and-drop or file picker.

Each document can be set to **For training** (active) or **Archived** (excluded from agent knowledge). Use filters to find documents by file type, status, or last updated date.

Spara also supports syncing documents from external platforms:

* [Google Drive](/integrations/document-sync-integrations/google-drive)
* [Confluence](/integrations/document-sync-integrations/confluence)
* [Notion](/integrations/document-sync-integrations/notion)
* [Sharepoint](/integrations/document-sync-integrations/sharepoint)

## FAQ

### How do agents use knowledge?

When a lead asks a question, Spara searches across all enabled knowledge sources — webpages and documents — to find relevant information. The agent then incorporates that information into its response, following the tone and rules defined in its prompt.

### Is knowledge shared across all my agents?

Yes. Knowledge is shared across all agents in your organization, and any change to your knowledge base takes effect immediately for every agent.

### How often are webpages re-indexed?

Spara periodically re-crawls your website to keep the knowledge base current. If you need an immediate refresh after a website update, contact your Spara representative.

### Can I see what the agent knows about a topic?

Test your agents on the [Testing](/build/testing) page to verify responses in real time.

### What if I upload conflicting information?

Spara uses the most recently updated information. If you notice conflicting answers, review your knowledge sources and update or archive the outdated one.


# Data Model

How Spara organizes lead data — where fields come from, how conflicting sources are resolved, and how to manage your fields.

Spara automatically captures and organizes data about every lead that interacts with your agents. This data powers personalization, workflow triggers, conditions, and analytics across the platform. The [**Data Model**](https://app.spara.co/data-model) page is where you see and manage every field on your instance — built-in and custom — in one place.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-c95e1a540104b213067971e8436598f54b924863%2FData%20Model%20Page.png?alt=media" alt=""><figcaption><p>The Data Model page lists every field with its type, CRM sync status, and which agents gather it.</p></figcaption></figure>

## How It Works

Every piece of lead data is stored as a **field**. Fields are organized into categories and can come from multiple sources:

* **Automatically captured** — Spara collects data from website visits, chat conversations, email interactions, phone calls, and calendar events without any setup.
* **Gathered by agents** — Your Chat, Email, Phone, and Text agents can be configured to ask leads for specific information (like job title or company size) during conversations.
* **Synced from your CRM** — Fields from Salesforce, HubSpot, or Marketo are automatically synced and available alongside Spara-native data. See [CRM Integrations](/integrations/crm-integrations) for setup.
* **Enriched from third parties** — [Lead Enrichment](/pipeline/leads/lead-enrichment) and [Deanonymization](/pipeline/leads/deanonymization) fill in contact and company details from data vendors.
* **Extracted by workflows** — [API Step](/build/workflows/steps/api) and [Research Step](/build/workflows/steps/research) workflow steps can extract new data from external services or AI responses and save it to the lead profile.
* **Set by workflows** — A [Set Field Step](/build/workflows/steps/set-field) step writes a value you specify to a field when a lead reaches that point in a workflow.
* **Fixed value** — Fields stamped with a constant value on every Spara-engaged lead, set by your team. Useful for tagging leads with a source, campaign, or tier without relying on agent conversations or external data.
* **Read-only** — Fields Spara never sets. Their values come only from outside Spara, such as your CRM sync, your website's URL parameters, or the Leads API, and Spara never writes them back to your CRM.

For the full catalog of built-in fields — including the API names to use in personalization, workflows, and API requests — see [Developer: Spara Objects & Fields](https://docs.spara.com/developers).

### Lead, Account, and Owner Objects

Every field describes one CRM object, and the Data Model page has a tab for each:

* **Lead** — fields about the individual person interacting with your agents.
* **Account** — fields about the lead's company.
* **Owner** — fields about the lead's assigned owner.

Account and Owner fields are pulled from your CRM rather than gathered by agents, so new ones cannot be created manually. The **Create field** button applies to Lead fields.

For a tour of how these objects fit together and map to your CRM, see [Developer: Spara Objects & Fields](https://docs.spara.com/developers).

### Custom Fields

Any Spara agent can gather custom fields during a conversation. For example, you could configure a Chat agent to ask "What's your biggest challenge right now?" and save the response as a custom field called `biggest_challenge`. Custom fields appear alongside built-in fields everywhere in the platform — in workflows, personalization, analytics, and CRM syncs.

### Set By

Each field's **Set by** tab shows everything that writes the field and controls what each channel does with it, in two sections:

* **Where it comes from**: a read-only list of everything that sets the field today, including your website's URL parameters, workflow steps, CRM sync, fixed value stamps, and the channels gathering it in conversation.
* **Channel access**: what each channel does with the field. For every channel, choose one of three levels:
  * **Sets this field**: the agent asks for the field during conversations and saves what it learns. An agent that sets a field also sees its value.
  * **Sees the value**: the agent uses the field's stored value to inform its conversations, but never sets it. Use this for fields that come from your CRM, your website's URL parameters, or another agent, so every channel benefits from the data without re-asking for it or changing it.
  * **No access**: the field is not available to that agent at all.

New custom Lead fields start as **Sees the value** for every agent, so their values reach your agents' conversations right away; setting a field stays an explicit choice per agent. Fixed value fields can be seen but never set, since Spara stamps their value automatically. Read-only fields can also be seen but never set, since their value only comes from outside Spara.

Account and Owner fields come from your CRM, so agents can never set them. They start as **No access**; choose **Sees the value** for any agent that should use them in conversation. Granted values can also be referenced as variables in agent instructions, for example `{{ lead_owner_email }}`.

Built-in Lead fields that agents gather in conversation, such as email address, first name, last name, phone number, job title, and company name, have the same channel access controls. Their name and type are fixed and only admins can change how agents ask for them, but anyone who can edit the Data Model chooses which channels set or see each one. An agent only asks for a field where it is set to **Sets this field**, so keep that on for the fields each channel should capture; a field no channel sets is flagged on the Data Model page.

{% hint style="info" %}
Example: a `utm_campaign` field is stamped by your website's URL parameters when a visitor arrives. Choose **Sees the value** so your agents tailor the conversation to the campaign that brought the visitor in, but never ask for it. The value can only come from the URL, so **Sets this field** would have the agent asking a question the visitor cannot answer.
{% endhint %}

**Data type is permanent.** Once a field is saved, its data type (String, Integer, Boolean, etc.) cannot be changed. Choose the correct type when creating a field.

Creating and editing fields requires the **Data Model Editor** permission. Users without this permission can view field definitions but cannot create or modify fields.

### CRM Field Mappings

CRM field mappings (Salesforce, HubSpot, and Marketo) are set on each field in the Data Model. Open a field and find its sync section, labelled by CRM (for example **Salesforce sync** or **HubSpot sync**). If you have several CRMs connected, the field shows one sync panel per CRM.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-540753679d6d4c3ea54e509b860937b586074856%2FField%20Detail%20Drawer.png?alt=media" alt=""><figcaption><p>A field's details, showing its CRM sync, type, and picklist values.</p></figcaption></figure>

The sync section has one slot per CRM object the field can map to:

| CRM            | Lead fields      | Account fields | Owner fields |
| -------------- | ---------------- | -------------- | ------------ |
| **Salesforce** | Contact and Lead | Account        | Owner        |
| **HubSpot**    | Contact          | Company        | Owner        |
| **Marketo**    | Lead             | *None*         | *None*       |

In each slot, pick the CRM field and a write rule for each direction, **{CRM} → Spara** and **Spara → {CRM}**:

* **Overwrite**: replace any existing value
* **Set if empty**: write only when the receiving field is empty
* **Read-only**: never write in this direction

Save your edits with the page's **Save changes** prompt. Account and Owner mappings are pull-only, shown as **Pulled from {CRM}**, since Spara never writes to those objects.

Some rules are locked to **Read-only**:

* **{CRM} → Spara** is locked for fields Spara sets itself, such as GCLID, UTM parameters, and conversation summaries and transcripts.
* **Spara → {CRM}** is locked for [#what-is-a-read-only-field](#what-is-a-read-only-field "mention").

#### Built-in syncs

Some fields sync with every connected CRM without a mapping. Their slots show **Built in** with fixed rules, and they can't be changed or removed:

* **Email address** syncs with the Salesforce Lead and Contact `Email` field and the HubSpot Contact `email` property, and is how Spara finds a lead's CRM record. In Marketo, email is only used to find and create records; Spara doesn't copy it either way.
* **First name** and **Last name** sync with the HubSpot Contact `firstname` and `lastname` properties.
* **CRM record IDs** (Salesforce Lead ID, Salesforce Contact ID, HubSpot Contact ID, Marketo Lead ID) are pulled from the linked record and never written back.
* **Account fields** (company name, website, industry, employee count, annual revenue, billing city) and **Owner fields** (email, full name, active) are pulled from the CRM's Account or Company and Owner records.

If one of these fields already has a mapping of its own on an object, that mapping replaces the built-in sync there and stays editable.

#### Mapping problems

The field page flags mapping problems in plain language, including when:

* The Spara field is missing, or the mapped field no longer exists in the CRM
* The mapping syncs nothing because both directions are **Read-only**
* **Spara → {CRM}** writes to a field the CRM won't let Spara write (such as a formula or calculated field)
* The Spara and CRM field types don't match
* **Set if empty** never writes because the CRM field is required
* Some picklist values would be rejected by the CRM
* Two Spara fields write to the same CRM field
* Two CRMs both **Overwrite** the same Spara field. The CRM pulled last wins; Spara pulls Salesforce, then HubSpot, then Marketo.

#### Seeing sync status across fields

The Data Model table shows each field's mapping in the **{CRM} field**, **{CRM} → Spara**, and **Spara → {CRM}** columns. With several CRMs connected, the columns are labelled **CRM field**, **CRM → Spara**, and **Spara → CRM**, with one line per CRM. Use the **CRM sync** filter to show fields that are **Synced with {CRM}**, **Not synced**, or **Needs attention**.

#### Suggest fields

On the **Lead** tab, **Suggest fields** in the page header uses AI to suggest mappings for Salesforce Leads and Contacts and HubSpot Contacts. Each suggestion you pick saves immediately as a mapping, creating the Spara field if it doesn't exist yet.

#### Starting a field from your CRM

**Create field** opens a new field page. Choose **Start from a {CRM} field** to fill in the name, type, and picklist values from an existing CRM field; that object's slot in the sync section is prefilled with the mapping.

Each integration's settings page keeps record-level settings (sync on or off, create and update, Import Rules) and shows a read-only list of the fields synced with each object, with **Manage in Data Model** to jump back here. See [CRM Integrations](/integrations/crm-integrations).

## Trust Hierarchy

The same field can receive values from several sources: a lead types a phone number into chat, your CRM syncs a different one, and an enrichment vendor suggests a third. Spara resolves these conflicts with a trust hierarchy. Every field value is tagged with the source it came from, and a new value only overwrites the existing one when it comes from a source that is at least as trusted.

From most to least trusted:

| Trust level                         | What it covers                                                                                                                                                                                                                                    |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **System-observed** (highest)       | Signals Spara's systems observe directly — for example, the caller ID on a phone call, or the visitor's network-derived location (IP country, region, city).                                                                                      |
| **User-confirmed**                  | Values the lead explicitly confirmed — for example, an email address read back and confirmed during a voice call.                                                                                                                                 |
| **Self-reported & CRM**             | What leads tell your agents in conversation, values passed in from your website (URL parameters, webforms, the JavaScript API), values extracted by workflows, and fields synced from your CRM. Self-reported and CRM values are equally trusted. |
| **Third-party enrichment** (lowest) | Values from [Lead Enrichment](/pipeline/leads/lead-enrichment) and [Deanonymization](/pipeline/leads/deanonymization) data vendors.                                                                                                               |

How conflicts resolve:

* **Equal or higher trust overwrites.** Within the same level, the most recent update wins — so your CRM sync and your agents can both keep a field current.
* **Lower trust never overwrites.** Enrichment fills in fields that are empty, but it never replaces what a lead told your agent or what your CRM synced. The existing value stays in place.
* **Deanonymization stays in its own lane.** Identity guesses from visitor deanonymization are stored in separate, read-only **Deanonymized** fields rather than the primary identity fields, so a vendor's best guess is never confused with data the lead actually provided.

For example: a lead types a phone number into chat (self-reported). If they later call one of your phone numbers, the caller ID (system-observed) replaces the typed value. From then on, neither a conversation nor an enrichment vendor can overwrite it — only another system-observed or more trusted source can.

The same hierarchy is documented alongside the object and field reference in [Developer: Spara Objects & Fields](https://docs.spara.com/developers#trust-hierarchy).

## Field Reference

The full list of built-in fields lives in the developer documentation, organized by category with the API name, type, and description for each field: [Developer: Spara Objects & Fields](https://docs.spara.com/developers).

To see the fields on your own instance — including your custom fields and CRM-synced fields — open [**Data Model**](https://app.spara.co/data-model) in the app. You can search, filter by type, origin, sync status, or gathering agent, and click any field to view or edit its details.

## FAQ

### Where can I use these fields?

Everywhere in Spara. Fields are available in workflow triggers and conditions, email and text message personalization, agent instructions, API request bodies, and analytics filters. See [Guide: How to Use Spara's Text Editor](https://docs.spara.com/guides/platform-guides/how-to-use-sparas-text-editor) for how to insert fields into text.

### How do I create custom fields?

There are two ways to create a custom field:

1. **Gathered by an agent** — Configure any Spara agent to ask for specific information and map the response to a named field. For example, add "Ask the lead about their timeline" to your Chat agent's instructions and map the response to a field called `timeline`.
2. **Fixed value** — Create a field with a constant that is stamped on every Spara-engaged lead automatically, without any agent conversation. Go to [**Data Model**](https://app.spara.co/data-model), create a new field, and set the source to **Fixed value**.

You can also set the source to **Read-only** for a field whose value only comes from outside Spara, such as your CRM. See [#what-is-a-read-only-field](#what-is-a-read-only-field "mention").

Custom fields are immediately available across the platform — in workflows, personalization, analytics, and CRM syncs.

### Where do I edit CRM field mappings?

On the field itself. Open the field in [**Data Model**](https://app.spara.co/data-model) and use its CRM sync section. Integration settings pages list synced fields read-only and link back to the Data Model. See [#crm-field-mappings](#crm-field-mappings "mention").

### What is a Fixed value field?

A Fixed value field holds a constant that is automatically stamped on every lead Spara engages with, with no agent conversation required. For example, you could create a field called `lead_source_campaign` with a fixed value of `"spring-webinar-2026"` to tag every lead from a specific campaign. Fixed value fields are useful for tracking source attribution, campaign codes, or tier tags that apply uniformly to all leads your agents interact with.

### What is a Read-only field?

A Read-only field is one Spara never sets: no agent gathers it, no workflow step writes it, and Spara never syncs it back to your CRM. Its value only comes from outside Spara — your CRM sync, your website's URL parameters or JavaScript API, or the Leads API — for example a Salesforce field you pull into Spara so your agents can see it. To make a field Read-only, open it in [**Data Model**](https://app.spara.co/data-model) and set the source to **Read-only**.

Spara won't save a field as Read-only while something in Spara still sets it. The error lists what to change first:

* A workflow **Set Field** step, or an **API** or **Research** step that saves to the field.
* A voice agent **Set Field** tool that writes to the field.
* A CRM field mapping whose **Spara → CRM** rule isn't **Read-only**.

Channels set to **Sets this field** switch to **Sees the value** automatically when you save the field as Read-only. Once a field is Read-only, CRM field mappings for it are locked to **Read-only** in the Spara → CRM direction.

### Why didn't my CRM sync (or enrichment) change a field?

Most likely the existing value came from an equally or more trusted source — see [#trust-hierarchy](#trust-hierarchy "mention"). For example, enrichment data never overwrites a value the lead provided directly, and nothing short of another system-observed source can replace a phone number captured from caller ID.

### What happens when a field has no value?

It depends on the field:

* **Name fields** (`{{ first_name }}`, `{{ last_name }}`, `{{ full_name }}`) — Spara falls back to the best identity available for the lead (for example, an email address or company name) rather than rendering blank.
* **All other fields** — render as empty when the value hasn't been captured (e.g., `{{ company_name }}` becomes blank).

Use [Condition Step](/build/workflows/steps/condition) steps in workflows to check whether a field has a value before acting on it.


# Testing

How to test Spara AI.

The [Testing](https://app.spara.co/tests) page lets you try out any agent (before or after it goes live) and review past test sessions in one place.

Click **Test** to start a session. Choose the **Agent Type** (such as Chat or Phone), the specific **Agent** to test (including unpublished **drafts**), and the **Interface** to run it in. Spara loads a test conversation where you can interact exactly as a lead would.

Give feedback on any Spara-generated response by clicking the thumbs up or thumbs down button on a message. A modal appears with fields to enter your feedback, which is used to improve Spara AI's performance.

Past test sessions are listed below the controls (the agent tested, its published/draft status, who ran the test, and when), so your team can revisit earlier runs.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-6f3cb660a9116cd69c572974ef1975c050628175%2FTesting%20Page.png?alt=media" alt=""><figcaption><p>The Testing page: start a test for any agent and interface, and review past sessions.</p></figcaption></figure>

To test a single capability from inside its editor and run automated Simulations, see [Testing](/build/channels/configuring/testing).


# Leads

How to view and interact with leads in Spara.

The [Leads page](https://app.spara.co/leads) is where you manage every lead that has interacted with your Spara agents. Each row represents a single lead with their latest webpage visit, latest engagement, and next workflow step.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-46dbb012b2331ec5ebb1b5bf86063608530674e0%2FLeads%20Page.png?alt=media" alt=""><figcaption><p>The Leads page showing lead stage, latest actions, and next workflow steps.</p></figcaption></figure>

Each lead row shows:

* **Lead** — Name, email, and status indicators. A green checkmark means the lead self-identified; a yellow warning icon means they were identified through deanonymization or enrichment.
* **Latest Webpage Visit** — The most recent page the lead viewed on your website, with the visit time.
* **Latest Spara Engagement** — The most recent meaningful engagement with a Spara agent (e.g., Sent Chat Message, Sent Email Reply, Agent Sent Email, Answered Phone Call, Completed Product Demo). Webpage visits are tracked separately so they don't drown out real engagements.
* **Next Spara Workflow Step** — The upcoming workflow touchpoint, or "No upcoming steps" if the lead isn't in an active workflow.

### Filtering and Search

Use filters to narrow your leads list:

| Filter             | Options                                                                                                                                                                                                                                                         |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Timeframe**      | Last 7 / 14 / 30 days, All time, or a custom range. Shows leads with any recorded activity in the window, whether the lead reached out or Spara did: a website visit, a chat, an email or text, a call, a demo, or a booked meeting. All time shows every lead. |
| **Agent**          | Filter by a specific Chat, Email, or Phone agent                                                                                                                                                                                                                |
| **Channel**        | Chat, Email, Phone, Text                                                                                                                                                                                                                                        |
| **Meeting Source** | Which channel the lead's meeting was scheduled through: Chat, Email, Phone, or Product Demo                                                                                                                                                                     |
| **Engagement**     | High (5+ messages), Medium (<5 messages), Browsing (no messages)                                                                                                                                                                                                |
| **Stage**          | Any lead stage                                                                                                                                                                                                                                                  |
| **Lead Source**    | Spara, Salesforce, HubSpot, Marketo, Leads API                                                                                                                                                                                                                  |
| **Country**        | Searchable country list based on IP location                                                                                                                                                                                                                    |
| **Known**          | Verified vs. enriched leads                                                                                                                                                                                                                                     |

Use the search bar to find leads by name, email, or company. Click **Export as CSV** to download the filtered list.

#### Custom filters

Click **All filters** and scroll to **More fields** to filter by any field in your [Data Model](/build/data-model), not just the filters listed above. Pick a field, pick a condition, and (if the condition needs one) a value, then click **Apply filter**:

* **is true** / **is false**: for yes/no fields
* **equals**: for fields with a fixed set of values
* **is defined** / **is not defined**: for whether the field has a value at all
* **is in range**: for select number fields (e.g. company headcount)

Each custom filter appears as a removable pill next to your other filters. Add as many as you need; leads must match every filter to appear in the list. Adding the same field twice matches either value, so you can filter to more than one option on that field at once. To change a custom filter, remove its pill and add it again with the new value.

Custom filters combine with the standard filters and search above, are included in the page URL so you can share a filtered view, and are honored by **Export as CSV**.

#### Filter with Ask Spara

Describe the leads you want to see, and [Ask Spara](/platform/ask-spara) sets the filters for you. Click **All filters**, then **Filter with Ask Spara**, and type a request such as "Show me leads from HubSpot in the last week." You can also ask from the Ask Spara bar at the top of any page, and Ask Spara takes you to the Leads page first.

Ask Spara builds each request from the filters above and your data model fields. The filters it sets appear next to your other filters, where you can remove them, and it tells you about any part of the request it could not apply. To change the view, ask again in the same conversation.

## Lead Details

Click any lead to open its page. Everything Spara knows about the lead sits on the left, and the full history of the relationship runs down the right.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-dcc2e005fa17ba32c4fd1e2063a5b28d93459228%2FLead%20Details.png?alt=media" alt=""><figcaption><p>The lead page: personal details and enrichment on the left, the timeline of every touchpoint on the right.</p></figcaption></figure>

The record on the left is organized into sections:

* **Personal Details**: Name, email (with validation status), phone, job title, seniority, department, location, LinkedIn profile, background, skills, and interests. Each field shows where its value came from, such as HubSpot, Spara enrichment, or a conversation. Click a field to see every source that reported it.
* **What Spara understands**: An AI-generated summary of the relationship and the questions the lead has asked.
* **What Spara gathered**: Fields captured during conversations and workflows, plus fields Spara works out from the lead's activity, such as the teammate who last took over the chat.
* **Account**: The company record synced from your CRM, merged with enrichment data such as products, objectives, competitors, and recent news.
* **Owner**: The team member who owns the lead in your CRM.

### Timeline

The timeline lists every touchpoint in one chronological feed: chat conversations, phone calls, emails, product demos, workflow steps, and events such as an email being opened. Click a row to expand it, or use its action to read the email, listen to the call, or open the transcript. **Open full timeline** shows the message-level conversation history across all channels. Expand a website visit to see the pages the lead viewed that day; **Open full timeline** lists each page view, with the full URL on hover.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-81bac1c49c19607b500a88490ea6cbe744d1f0e7%2FLead%20Timeline.png?alt=media" alt=""><figcaption><p>The full timeline showing a chat conversation between a lead and a Spara agent.</p></figcaption></figure>

This is where you can:

* **Take over a conversation**: Click "Take over chat" at the bottom to enter manual mode. Spara agents will stop sending automatic messages. Click "Return to Automated" when you're done.
* **Control what Spara does next**: The **What Spara will do** section below the timeline holds the **Workflows outreach enabled** and **AI Responses enabled** toggles. See [Blocking](/pipeline/leads/blocking) for what each one controls.

When a team member takes over via **Take over chat**, the timeline shows a **"\[Name] has taken over the chat"** marker at that point in the history. When they click **Return to Automated**, a **"Returned to automated"** marker appears. These markers make it easy to see at a glance exactly when human and AI control switched during a conversation.

Once a team member replies after taking over, the lead's **Manual takeover user** field (`manual_takeover_user`) holds that team member's email. Taking over without replying leaves it unchanged, and it stays set after the chat returns to the agent. When a different team member takes over and replies, the field moves to them. The field is listed in the [Data Model](/build/data-model) and can be synced to your CRM, so lead ownership can follow the rep who worked the chat; it isn't available as a leads filter.

{% hint style="info" %}
Spara can send Slack, Webex, or Microsoft Teams notifications when specific events happen, so your team knows when to take over. Configure these in [Notifications](/platform/settings/notifications).
{% endhint %}

All fields come from Spara's [Data Model](/build/data-model) — a combination of data gathered by agents, CRM syncs, and lead enrichment.

## FAQ

### How do I improve a response the agent gave?

Lead conversations are connected to Ask Spara. If you see a response you want to improve, use the feedback tools in the conversation to suggest better behavior. This helps refine your agent's prompt over time.

### Can I export lead data?

Yes. Apply any filters on the Leads page and click **Export as CSV** to download the filtered results.

### How does deanonymization work?

When a visitor hasn't self-identified, Spara can match them to known contacts using IP and behavioral signals. Deanonymized leads are marked with a yellow warning icon to indicate the data came from external sources rather than direct identification. See [Deanonymization](/pipeline/leads/deanonymization) for details.

### What happens when a lead is blocked?

Spara automatically blocks leads who send harmful or malicious content. Blocked leads can no longer receive responses from Spara. See [Blocking](/pipeline/leads/blocking) for details on how moderation works and how to manually block or unblock leads.


# Blocking

How Spara detects and blocks leads with malicious or inappropriate behavior.

Spara automatically monitors all incoming messages for harmful content. When a lead sends messages that violate safety thresholds, Spara blocks the lead to protect your team and maintain a safe sales environment.

## How blocking works

Every message a lead sends is evaluated in real time using OpenAI's content moderation model. The model checks for categories including harassment, illicit content, violence, hate speech, sexual content, and self-harm. Each message receives a category score between 0 and 1.

Spara tracks a cumulative moderation score across all of a lead's messages. When the total score reaches **1.0 or higher**, the lead is automatically blocked. A single severe message (e.g., a threat or illicit request) can trigger a block immediately, while milder violations accumulate over multiple messages.

When a lead is blocked:

* Spara stops responding to the lead's messages
* The lead appears as **Blocked** on the [**Leads**](https://app.spara.co/leads) page
* A [Notifications](/platform/settings/notifications) is sent if the Blocked event is enabled in your notification settings

## Moderation categories

Spara evaluates messages against these categories, based on [OpenAI's moderation policy](https://platform.openai.com/docs/guides/moderation):

| Category       | Examples                                                    |
| -------------- | ----------------------------------------------------------- |
| **Harassment** | Insults, threats, or abusive language directed at the agent |
| **Illicit**    | Requests for illegal goods, services, or activities         |
| **Violence**   | Threats of violence or graphic violent content              |
| **Hate**       | Discriminatory language targeting protected groups          |
| **Sexual**     | Explicit sexual content or solicitation                     |
| **Self-harm**  | Content promoting or describing self-harm                   |

## Manual blocking and unblocking

Your team can manually override the automatic moderation system. Open the lead from the [**Leads**](https://app.spara.co/leads) page. The controls are in the **What Spara will do** section, below the timeline on the right.

* **Block a lead** — Turn off the **AI Responses enabled** toggle, regardless of the lead's moderation score. Spara stops responding to the lead on every channel — website chat, AI demos, and incoming voice calls — and submitting the same email address again does not create a fresh, unblocked lead.
* **Unblock a lead** — Turn the **AI Responses enabled** toggle back on for a lead that was automatically flagged. Once unblocked, Spara will not re-block the lead automatically, even if they send additional flagged messages. This is useful when a false positive occurs.

The **Workflows outreach enabled** toggle in the same section is the outgoing counterpart: while **AI Responses enabled** covers incoming engagement, turn off **Workflows outreach enabled** to stop [Workflows](/build/workflows) from emailing, texting, or calling the lead. The lead stays in its workflows, and every Send Email, Send Text, and Call Phone step is skipped with a note on the step. Other steps, like notifications and CRM updates, still run. The toggle applies to this lead only, even when other leads share its email address or phone number. Use it when a rep takes a lead over.

## FAQ

### Can I adjust the sensitivity of the moderation?

The moderation thresholds are not configurable per-organization. They are calibrated to block clearly harmful content while minimizing false positives.

### What happens to a blocked lead's data?

Blocking a lead does not delete any data. Their conversation history, field data, and activity remain visible on the Leads page. The lead simply cannot receive further responses from Spara.

### Does moderation apply to email messages?

Yes. Both chat messages and email messages from leads are evaluated for harmful content and contribute to the lead's cumulative moderation score.


# Deanonymization

How Spara identifies anonymous website visitors before they introduce themselves

Deanonymization identifies anonymous visitors interacting with Spara by resolving their identity through a third-party data vendor (currently Vector). When a visitor lands on a page where Spara's JS snippet is installed, Vector attempts to match them to a known person or company using privacy-safe data sources — giving your chat capability context before the first message is sent.

Important: Deanonymization works at the chat-widget level by default. It is not a site-wide visitor tracking tool unless your account is configured for “All Site Traffic” mode.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-232322d6f60f43a663830294e413861985838941%2FDeanonymization.png?alt=media" alt=""><figcaption><p>The Leads page distinguishes self-identified leads (green check) from deanonymized visitors (yellow warning).</p></figcaption></figure>

### How it works

1. A visitor lands on a page where Spara is active.
2. Spara sends visitor data to Vector’s identity resolution API via a lightweight pixel.
3. Vector attempts to match the visitor to a known contact or company in its dataset.
4. If matched, the capability can reference those details (name, company, job title, etc.) in its prompt context.

The visitor’s experience is unchanged — but the capability now has a head start on who it’s talking to.

### Trigger modes

Deanonymization is configured at the account level by a Spara admin. You can view your current mode and provider under **Settings > Signals**; contact your CSM to change them.

| Mode                    | When it runs                                        | Notes                                                           |
| ----------------------- | --------------------------------------------------- | --------------------------------------------------------------- |
| Off                     | Never runs                                          | <p><br></p>                                                     |
| On engagement (default) | When a visitor sends at least one message in chat   | Default for all accounts                                        |
| All Site Traffic        | On every page visit, regardless of chat interaction | Additional charge. Coordinate with your Spara point of contact. |

### What data is returned

When a match is found, the following fields may be populated on the lead record. Not all fields are guaranteed — availability depends on Vector’s coverage for that visitor.

| Field                    | Location             | Notes                                                      |
| ------------------------ | -------------------- | ---------------------------------------------------------- |
| first\_name / last\_name | Lead page header     | May reflect a contact match, not just the company          |
| email                    | Lead Information tab | Work email if available — not always populated             |
| company\_name            | Lead Information tab | Matched from company-level resolution                      |
| job\_title               | Lead Information tab | From contact record when matched at person level           |
| linkedin\_url            | Enrichment section   | When available in Vector’s dataset                         |
| industry                 | Enrichment section   | Company-level field; may reference domain rather than name |

Additional information on Spara's data model can be found on the [Data Model](/build/data-model) page.

On the Leads detail page, the right-hand panel distinguishes between visitor-provided data (gathered in chat) and deanonymized/enriched data (vendor-sourced).

### Status icons on the lead header

A small icon next to the lead’s name signals the confidence level of their identity data:

* Green checkmark — Verified identity. The visitor provided their email directly in chat. First-party, confirmed match.
* Yellow warning triangle — Unverified. Identity came from deanonymization, not from the visitor. Tooltip: “Unverified information may be inaccurate.”
* No icon — Anonymous. No identity data available from either source.

### Accuracy and limitations

Deanonymization is probabilistic — it is not always accurate. A few things to keep in mind:

* Contact-level match rates typically range from 15–30% of US-based traffic. Company-level matches are higher. Rates depend on your visitor base and Vector’s coverage of that audience.
* Vector operates only in the United States. International visitors will not be matched. Vector is geofenced to comply with US privacy regulations.
* Email is rarely returned. Vector’s dataset does not reliably include email addresses. Collecting email through the chat conversation remains the most reliable path to email capture.
* Company-level ≠ person-level. Corporate IPs and shared networks often resolve to the company but not a specific person — name and title fields may be blank even when company is present.

### Privacy and compliance

Vector uses privacy-safe data sources and does not rely on third-party cookies. Vector is SOC 2 Type 2, GDPR, and CCPA compliant. Spara passes Vector’s data to the lead record as-is, without additional cleansing or validation.

Note: Vector requires customers to update their Privacy Policy and Consent Management Platform (CMP) to disclose the use of third-party data partners. Confirm with your Spara point of contact if you have not already done so.

### FAQ

**Can I use deanonymized data in my CRM?**

Yes. The deanonymized fields (including Deanonymized Email) can be mapped to CRM properties from each field's CRM sync section in the [**Data Model**](https://app.spara.co/data-model), so deanonymized data flows into your CRM alongside visitor-provided data.

**Can I filter leads by whether they were deanonymized?**

Yes. The Leads page includes an “Identification” filter with two options: Self-identified (visitor provided details in chat) and Deanonymized by IP address (details from Vector). Useful for segmenting outreach or evaluating hit rate quality.

**Does deanonymization work for non-chat visitors?**

Only in “All Site Traffic” mode. In the default “On engagement” mode, a visitor must send at least one message before deanonymization runs. Contact your Spara point of contact to enable this.

**Can I use deanonymized data to trigger a workflow?**

Yes. When a lead is deanonymized, the resolved data is written to dedicated fields — Deanonymized Company name, Deanonymized Company domain, Deanonymized Company LinkedIn URL, Deanonymized Email, Deanonymized First name, Deanonymized Last name, Deanonymized LinkedIn URL, Deanonymized Job title, Deanonymized Department, Deanonymized First/Last visit at, and Deanonymized Unique pages visited — that you can reference in workflow conditions (for example, "Deanonymized Company domain is defined"). This lets you enroll a visitor from a target account in a workflow when they're identified, even if they never chatted.

Deanonymized leads also get the same location fields a chat lead gets: IP Country Code, IP Country Name, IP Region, IP City, and IP Address. They are taken from the visitor's website visits, so location conditions (for example, "IP Country Name equals United States") work the same way for leads that never chatted as for leads that did. The IP Address is recorded only for visitors who accepted tracking under your cookie consent setup.

**What vendor powers deanonymization?**

Spara supports two providers: [Vector (Deanonymization)](/integrations/signals/vector) for person-level identity resolution (the default) and [Bombora (Deanonymization)](/integrations/signals/bombora) for company-level firmographics. The providers are chosen with your Spara point of contact; an account deanonymizing all website visitors can run either or both. See the provider pages for the full list of fields captured, match rates, and how each integration is enabled.

**What’s the difference between deanonymization and enrichment?**

Deanonymization identifies anonymous visitors using vendor data — no email required. [Lead Enrichment](/pipeline/leads/lead-enrichment) takes a lead whose email is already known and layers on additional company and contact data. Deanonymization is the first guess at who someone is; enrichment fills in the full picture once you have a confirmed identity.


# Lead Enrichment

How Spara automatically enriches leads with contact and company data after capturing their email.

When a lead provides their work email address during a conversation, Spara automatically enriches their record with additional contact and company data from a third-party data vendor ([Explorium (Lead Enrichment)](/integrations/signals/explorium)). This gives your capabilities — and your sales team — a fuller picture of who they're talking to, without the lead needing to provide every detail themselves.

Enrichment runs in the background and typically completes within seconds. The enriched data appears on the lead page (see [Leads](/pipeline/leads)), labeled **Spara enrichment** under Personal Details and Account, and is available to capabilities in subsequent messages.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-6bdca7c43d92a5fa5cd12f69ea2f9c82c5768e69%2FLead%20Enrichment.png?alt=media" alt=""><figcaption><p>Enriched company data in the Account section of the lead page.</p></figcaption></figure>

## When enrichment runs

Enrichment triggers automatically when a lead's **email address** is captured — whether the lead typed it in chat, submitted it through a webform, or it was passed in via [Developer: Query Parameters](https://docs.spara.com/developers/spara-api/query-parameters).

Requirements for enrichment to run:

* The lead must have a **work email address**. Personal email domains (Gmail, Yahoo, Outlook, Hotmail, etc.) are excluded because data vendors cannot reliably match them to contact or company records.
* Enrichment runs **once per 24-hour period** per lead. If a lead's email changes, enrichment runs again for the new address.

## What data is enriched

Enrichment populates two categories of data on the lead record:

### Personal information

| Field                  | Description                                          |
| ---------------------- | ---------------------------------------------------- |
| **Name**               | First and last name from the contact record          |
| **Job title**          | Current role at their company                        |
| **Seniority**          | Level (e.g., Director, VP, C-Suite)                  |
| **Department**         | Functional area (e.g., Engineering, Marketing)       |
| **LinkedIn profile**   | URL to their LinkedIn profile                        |
| **Location**           | Geographic location                                  |
| **Skills & interests** | Professional skills and interests from their profile |

### Company details

| Field                    | Description                             |
| ------------------------ | --------------------------------------- |
| **Company name**         | Legal or common company name            |
| **Website**              | Company website URL                     |
| **Industry**             | Primary industry classification         |
| **Revenue**              | Estimated annual revenue                |
| **Headcount**            | Approximate employee count              |
| **Business model**       | B2B, B2C, marketplace, etc.             |
| **Products**             | Key products or services offered        |
| **Corporate objectives** | Strategic goals and initiatives         |
| **Competitors**          | Known competitors in their space        |
| **Recent news**          | Recent press coverage and announcements |

Not all fields are guaranteed — availability depends on the data vendor's coverage for each contact and company.

### Conversation summary

In addition to vendor-sourced data, Spara generates an AI-powered **conversation summary** after the lead has engaged on any channel — chat, email, SMS, a phone call, or a product demo. This includes:

* A summary of the conversation so far
* Questions the lead asked
* Sales stage assessment
* Pain points identified
* Interests expressed

The conversation summary updates whenever the lead is active on any channel.

## How enriched data is used

Enriched data benefits both your capabilities and your team:

* **Capability context** — Capabilities can reference enriched data in their responses. For example, if enrichment reveals the lead works at a Fortune 500 company, the capability can tailor its pitch accordingly.
* **Lead details** — Your team sees enriched data on the [**Leads**](https://app.spara.co/leads) page, giving sales reps context before they take over a conversation or reach out directly.
* **Workflow conditions** — Enriched fields can be used in [Workflows](/build/workflows) conditions to route leads based on company size, industry, or seniority.
* **CRM syncing** — Enriched data syncs to your connected CRM ([Salesforce](/integrations/crm-integrations/salesforce), [HubSpot (CRM)](/integrations/crm-integrations/hubspot-crm), or [Marketo](/integrations/crm-integrations/marketo)).

## FAQ

### What's the difference between enrichment and deanonymization?

[Deanonymization](/pipeline/leads/deanonymization) identifies anonymous visitors using IP and behavioral signals — no email required. Enrichment takes a lead whose email is already known and layers on additional contact and company data. Deanonymization is the first guess at who someone is; enrichment fills in the full picture once you have a confirmed identity.

### Does enrichment work with personal email addresses?

No. Enrichment requires a work email address. Personal domains like Gmail, Yahoo, and Outlook are excluded because data vendors cannot reliably match them to professional records.

### Can I disable enrichment?

Enrichment is enabled by default for all accounts. Contact your Spara account manager if you need to disable it.

### How often is enrichment data refreshed?

Enrichment runs once per lead when their email is first captured, and can re-run if their email address changes. Company data is refreshed periodically to keep information like revenue, headcount, and news current.


# Accounts

How Spara organizes the companies in your pipeline, synced from your CRM.

The [Accounts page](https://app.spara.co/accounts) shows the companies in your pipeline, synced from your CRM. Each account groups the leads at that company alongside its firmographics and the owner responsible for it, so you can understand engagement at the company level — not just lead by lead.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-7a3c48fe0f525b1b45790c6b9c026c96f85988b2%2FAccounts%20Page.png?alt=media" alt=""><figcaption><p>The Accounts page, showing companies synced from your CRM with their industry, size, and owner.</p></figcaption></figure>

## Account details

Click any account to open its detail view — a single card summarizing everything Spara knows about the company. The detail view includes:

* **Firmographics** — Website, Industry, Employees, Annual Revenue, and Billing City.
* **Owner** — The person responsible for the account. Click through to their [Owners](/pipeline/owners) record.
* **Leads** — How many leads Spara has engaged at this company. Click the count to open those leads on the [Leads page](https://app.spara.co/leads).
* **CRM Source** — Which CRM the account synced from. Click **View in HubSpot** or **View in Salesforce** to open the record in your CRM.
* **Custom fields** — Any account-level [Data Model](/build/data-model) fields your team has configured appear at the bottom of the card.

## Syncing from your CRM

Accounts are synced from your connected CRM — Salesforce, HubSpot, or Marketo — when account syncing is enabled. Spara keeps them up to date as records change in your CRM, so the Accounts page reflects your source of truth without manual entry.

If your Accounts page is empty, either no CRM is connected or account syncing is turned off. See [CRM Integrations](/integrations/crm-integrations) to connect a CRM, and reach out to your Spara customer success representative to enable account syncing.

{% hint style="info" %}
For a full picture of how Spara's data model operates and syncs with your CRM, see [Developer: Spara Objects & Fields](https://docs.spara.com/developers/data-model).
{% endhint %}

## FAQ

### Why is my Accounts page empty?

Accounts only populate from a connected CRM with account syncing enabled. Connect Salesforce, HubSpot, or Marketo under [**Settings > Integrations**](https://app.spara.co/organization/integrations), then confirm account syncing is on. If a CRM is already connected, contact your Spara customer success representative to turn on account syncing.

### How are accounts linked to leads?

Spara matches each lead to a company account so you can see all engagement at that company in one place. The account detail view shows the number of related leads, and you can filter the [Leads page](https://app.spara.co/leads) by account.

### What does the Owner column show?

The owner is the person in your CRM responsible for the account — typically the assigned sales rep or account owner. Owners are managed on the [Owners](/pipeline/owners) page.

### Can I add custom fields to an account?

Yes. Account-level fields defined in your [Data Model](/build/data-model) appear in the account detail view alongside the built-in firmographics.


# Owners

How Spara tracks the people responsible for your accounts and leads.

The [Owners page](https://app.spara.co/owners) shows the people in your CRM responsible for your accounts and leads — your sales reps and account owners — synced directly from your CRM. Owners connect every account and lead to the person who owns the relationship, so Spara can route, personalize, and report by rep.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-e9cf95025c61fe48d9e6241389cbbe0afe76ebd9%2FOwners%20Page.png?alt=media" alt=""><figcaption><p>The Owners page, showing account owners and sales reps synced from your CRM.</p></figcaption></figure>

## Owner details

Click any owner to open their detail view, which summarizes who they are and what they're responsible for. The detail view includes:

* **Email** and **Role** — The owner's contact details and title.
* **Accounts** — How many [Accounts](/pipeline/accounts) this owner is responsible for. Click the count to see them on the Accounts page.
* **Leads** — How many leads this owner is responsible for. Click the count to open those leads on the [Leads page](https://app.spara.co/leads).
* **CRM Source** — Which CRM the owner synced from. Click **View in HubSpot** or **View in Salesforce** to open the record in your CRM.
* **Spara User** — Whether this owner also has a Spara login, linking them to their platform account.
* **Custom fields** — Any owner-level [Data Model](/build/data-model) fields your team has configured appear at the bottom of the card.

## How owners connect accounts and leads

Owners tie your pipeline together. Each [Accounts](/pipeline/accounts) and lead carries the owner responsible for it, which lets you:

* **Filter by owner** — Narrow the [Accounts](/pipeline/accounts) and [Leads](https://app.spara.co/leads) pages to a single rep's book of business.
* **Personalize with owner data** — Reference a lead's assigned rep by name in agent messages and workflow logic. See the CRM integration pages for how owner data flows into Spara — for example, [HubSpot (CRM)](/integrations/crm-integrations/hubspot-crm).

## Syncing from your CRM

Owners are synced from your connected CRM — Salesforce, HubSpot, or Marketo — when owner syncing is enabled. Spara keeps them up to date as your CRM changes.

If your Owners page is empty, either no CRM is connected or owner syncing is turned off. See [CRM Integrations](/integrations/crm-integrations) to connect a CRM, and reach out to your Spara customer success representative to enable owner syncing.

{% hint style="info" %}
For a full picture of how Spara's data model operates and syncs with your CRM, see [Developer: Spara Objects & Fields](https://docs.spara.com/developers/data-model).
{% endhint %}

## FAQ

### Why is my Owners page empty?

Owners only populate from a connected CRM with owner syncing enabled. Connect Salesforce, HubSpot, or Marketo under [**Settings > Integrations**](https://app.spara.co/organization/integrations), then confirm owner syncing is on. If a CRM is already connected, contact your Spara customer success representative to turn it on.

### What's the difference between an owner and a Spara user?

An owner is a person synced from your CRM who is responsible for accounts and leads — they don't need a Spara login to appear here. A Spara user is someone with access to the Spara platform. When an owner also has a Spara login, the owner detail view links the two under **Spara User**.

### Can I reassign an account or lead to a different owner?

Ownership is synced from your CRM, so change the owner on the record in Salesforce, HubSpot, or Marketo and Spara will reflect it on the next sync.


# Analytics

How Spara tracks conversion metrics and lead engagement across all agents.

The [Analytics page](https://app.spara.co/analytics) gives you a real-time view of how your Spara agents are performing — from high-level conversion metrics to drill-downs into individual lead conversations.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-534d71510bd7bb457f600c6d8167e30eb9fa4cef%2FAnalytics%20Page.png?alt=media" alt=""><figcaption><p>The Analytics dashboard with conversion metrics and engagement charts.</p></figcaption></figure>

## Overview

The Overview section shows key metrics across all agents at a glance:

* **Leads engaged** — Total leads who sent a message or scheduled a meeting
* **Messages sent by Spara** — Total agent messages across all channels
* **Average session length** — How long leads typically engage
* **Meetings booked** — Meetings booked with Spara across every channel, counted when the booking happened
* **Emails collected** — Email addresses captured
* **Call calendar shown** — Leads offered a calendar to book a meeting on any channel: a calendar shown in chat or a product demo, times offered on a call, or a booking link opened from an email

Two summary charts show **Call Interest** (who asked to speak with sales) and **Spara Touchpoints** (engagement by channel).

## Channel Sections

Analytics are organized by agent type, each with channel-specific metrics:

### Chat

* **Conversion funnel** — Website visitors to conversations started
* **Recent questions** — Searchable, categorized list of questions leads asked. Click any question to view the original conversation.
* **Conversation volume** — Bar chart showing conversations over time, broken down by chat interface (Navigator, Smartbar, Fullscreen)
* **Conversation length** — Distribution of how many messages leads send
* **Country of origin** — Geographic breakdown of your leads
* **Initial page URLs** — Which pages leads were on when they started chatting
* **Custom field charts** — Metrics based on data your agents gather (e.g., company size, interest level)

### Email

* **Meetings scheduled** — Meetings scheduled by leads who clicked a booking link in a Spara email, counted when the booking happened
* **Email funnel** — Unique leads through the email pipeline, including a reply stage showing how many leads replied to at least one email
* **Email messages funnel** — Message-level conversion metrics, including a reply stage showing reply volume
* **Bounce rate** — Percentage of emails that could not be delivered (invalid addresses), with a drill-down link to the affected leads
* **Reply rates** — Breakdown of replies vs. no-replies
* **Unsubscribes** — Opt-out tracking

### Phone

* **Conversion funnel** — Calls to qualified conversations to meetings scheduled
* **Lead messages per call** — How much leads talked: total messages sent by leads across all calls, and the average per call
* **Transfers** — Total successful cold and warm transfers to a human. The rate's denominator is calls handled by agents that have a transfer tool configured ("eligible calls")
* **Meetings scheduled** — Total meetings scheduled during phone calls, including rescheduled appointments. The rate's denominator is calls handled by agents that have the booking (calendar) tool configured ("eligible calls")
* **Recent questions** — Questions asked during phone calls, searchable and categorized. Click any question to view the call transcript.
* **Comparison mode** — When a phone A/B test is active, toggle to comparison view to see per-variant metrics side by side

## Filters

The filter bar sticks to the top of the page as you scroll, so your selections stay visible and editable while you review charts across all sections.

All sections share a common filter bar:

| Filter             | Options                                                                                                                                                                                     |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Date range**     | Last 7 days, Last 14 days, Last 30 days, All time, or custom                                                                                                                                |
| **Agent**          | Filter by a specific agent. Selecting a Chat agent narrows the Unique Visitors count to traffic attributed to that agent. Selecting a Phone or Email agent does not filter page visit data. |
| **Chat interface** | Navigator, Smartbar, Fullscreen (multi-select)                                                                                                                                              |
| **Email status**   | Known email, Unknown email                                                                                                                                                                  |
| **Country**        | Searchable country list (multi-select)                                                                                                                                                      |

Click **Export as CSV** to download the current view's data.

## Drilling Down to Leads

Most charts support drill-down. Hover over a chart segment and click **View conversations** to open the Leads page pre-filtered to the leads in that segment. This makes it easy to go from a metric to the actual conversations behind it.

## Unique visitors

The conversion funnel in the Chat section starts with **unique visitors** — the count of distinct people who visited pages where Spara is active during the selected date range.

### How uniqueness is determined

Spara assigns each visitor a randomly generated **prelead UUID** the first time they visit a page with the Spara widget. This UUID is stored in the visitor's browser (via localStorage) and persists across page loads and return visits. Each distinct prelead UUID counts as one unique visitor.

A visitor is counted once per date range regardless of how many pages they visit or how many times they return. If a visitor clears their browser data or uses a different browser/device, they are counted as a new unique visitor.

### Caveats

* **Bot traffic is excluded** where possible, but some automated visitors may still be counted
* **Incognito/private browsing** generates a new UUID each session, so the same person may be counted multiple times
* **Country filter** — Unique visitors can be filtered by country when the data source supports it

For technical details on how Spara tracks visitors and what data is stored in the browser, see [Developer: iFrame & Cookies](https://docs.spara.com/developers/installation/iframe-and-cookies).

## FAQ

### How are "leads engaged" counted?

A lead counts as engaged if they sent at least one message or scheduled a meeting. Browsing-only visitors are not included.

### Can I see which questions my leads ask most?

Yes. The Recent Questions panels in the Chat and Phone sections show all questions asked, organized by category (Value Prop, Product, Sales & Process, Competitive, Sensitive, Misc). Use the search bar to find specific topics.

### How do custom field charts work?

When your agents are configured to gather specific data (e.g., "What's your budget?"), Spara automatically creates analytics charts for those fields. The charts appear in the Chat section alongside the standard metrics.

### What does "lead messages per call" measure?

It counts messages sent by the lead during phone calls — not Spara's messages. The total gives you raw volume; the per-call average tells you how engaged leads are during a typical call. A higher average generally indicates leads are asking more questions and exploring the conversation rather than dropping off quickly.

### How does phone comparison mode work?

When a Phone A/B test is running, a **Comparison** toggle appears in the Phone section header. Switch it on to split every phone metric by variant so you can see how each version performs side by side. The toggle only appears when an active A/B test exists for a phone agent.


# Ask Spara

Ask Spara is the AI assistant built into the platform — ask questions, build and change agents, edit your data model, and get analytics answers from one chat.

**Ask Spara** is the AI assistant built into the Spara platform. It's one chat that follows you across every page: ask it how something works, have it build or change an agent for you, edit the data you track, or get an answer straight from your analytics — without leaving the page you're on.

Instead of a separate helper on each page, Ask Spara is a single assistant that carries context from one task to the next. You can describe what you want in plain language, and it does the work or walks you through it.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-8a868feb02df0db2d758af6318c54e675dc8842d%2FAsk%20Spara%20Rail.png?alt=media" alt=""><figcaption><p>Ask Spara open in the side rail, ready to answer a question or take on a task.</p></figcaption></figure>

## Where to find it

Ask Spara is available from anywhere in the platform in two forms:

* **Side rail** — a compact panel that slides in alongside whatever page you're on, so you can ask a question without losing your place.
* **Fullscreen** — expand the rail to a full [**Ask Spara**](https://app.spara.co/ask-spara-ai) page when you want more room, a wider view of a change, or to review past conversations in the sidebar.

You can also ask questions from Slack by messaging the Spara app or @-mentioning it in a channel. In Slack, Ask Spara answers questions but doesn't make changes. See [Slack](/integrations/communications-integrations/slack).

The suggestions in the composer are aware of the page you're on — open it from Analytics and it suggests analytics questions; open it from Workflows and it suggests workflow tasks.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-8ecd8449e531623178bb69828f4cae0853903355%2FAsk%20Spara%20Fullscreen.png?alt=media" alt=""><figcaption><p>The fullscreen view, with past conversations listed in the left sidebar.</p></figcaption></figure>

## What you can do

### Answer product and how-to questions

Ask Spara answers questions about how to use the platform, grounded in Spara's documentation, right inside the chat. It's the fastest way to learn how a feature works or find the right setting without leaving what you're doing.

### Build a new agent

Describe the agent you want and Ask Spara builds it with you. It creates a new channel from the conversation, takes you to its configuration, and keeps refining as you give feedback. Ask Spara can build across every channel — [Chat](/build/channels/chat), [Email](/build/channels/email), [SMS](/build/channels/sms), [Phone](/build/channels/phone), and [Product Demo](/build/channels/product-demo) — as well as [Workflows](/build/workflows).

For a step-by-step walkthrough of the whole agent, see [Agents](/build/agents).

{% hint style="info" %}
Building agents requires the **Agent edit** permission. Admins have this by default; other roles can be granted it by an admin under [User Management](/platform/settings/user-management).
{% endhint %}

### Change an existing agent

Ask Spara edits agents you've already built. Tell it what to change on a channel's prompt or configuration, and it proposes the edit as an **edit card** — a diff-style preview of exactly what will change, with a conflict check against your current setup. Click **Apply** to accept it. Changes save to your draft; nothing goes live until you publish. This works across Chat, Email, SMS, Phone, and Product Demo channels, as well as Workflows.

{% hint style="info" %}
Ask Spara is also embedded directly in the channel editor as a right-hand panel. See [Configuring Channels](/build/channels/configuring) for how it works while you're editing a single channel.
{% endhint %}

### Edit your data model

Ask Spara can add, rename, or adjust the [Data Model](/build/data-model) Spara tracks, and change which agents set or see each one, straight from the chat. This changes what data Spara collects — not just the agents that use it — so you can evolve your data model without opening the editor yourself.

### Answer analytics questions

Ask questions about your performance and Ask Spara answers them from your [Analytics](/pipeline/analytics). Because these answers map to the same metrics shown on the Analytics page, what Ask Spara tells you always matches what you see there. Each account only ever sees its own data.

### Filter your leads

Describe the leads you want to see, such as "Show me leads who submitted a webform," and Ask Spara filters the [Leads](/pipeline/leads) table for you. It uses the same filters you can set by hand, including your data model fields, and tells you about any part of the request it could not apply. See [Leads](/pipeline/leads#filter-with-ask-spara).

### Brand your chat widget

Give Ask Spara your brand colors — hex codes, or just a description of your site — and it turns them into a full chat widget theme: the accent, message bubbles, links, launcher button, and more. It proposes the palette first and applies it only after you say yes, then links you to the [Chat Theme](/build/channels/chat/chat-theme) page to preview it beside your site. Because a theme change is live on your website as soon as it's saved, Ask Spara always checks with you before applying one. Visitors may see the previous colors for up to about five minutes while the cached copy of your widget settings expires; there is nothing to publish or purge. Background images and avatars are still uploaded on the Theme page.

{% hint style="info" %}
Changing the theme requires the **Agent edit** permission, the same as the Theme page itself.
{% endhint %}

### Navigate the platform

Ask Spara points you to the right page and can take you there directly, so you spend less time hunting through the platform for the setting or view you need.

## How it works

A few things make Ask Spara feel like one continuous assistant rather than a series of one-off prompts:

* **Context awareness** — it knows what page you're on and what you've built, and carries that context across tasks within the same conversation.
* **Conversation history** — your chats are saved, so you can leave and pick a conversation back up later from the sidebar.
* **Upload a file** — attach a document or image to build or edit from it. Supported formats include PDF, Word (.docx), images (PNG, JPG, etc.), and most other file types up to 5 MB. For example, paste in a sales playbook to turn it into an agent.
* **In-chat controls** — Ask Spara uses inline controls like single- and multi-select questions, quick replies, and instruction-edit cards, so you can steer it with a click instead of typing everything out.
* **Live progress** — while it works, Ask Spara shows what it's doing and condenses the intermediate steps, so you can follow along.
* **Feedback** — give a thumbs up or down to help improve answers over time.
* **Share a conversation** — click the link icon in the side rail to copy a share link. Anyone in your organization who opens it lands on the same conversation, read-only, with the thread open.

## FAQ

### Does Ask Spara change anything without my approval?

No. When Ask Spara proposes a change to an agent, it shows an edit card you have to **Apply**, and applied changes save to your draft. Nothing affects live behavior until you publish the channel or workflow yourself. The one setting without a draft is the chat widget theme: it goes live as soon as it's saved, so Ask Spara proposes the palette and applies it only after you confirm in the chat.

### Can other accounts see my data through Ask Spara?

No. Ask Spara only ever works with your own account's data. Analytics answers are scoped to your account and match what appears on your Analytics page.

### Is Ask Spara the same as the assistant in the channel editor?

They're the same assistant in different places. The in-editor panel is focused on the single channel you're editing; the platform-wide Ask Spara carries context across pages and can build and change agents, edit your data model, and answer analytics questions. See [Configuring Channels](/build/channels/configuring).

### Are my Ask Spara conversations saved?

Yes. Conversations in the rail and fullscreen views are saved to your history, so you can resume them later. You can also start a new chat at any time with **New chat**.

### Is there a limit on how much I can paste into one message?

A single message can be up to 50,000 characters, enough for a long transcript or document. A counter appears as you approach the limit, and **Send** is disabled until you trim the message below it.

### Can I share an Ask Spara conversation with a teammate?

Yes. Click the link icon in the side rail to copy a share link. Teammates in your organization who open it can read the conversation thread. Share links are read-only — the recipient cannot continue the conversation or make changes.


# Todos

How Spara surfaces action items so your setup stays healthy and no leads slip.

**Todos** are action items Spara surfaces when it spots something in your setup that needs attention: a channel that isn't published, a disconnected CRM, or an integration that would improve your results. Instead of hunting for problems yourself, you get a prioritized list of exactly what to fix and where to fix it, so your agents keep converting leads without gaps.

Todos are generated automatically. Spara re-checks your account every hour — and again shortly after you change a related setting — opens a todo when it detects an issue, and closes it on its own once the issue is resolved.

You'll always find Todos in the top-right navigation bar, on every page. The button carries a count bubble showing how many todos are open. Click it to open the **Todos tray**, where open todos are grouped under the agent they relate to, and completed or dismissed todos are tucked into collapsed sections at the bottom.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-d9402f19a059c1dbe8202b9078d39c731082f43b%2FTodos%20Tray.png?alt=media" alt=""><figcaption><p>The Todos tray, grouped by area and sorted by priority</p></figcaption></figure>

## How to use Todos

Every todo has a priority that tells you how urgently it needs attention:

| Priority        | Meaning                                                                                                |
| --------------- | ------------------------------------------------------------------------------------------------------ |
| **Urgent**      | Something is actively broken or blocking leads. Fix it right away (e.g. a CRM that just disconnected). |
| **Required**    | Must be completed for your setup to work as intended, but nothing is actively broken.                  |
| **Recommended** | Optional improvements. Complete them if they fit your setup, or dismiss the ones that don't.           |

Urgent todos always sort to the top, followed by Required, then Recommended. A todo with a past-due date is nudged ahead of its tier so time-sensitive work stays visible.

Open any todo to see its details and take action. Each todo includes a short description of what's needed and why it matters, and links to the exact page where you can act on it.

**Mark as done.** Open a todo and click **Mark completed**. Completing is verified: Spara re-checks the todo's condition first, and if the issue is still there, the todo stays open and shows you what Spara found. Once a todo is completed, it is never reopened.

**Dismiss.** **Recommended** todos can be dismissed if they aren't relevant to your setup: open the todo and click **Dismiss**. Dismissed todos move to the collapsed **Dismissed** section at the bottom of the tray, where you can bring them back with **Undismiss**. Only Recommended todos can be dismissed; Urgent and Required todos represent work that has to be done, so they can't be waved off.

**Assign to a teammate.** Todos can be assigned to any member of your team. Open the todo and use the **Assigned to** field to pick a teammate. In the tray header, use the **Assigned to** filter to focus on todos owned by a specific person, or just the ones assigned to you. Add teammates first under [User Management](/platform/settings/user-management).

**Solve with Ask Spara.** Click **Solve with Ask Spara** to hand a todo directly to [Ask Spara](/platform/ask-spara), Spara's built-in AI assistant. It opens with full context about the todo and can walk you through resolving it, or take action on your behalf for things like configuring a channel. You can also just ask it what needs attention: Ask Spara can read your todo list, and on request dismiss a Recommended todo that doesn't apply or mark one done (completion is still verified).

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-0326d6803b84a71eec7a91806d2b635e045dff32%2FTodo%20Solve%20With%20Ask%20Spara.png?alt=media" alt=""><figcaption><p>A todo open with Ask Spara helping to resolve it</p></figcaption></figure>

**Share a todo.** Click the link icon in the todo's detail header to copy a direct link. Anyone on your team can open that link to jump straight to the same todo.

**Todos close on their own.** Todos created by Spara's hourly check close automatically once the underlying issue is resolved. For example, reconnecting a disconnected CRM closes the **Urgent** "CRM disconnected" todo on the next check, no manual step needed. Todos you've marked **Done** or **Dismissed** are never reopened automatically; if the same issue happens again later, Spara opens a fresh todo rather than reviving the one you closed.

## All todos

The table below is the complete list of todos Spara can open, with the exact condition that triggers each one.

Most todos appear at most once per account. Todos tagged *(per channel)* or *(per inbox)* open one card per affected channel or inbox, so several can be open at the same time.

<table data-full-width="true"><thead><tr><th>Todo</th><th>Description</th><th>Detection condition</th><th>Area</th><th>Priority</th></tr></thead><tbody><tr><td><strong>Add a human transfer option to voice calls</strong> <em>(per channel)</em></td><td>Callers who ask for a person hit a dead end. Add a transfer tool with a destination number.</td><td>A published phone channel has no transfer tool.</td><td>Agents</td><td>Recommended</td></tr><tr><td><strong>Add channel instructions</strong> <em>(per channel)</em></td><td>A channel on defaults speaks in a generic voice and doesn't know how to qualify your prospects. Add your own instructions and opening message.</td><td>A published channel's instructions are empty or unchanged from the Spara defaults (for chat, the opening message is also unedited).</td><td>Agents</td><td>Required</td></tr><tr><td><strong>Agent not gathering fields</strong> <em>(per channel)</em></td><td>Conversations there won't capture any lead data. Turn the channel on for the fields it should collect on the Data Model page.</td><td>A published channel is not set to gather any fields in the Data Model.</td><td>Agents</td><td>Urgent</td></tr><tr><td><strong>Assign an inbox to each email channel</strong> <em>(per channel)</em></td><td>Without an assigned inbox a channel can't send anything, even if an inbox is connected at the account level.</td><td>A published email channel has no inbox assigned.</td><td>Agents</td><td>Required</td></tr><tr><td><strong>Create a channel</strong></td><td>Prospects have no way to reach an agent. Create a channel, like chat, voice, or email, to get started.</td><td>No channels exist.</td><td>Agents</td><td>Required</td></tr><tr><td><strong>Create a workflow</strong></td><td>Your agents work without them, but we recommend one so follow-up happens automatically, like notifying your team about a hot lead or syncing it to your CRM.</td><td>No workflows exist.</td><td>Agents</td><td>Recommended</td></tr><tr><td><strong>Publish a channel</strong></td><td>An unpublished channel isn't live. Publish it to put it in front of your prospects.</td><td>At least one channel has been set up AND no channel is published.</td><td>Agents</td><td>Required</td></tr><tr><td><strong>Publish a workflow</strong></td><td>An unpublished workflow isn't running. We recommend publishing it so the follow-up actions it automates actually happen.</td><td>At least one workflow exists AND no workflow is published.</td><td>Agents</td><td>Recommended</td></tr><tr><td><strong>Configure CRM field mappings</strong></td><td>Until fields are mapped, the data Spara captures won't sync into the right CRM fields.</td><td>A CRM is connected AND it has no field mappings.</td><td>Integrations</td><td>Recommended</td></tr><tr><td><strong>Confirm rep routing on calendar</strong></td><td>Meetings booked from a conversation have nowhere to land. Map at least one rep or booking link so prospects reach a real calendar.</td><td>Calendly or Cal.com is connected AND no rep or booking link is mapped on any calendar provider.</td><td>Integrations</td><td>Recommended</td></tr><tr><td><strong>Connect a calendar</strong></td><td>Your agents can't book meetings with prospects. Connect a provider, or add a booking link, so conversations can end in a scheduled meeting.</td><td>No calendar provider (Calendly, Cal.com, HubSpot Meetings, or ChiliPiper) is connected AND no booking-link calendar has been added AND no booking link appears in a chat agent's instructions.</td><td>Integrations</td><td>Recommended</td></tr><tr><td><strong>Connect a CRM</strong></td><td>The leads Spara captures aren't syncing anywhere. Connect one to keep your pipeline up to date automatically.</td><td>No CRM (Salesforce, HubSpot, or Marketo) is connected AND no webhook endpoint is configured AND at least one channel is published.</td><td>Integrations</td><td>Required</td></tr><tr><td><strong>Connect a notification integration</strong></td><td>Your team isn't getting real-time alerts when Spara captures new leads, emails, or scheduled calls. Connect one to get notified as they happen.</td><td>Slack has never been connected AND Microsoft Teams has never been connected AND Webex is not connected.</td><td>Integrations</td><td>Recommended</td></tr><tr><td><strong>Connect an email inbox</strong></td><td>The agent has nothing to send from. Connect at least one warmed inbox. One is required, two are recommended.</td><td>A published email channel exists AND the account has no active email inbox connection.</td><td>Integrations</td><td>Required</td></tr><tr><td><strong>Connect Google Analytics</strong></td><td>Spara engagement and conversion events aren't reaching your GA4 property. Connect it to see Spara activity in your analytics and attribution.</td><td>Google Analytics (GA4) is not connected.</td><td>Integrations</td><td>Recommended</td></tr><tr><td><strong>Cal.com disconnected</strong></td><td>Your agents can no longer book meetings on this calendar. Reconnect the integration to restore scheduling.</td><td>A connected Cal.com account has rejected Spara's access, so bookings fail until an admin reauthorizes it. Reauthorizing keeps your configured calendars.</td><td>Integrations</td><td>Urgent</td></tr><tr><td><strong>CRM disconnected</strong></td><td>The leads Spara captures are no longer syncing. Reconnect the integration to restore the flow of data.</td><td>A connected CRM can no longer refresh its credentials. When a single CRM is affected, the todo names it (e.g. "Salesforce disconnected").</td><td>Integrations</td><td>Urgent</td></tr><tr><td><strong>Email inbox disconnected</strong> <em>(per inbox)</em></td><td>Spara can no longer receive or reply to email there. Reconnect the mailbox to restore email flow.</td><td>An inbox has been failing to sync for over an hour, or its provider revoked Spara's access. The todo names the inbox (e.g. "sales@yourco.com disconnected").</td><td>Integrations</td><td>Urgent</td></tr><tr><td><strong>Enable CRM sync</strong></td><td>No data is flowing between Spara and your CRM. Turn syncing on to keep your pipeline up to date.</td><td>A CRM is connected AND sync is turned off for every record type.</td><td>Integrations</td><td>Required</td></tr><tr><td><strong>Microsoft Teams disconnected</strong></td><td>Lead notifications and alerts have stopped flowing to your workspace. Reconnect Teams to restore them.</td><td>Microsoft Teams was connected AND the connection is no longer authorized.</td><td>Integrations</td><td>Urgent</td></tr><tr><td><strong>Webex disconnected</strong></td><td>Lead notifications and alerts have stopped flowing to your Webex rooms. Reconnect Webex to restore them.</td><td>Webex was connected AND (the connection is no longer authorized OR Webex has stopped accepting Spara's access, so it needs to be reauthorized).</td><td>Integrations</td><td>Urgent</td></tr><tr><td><strong>Slack disconnected</strong></td><td>Lead notifications and alerts have stopped flowing to your workspace. Reconnect Slack to restore them.</td><td>Slack was connected AND the connection is no longer authorized.</td><td>Integrations</td><td>Urgent</td></tr><tr><td><strong>Add websites</strong></td><td>Your agents have no website to learn from. Add yours so Spara can scan it and answer prospect questions with accurate, up-to-date knowledge.</td><td>No homepage URL is set AND no website domains have been added.</td><td>Knowledge</td><td>Required</td></tr><tr><td><strong>Sync documents</strong></td><td>Your agents can't answer with your organization's own content. Upload files or sync a source like Google Drive, Notion, or Confluence.</td><td>No documents have been uploaded AND no document source (Google Drive, Notion, Confluence, etc.) has been synced.</td><td>Knowledge</td><td>Recommended</td></tr><tr><td><strong>Website pages not scanned</strong></td><td>Until a scan completes, your agents have nothing to learn from the site. Check the domain on the Knowledge page and re-run the scan.</td><td>Websites were added more than an hour ago AND no page has been successfully scanned.</td><td>Knowledge</td><td>Required</td></tr><tr><td><strong>Add custom query parameters</strong></td><td>Add mappings for any custom query parameters in your website URLs so Spara can ingest them. Standard UTM parameters are already mapped by default.</td><td>A chat or product demo channel has been set up AND no custom query-parameter mappings exist beyond the standard UTM defaults.</td><td>Settings</td><td>Recommended</td></tr><tr><td><strong>Add team members</strong></td><td>Invite teammates so they can manage agents, review conversations, and follow up on leads with you.</td><td>The account has a single user.</td><td>Settings</td><td>Recommended</td></tr><tr><td><strong>Customize your theme</strong></td><td>Customize the theme, colors, and avatar so the agent looks like part of your brand instead of a Spara default.</td><td>A chat channel has been set up AND no logo has been uploaded AND the theme is unchanged from the default.</td><td>Settings</td><td>Recommended</td></tr><tr><td><strong>Install chat JavaScript</strong></td><td>No visitors are reaching your agent. Add the embed snippet to your website to put your agent in front of prospects.</td><td>A published chat channel exists AND no website visitor has ever started a chat.</td><td>Settings</td><td>Required</td></tr><tr><td><strong>Set Chat whitelist/blacklist</strong></td><td>Navigator is showing on every page Spara's Javascript snippet loads. Set a whitelist or blacklist to control which pages Navigator is shown to your website visitors.</td><td>Website visitors have started chats AND no page whitelist or blacklist has been configured.</td><td>Settings</td><td>Recommended</td></tr><tr><td><strong>Set up notifications</strong></td><td>Nobody on your team is alerted when leads come in. Enable Slack, Teams, or email notifications to stay on top of new activity.</td><td>No notification is enabled AND no published workflow contains a Notify step.</td><td>Settings</td><td>Recommended</td></tr><tr><td><strong>Submit Twilio registration</strong></td><td>Carrier review takes weeks, and registration can't be started from the platform. Reach out to your Spara CSM now to avoid delaying your go-live.</td><td>A phone or SMS channel has been set up AND no A2P brand registration or toll-free verification has been submitted.</td><td>Settings</td><td>Urgent</td></tr></tbody></table>

## FAQ

### Can I create my own todos?

Not currently. Todos are generated automatically by Spara based on your account's configuration and health.

### What happens if I ignore a todo?

Urgent and Required todos stay open until the underlying issue is fixed. Recommended todos can be left open or dismissed; they won't escalate.

### Will a todo reopen after I mark it done?

No. Spara verifies the fix before accepting a completion, so a completed todo never reopens. If the same issue happens again later, Spara opens a fresh todo rather than reviving the one you closed.

### Who can see and act on todos?

Todos are shared across your team. Any teammate can view the tray, complete or dismiss todos, and assign them to others.


# Settings

How to manage general, team, integrations, and technical settings.

Spara's settings page covers general, team, integrations, and technical settings.

* **General**
  * Company description: A brief description for how you want Spara to describe your business.
  * Sales avatar: The name, title, and profile image of how Spara is represented in all channels.
  * Cross Channel Opt-Outs: Whether a lead who asks to stop on one channel (email, text, or phone) is opted out of all three. On by default. When off, each opt-out covers only the channel it came from.
* **Team**
  * Invite and manage team members — see [User Management](/platform/settings/user-management)
* **Chat** — settings for your chat agents, organized into tabs:
  * **Deployment** — embed code and deployment configuration
  * **Themes** — visual styling for chat widgets
  * **Media** — images and media used in chat
  * **Admin** — response length and other admin-only settings (visible to admins only)
* **Email Configuration** — settings that apply across all email activity:
  * **Daily send limits** — cap on outgoing emails per day
  * **Email Tracking** — enable or disable open-tracking pixels and link rewriting on outgoing emails. See [Email](/build/channels/email) for details.
* **Product Demo** — settings for your Product Demo agents, including the Spara Scanner tab
* **Integrations**
  * Connect and configure Spara's native integrations to third party applications. See [Calendar Integrations](/integrations/calendar-integrations), [Communications Integrations](/integrations/communications-integrations), [CRM Integrations](/integrations/crm-integrations), and [Document Sync Integrations](/integrations/document-sync-integrations) for more details.


# User Management

How to invite team members and manage user permissions.

### User roles & permissions

Each Spara user has a role. By default, users join as the lowest-level role, Member. Sensitive actions are restricted to higher level roles.

User roles may be updated in [Settings > Team](https://app.spara.co/settings/team).

<table data-full-width="true"><thead><tr><th>Role</th><th>Agents</th><th>Workflows</th><th>Manual Mode</th><th>Settings > General</th><th>Settings > Team</th><th>Settings > Integrations &#x26; Webhook</th></tr></thead><tbody><tr><td>Member</td><td>View-only</td><td>View-only</td><td>Yes</td><td>Hidden</td><td>View-only</td><td>Hidden</td></tr><tr><td>Integrator</td><td>View-only</td><td>View-only</td><td>Yes</td><td>Full access</td><td>View-only</td><td>Full access</td></tr><tr><td>Contributor</td><td>Edit and test, no publish</td><td>Edit and test, no publish</td><td>Yes</td><td>Full access</td><td>View-only</td><td>View-only</td></tr><tr><td>Editor</td><td>Full access</td><td>Full access</td><td>Yes</td><td>Full access</td><td>View-only</td><td>View-only</td></tr><tr><td>Manager</td><td>Full access</td><td>Full access</td><td>Yes</td><td>Full access</td><td>Full access</td><td>Full access</td></tr></tbody></table>

**Agents and Workflows.** Roles with Full access can create, edit, test, publish, and delete agents and workflows. Contributors can edit and test drafts but cannot publish them: only Editors and Managers publish. View-only roles can open an agent or workflow to inspect its configuration but cannot make changes.

**Manual Mode.** Manual Mode lets any user take over a live conversation from the AI agent — they can pause Spara's responses and respond to the lead directly. Manual Mode is available to all roles regardless of permission level.

### Agent access

A role sets what a user can do across every Agent. When different teams own different Agents, a Manager can also **restrict** a single Agent so that only the people they list can change it.

* **Who can restrict an Agent**: Managers. Open the Agent on the [**Agents**](https://app.spara.co/agents) page, click **Manage**, and use the **Access** control to turn on the restriction and pick its members from your team.
* **What a restriction covers**: every channel and workflow inside the Agent. Its members and all Managers can change them; everyone else can open the Agent and its channels but not change them, and cannot add a channel or workflow to it or move one into or out of it.
* **A member's role still applies**: restricting an Agent never grants more than the member's role allows. A Contributor on the list can edit but not publish, and a Member on the list is still view-only.
* **Unrestricted Agents** work as before: anyone whose role has full access to Agents can edit them.

See [Restricting who can edit an Agent](https://docs.spara.com/agents#restricting-who-can-edit-an-agent) on the Agents page for how it looks in the product.

### Inviting team members

New users may be invited in [Settings > Team](https://app.spara.co/settings/team). Click the "Invite" button to enter their email address, assign them a role, and send them an invitation to the Spara platform.

### Authentication methods

Spara leverages [Clerk](https://clerk.com) for best-in-class user authentication & security.

By default, Spara customers' users may authenticate with email address and password. You may also elect to enable enterprise SSO (SAML, OAuth 2.0, and OpenID Connect) or social SSO for user authentication.

For enterprise SSO, Spara supports:

* Okta
* Microsoft Active Directory
* Google Workspace
* Sign in w/ Google
* Sign in w/ Github

Spara supports SSO/SAML authentication as well as email/password authentication. In the case of email/password authentication Spara requires the password to be:

* At least 8 characters long.
* At least one uppercase character
* At least one lowercase character
* At least one number
* Not be a known compromised password

{% hint style="info" %}
Contact your CSM to enable SSO for your organization.
{% endhint %}


# Notifications

Configure when and how your team gets notified about lead activity.

Spara can notify your team in real time when key lead events occur — like a new visitor being identified, lead information being enriched, or an email being sent. Notifications help your sales team respond faster and stay on top of pipeline activity without constantly monitoring the platform.

There are two ways to set up notifications about lead activity:

* [**Settings > Notifications**](https://app.spara.co/settings/notifications) — automatically notify your team when specific lead events happen across all leads. Best for organization-wide alerts that should fire every time an event occurs.
* **Workflow Notify step** — send targeted notifications as part of a [Workflows](/build/workflows), with custom messages and lead-specific data. Best for conditional alerts that should only fire when leads match specific criteria. See [Notify Step](/build/workflows/steps/notify) for setup instructions.

## Notification Settings

Navigate to [**Settings > Notifications**](https://app.spara.co/settings/notifications) to configure automatic notifications for your organization. Each notification event can be independently enabled and routed to one or more channels.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-99cee1ffda8716caa7f44cb3d2381e1cd23d7926%2FNotification%20Settings.png?alt=media" alt=""><figcaption><p>The Notifications tab in Settings, showing configurable events.</p></figcaption></figure>

### Notification events

Notifications share their event catalog with [Workflows](/build/workflows) triggers, so any event a workflow can start from can also send your team a notification. Events are grouped by where they come from:

**Lead activity events** fire based on lead identification and status changes:

| Event                               | What triggers it                                                   |
| ----------------------------------- | ------------------------------------------------------------------ |
| **Website visitor deanonymization** | A previously anonymous website visitor is identified by IP address |
| **Lead enrichment**                 | Spara learns new information about a lead through enrichment       |
| **Blocked**                         | A lead is blocked or marked as malicious                           |
| **Webform submitted**               | A lead submits a webform                                           |
| **Unsubscribed**                    | A lead unsubscribes from your emails                               |

**Email events** fire when emails are sent, received, or engaged with:

| Event                           | What triggers it                                              |
| ------------------------------- | ------------------------------------------------------------- |
| **Workflow email sent to lead** | A [Workflows](/build/workflows) step sends an email to a lead |
| **Reply email sent to lead**    | A reply email is sent to a lead                               |
| **Lead sent an email**          | A lead sends your team an email                               |
| **Email opened**                | A lead opens an email from Spara                              |
| **Email link clicked**          | A lead clicks a link in a Spara email                         |
| **Email reply received**        | A lead replies to an email                                    |

**Text events** fire when a lead texts your team:

| Event             | What triggers it            |
| ----------------- | --------------------------- |
| **Text received** | A lead sends a text message |

**Chat events** fire during live conversations with a lead:

| Event                         | What triggers it                                          |
| ----------------------------- | --------------------------------------------------------- |
| **Chat conversation started** | A lead starts a chat conversation                         |
| **Chat conversation ended**   | A lead finishes a chat conversation                       |
| **Email captured**            | A lead provides their email address                       |
| **Agent condition met**       | A lead meets a condition configured in an agent's trigger |

**Phone and product demo events** fire when calls complete:

| Event                    | What triggers it                             |
| ------------------------ | -------------------------------------------- |
| **Incoming call ended**  | An incoming phone call with a lead completes |
| **Outgoing call ended**  | An outgoing phone call to a lead completes   |
| **Navigator call ended** | A Spara Navigator web call completes         |
| **Product demo ended**   | A product demo session completes             |

**Meeting events** fire around scheduling:

| Event                 | What triggers it                                                                                                                                         |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Calendar shown**    | A lead is offered a booking calendar: in chat, on a phone call or product demo, or by opening a booking link from an email. Fires once per call or email |
| **Meeting scheduled** | A lead books a meeting                                                                                                                                   |

{% hint style="info" %}
Call-ended notifications fire only for calls that connect. Dials that go unanswered or fail do not notify your team. **Email opened** and **Email link clicked** require email tracking to be enabled for your account.
{% endhint %}

{% hint style="info" %}
For **Agent condition met**, the message content is defined by your agent's trigger configuration; here you only choose where to send it. If you previously subscribed to "A voice call has ended", your subscription was split into the per-call-type events above, based on the call types your account has had.
{% endhint %}

### Notification channels

Each event can be routed to one or more of these channels:

* **Email** — Send to a specific email address. When a sales rep is assigned to the lead, you can also enable **Notify sales rep** to send a copy to them automatically.
* **Slack** — Post to a specific Slack channel. Also supports **Notify sales rep** to DM the assigned rep.
* **Microsoft Teams** — Post to a specific Teams channel.
* **Webex** — Post to a specific Webex room.

Slack, Teams, and Webex must be connected under [**Settings > Integrations**](https://app.spara.co/settings/integrations) before they appear as notification options. See [Communications Integrations](/integrations/communications-integrations) for setup instructions.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-765aa022110509ea75b344f9f66ea477fca4d14b%2FIntegrations%20Page.png?alt=media" alt=""><figcaption><p>Connect Slack, Microsoft Teams, or Webex under Settings > Integrations to unlock messaging channels.</p></figcaption></figure>

### Enabling a notification

To enable a notification for an event:

1. Check the **Send to email address** box next to the event
2. Enter the email address that should receive the notification
3. Click **Save Changes**

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-522d5b8d7a9001b75e08186b85fc0951d633ef3c%2FNotification%20Email%20Enabled.png?alt=media" alt=""><figcaption><p>Enabling an email notification reveals the email address field.</p></figcaption></figure>

{% hint style="info" %}
If your organization has connected [Slack](/integrations/communications-integrations/slack), [Microsoft Teams](/integrations/communications-integrations/microsoft-teams), or [Webex](/integrations/communications-integrations/webex), additional channel options appear for each event. You can route the same event to multiple channels simultaneously.
{% endhint %}

## FAQ

### Do notification settings and workflow Notify steps overlap?

They serve different purposes. Notification settings send automatic alerts for every lead that triggers an event. Workflow Notify steps send alerts only for leads that enter a specific workflow and reach the Notify step. You can use both together.

### Can I notify the assigned sales rep?

Yes, for Email and Slack notification channels. Enable the **Notify sales rep** toggle next to the event. Spara looks up the rep's email from your connected CRM (e.g., Salesforce) and sends them a notification when their assigned lead triggers the event.

### What if I don't see Slack or Teams options?

You need to connect the integration first. Go to [**Settings > Integrations**](https://app.spara.co/settings/integrations) and authorize Slack, Microsoft Teams, or Webex. Once connected, those channels appear as options in both notification settings and the workflow Notify step.


# Voice

Account-wide voice settings shared across every agent, including pronunciations that control how words are spoken and recognized.

Voice settings apply across all your agents. Configure them at [**Settings > Voice**](https://app.spara.co/settings/voice).

## Pronunciations

On the [**Settings > Voice**](https://app.spara.co/settings/voice) tab, you can add custom pronunciations that apply to every Voice agent in your account. Each entry serves two purposes:

* **Controls how the agent speaks the word.** The pronunciation drives text-to-speech, so "SQL" → "sequel" or "kubectl" → "kube control" make the agent say specialty terms correctly.
* **Strengthens how the agent hears the word.** The source term is also added to the speech-to-text key term list, biasing recognition toward that word. This is especially helpful for specialty terms that sound like common English words. For example, mapping "Paychex" → "Paychecks" both makes the agent pronounce the product correctly and helps the model transcribe "Paychex" instead of "Paychecks" when a caller says it.

Add an entry for any product name, person name, acronym, or industry term that voice agents need to say or hear reliably. Pronunciations apply org-wide to every Voice agent. There is no per-agent override today.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-53b20ba3c8de5f9b2544f17b01c5350b303824cd%2FVoice%20Pronunciations.png?alt=media" alt=""><figcaption><p>The Pronunciations panel on Settings > Voice, showing example entries that apply to every Voice agent.</p></figcaption></figure>

{% hint style="info" %}
Use phonetic spelling: spell the word the way it should sound, and use spaces to separate syllables or letters (for example, "A P I" for the acronym "API").
{% endhint %}


# Calendar Integrations

How to connect your third party calendar tool to Spara.

Spara's AI can intelligently push leads to schedule a call with your sales team. To accomplish this, Spara supports integrations with most major third party calendar scheduling solutions.

{% hint style="info" %}
Spara strongly recommends Cal.com as a calendar provider.
{% endhint %}

Each agent type uses calendars differently:

* **Chat agents** render a calendar widget directly in the conversation for the lead to pick a time
* **Email agents** include links to your calendar booking page
* **Phone capabilities** handle booking entirely by conversation — Spara reads available slots aloud, the lead picks a time, and it books the meeting. See [Phone](/build/channels/phone) for details on the voice booking flow.

All Spara agents can route leads to specific calendars based on any information known about the lead.

Spara supports both round robin calendars and routing to specific sales reps' calendars (through Salesforce integration only). See [Salesforce](/integrations/crm-integrations/salesforce#owner-objects) documentation for more details.

Spara's integrations are sometimes limited by what each calendar's API makes available. In all cases, Spara is immediately alerted whenever a calendar event has been scheduled, meaning that Spara's behavior can react to this situation. After a call is scheduled, it is common to configure Spara to send a success message and then ask additional prequalification questions.

Please see our calendar integration guides, including installation instructions and calendar limitations, in the table below:

<table data-full-width="true"><thead><tr><th>Calendar</th><th>Spara can prepopulate...</th><th>Spara can read from submitted calendar...</th><th>Integration Notes</th></tr></thead><tbody><tr><td><a data-mention href="/integrations/calendar-integrations/cal.com">Cal.com</a></td><td><ul><li>Email</li><li>First name</li><li>Last name</li><li>Phone number</li><li>Company name</li></ul></td><td><ul><li>Email</li><li>First name</li><li>Last name</li><li>Phone number</li><li>Company name</li></ul></td><td>Cal.com is flexible and easy to integrate with.</td></tr><tr><td><a data-mention href="/integrations/calendar-integrations/calendly">Calendly</a></td><td><ul><li>Email</li><li>First name</li><li>Last name</li><li>Name</li></ul></td><td><em>None</em></td><td><p>Spara should capture email address before showing a Calendly calendar.</p><p>Spara will prepopulate the calendar form's email field with this info.</p></td></tr><tr><td><a data-mention href="/integrations/calendar-integrations/chili-piper-concierge">Chili Piper Concierge</a></td><td><ul><li>Email</li><li>First name</li><li>Last name</li><li>Company name</li><li>Company size</li></ul></td><td><em>None</em></td><td><p>Spara should capture email address before showing a Chili Piper calendar.</p><p>Spara will prepopulate the calendar form's email field with this info.</p></td></tr><tr><td><a data-mention href="/integrations/calendar-integrations/chilical">ChiliCal</a></td><td><ul><li>Email</li></ul></td><td><em>None</em></td><td>Spara should capture email address before showing a ChiliCal calendar. Spara will prepopulate ChiliCal's form email field with this info.</td></tr><tr><td><a data-mention href="/integrations/calendar-integrations/default">Default</a></td><td><ul><li>Email</li></ul></td><td><ul><li>Email</li></ul></td><td></td></tr><tr><td><a data-mention href="/integrations/calendar-integrations/hubspot-calendar">HubSpot (Calendar)</a></td><td><ul><li>Email</li><li>First name</li><li>Last name</li></ul></td><td><ul><li>Email</li><li>First name</li><li>Last name</li></ul></td><td>HubSpot is flexible and easy to integrate with.</td></tr><tr><td><a data-mention href="/integrations/calendar-integrations/revenuehero">RevenueHero</a></td><td><ul><li>Email</li><li>First name</li><li>Last name</li><li>Company</li><li>IP Country</li></ul></td><td><ul><li>Email</li><li>First name</li><li>Last name</li></ul></td><td></td></tr><tr><td><a data-mention href="/integrations/calendar-integrations/zoom-scheduler">Zoom Scheduler</a></td><td><em>None</em></td><td><ul><li>Email</li><li>First name</li><li>Last name</li><li>Phone number</li></ul></td><td>Spara will read email address and other fields after a meeting has been scheduled.</td></tr><tr><td><a data-mention href="/integrations/calendar-integrations/custom-calendar">Custom Calendar</a></td><td>Any fields (customizable)</td><td></td><td>Spara can detect a meeting scheduled only if the scheduler fires a success meeting booked event</td></tr></tbody></table>

## Voice agent calendar booking

Voice agents book meetings by conversation — the agent reads available slots aloud, the lead picks a time, and the agent books it directly. This is a different integration path than the calendar widgets above, which embed a scheduler for the lead to fill in. The table below covers which calendar providers Spara supports for voice scheduling today.

<table data-full-width="true"><thead><tr><th>Calendar</th><th>Voice scheduling</th><th>Connection</th></tr></thead><tbody><tr><td><a data-mention href="/integrations/calendar-integrations/cal.com">Cal.com</a></td><td>Available</td><td>OAuth</td></tr><tr><td><a data-mention href="/integrations/calendar-integrations/calendly">Calendly</a></td><td>Available</td><td>OAuth — connecting user should have an <strong>admin or owner role</strong> in your Calendly organization</td></tr><tr><td><a data-mention href="/integrations/calendar-integrations/hubspot-calendar">HubSpot (Calendar)</a></td><td>Available</td><td>OAuth — uses your existing HubSpot CRM connection</td></tr><tr><td><a data-mention href="/integrations/calendar-integrations/chili-piper-concierge">Chili Piper Concierge</a></td><td>Coming soon</td><td>Admin token — requires Chili Piper's <strong>Scheduling &#x26; Routing</strong> plan tier (or higher concierge tier)</td></tr><tr><td><a data-mention href="/integrations/calendar-integrations/chilical">ChiliCal</a></td><td>Not supported</td><td><em>—</em></td></tr><tr><td><a data-mention href="/integrations/calendar-integrations/revenuehero">RevenueHero</a></td><td>Not supported</td><td><em>—</em></td></tr><tr><td><a data-mention href="/integrations/calendar-integrations/zoom-scheduler">Zoom Scheduler</a></td><td>Not supported</td><td><em>—</em></td></tr><tr><td><a data-mention href="/integrations/calendar-integrations/default">Default</a></td><td>Coming soon</td><td><em>—</em></td></tr><tr><td><a data-mention href="/integrations/calendar-integrations/custom-calendar">Custom Calendar</a></td><td>Not supported</td><td><em>—</em></td></tr></tbody></table>

For details on the voice booking conversation flow, see [Phone](/build/channels/phone).


# Cal.com

How to integrate with Cal.com.

### Data flows

While Cal.com does not provide complete access to reading and writing data from scheduled events, it does currently provide better integration support than any other calendar provider in the market.

<table data-full-width="true"><thead><tr><th>Spara can prepopulate...</th><th>Spara can read from submitted calendar...</th><th>Integration Notes</th></tr></thead><tbody><tr><td><ul><li>Email</li><li>First name</li><li>Last name</li><li>Phone number</li><li>Company name</li></ul></td><td><ul><li>Email</li><li>First name</li><li>Last name</li><li>Phone number</li><li>Company name</li></ul></td><td><em>N/A</em></td></tr></tbody></table>

### Implementation

{% hint style="info" %}
How Spara's AI uses your calendar must be configured by Spara internally. Please contact your customer service representative to get started.
{% endhint %}

Cal.com calendars are embedded as an iFrame within Spara's interface. All Cal.com UX can be used by your lead in this format.

Spara requires a calendar URL in the form:

```yaml
https://cal.com/lori-byrne/30min
```

### Reconnecting

If Cal.com stops honoring Spara's access (for example after the authorizing user's password changes or the app's access is revoked in Cal.com), bookings fail until the connection is reauthorized. Spara flags this for you:

* The Integrations page shows Cal.com as **Reconnection required**.
* An **Urgent** "Cal.com disconnected" todo appears in your Todos.
* Voice agents tell callers they can't book right now and offer a follow-up instead of retrying.

To fix it, open **Settings → Integrations → Cal.com** and click **Reauthorize**. Your configured calendars are kept; you do not need to delete and recreate the connection.


# Calendly

How to integrate with Calendly.

### Data flows

Unfortunately, Calendly only provides partial support for data prepopulating their calendar form, and no support for reading information from their calendars. Because of this, we do not recommend Calendly as a calendar solution.

<table data-full-width="true"><thead><tr><th>Spara can prepopulate...</th><th>Spara can read from submitted calendar...</th><th>Integration Notes</th></tr></thead><tbody><tr><td><ul><li>Email</li><li>First name</li><li>Last name</li><li>Name</li></ul></td><td><em>None</em></td><td><p>Spara should capture email address before showing a Calendly calendar.</p><p>Spara will prepopulate Calendly's form email field with this info.</p></td></tr></tbody></table>

### Implementation

{% hint style="info" %}
How Spara's AI uses your Calendly calendar must be configured by Spara internally. Please contact your customer service representative to get started.
{% endhint %}

Calendly calendars are embedded as an iFrame within Spara's interface. All Calendly UX can be used by your lead in this format.

Spara requires a Calendly calendar URL in the form:

`https://calendly.com/your-name/calendar-name`

To find this URL, log into the Calendly website. Click the “Share” button for a specific calendar to find this URL.

### Multiple sales reps with separate calendars

If you have multiple sales reps and want bookings to land on the correct rep's calendar, you can pass the specific Calendly URL on a **per-lead basis** as a field. The Voice agent uses the field-supplied URL when booking, so the meeting lands on the assigned rep's calendar.

This requires you to **assign the rep (and their calendar URL) on each lead ahead of time** — for example, via your CRM sync or when creating the lead through the API. Spara does not currently support round-robin assignment or automatically choosing a rep on Spara's side.

{% hint style="warning" %}
This pattern requires configuration work on Spara's side to fully set up. Contact your Spara representative before relying on it for a live use case.
{% endhint %}

{% hint style="info" %}
This pattern works well for high-touch outgoing flows where leads are pre-assigned to a rep before the call. For inbound flows where any rep is acceptable, a single shared calendar is usually simpler.
{% endhint %}


# Default

How to integrate with Default calendars.

Default is a scheduling platform that provides embeddable booking queues. Spara can embed Default calendars directly within the chat interface, allowing leads to schedule meetings without leaving the conversation.

{% hint style="warning" %}
Default provides limited API support for data prepopulation and reading. Because of this, Spara does not recommend Default as a primary calendar solution. Consider [Cal.com](/integrations/calendar-integrations/cal.com) for the most complete integration.
{% endhint %}

## Data flows

<table data-full-width="true"><thead><tr><th>Spara can prepopulate...</th><th>Spara can read from submitted calendar...</th><th>Integration Notes</th></tr></thead><tbody><tr><td><ul><li>Email</li></ul></td><td><ul><li>Email</li></ul></td><td>Default only supports email prepopulation. Spara should capture the lead's email before showing the calendar.</td></tr></tbody></table>

## Setup

{% stepper %}
{% step %}

### Get your Default calendar URL

Log in to your Default account and find your scheduling queue URL. It follows this format:

```
https://scheduler.default.com/<team_id>/queue/<queue_id>
```

{% endstep %}

{% step %}

### Provide the URL to Spara

Contact your Spara account manager or CSM with your Default calendar URL. Spara will configure the integration on your behalf.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
Default calendar integration is configured by Spara internally. Please contact your customer service representative to get started.
{% endhint %}

## How it works

Default calendars are embedded as an iframe within Spara's chat interface. When your agent determines a lead is ready to schedule, it presents the Default booking widget. The lead can select a time and complete the booking without leaving the conversation.

Spara captures the lead's email address before showing the calendar and prepopulates it in the Default form to reduce friction.

## Default Forms SDK

The Forms SDK is Default's programmatic embed for triggering the scheduling drawer directly from your own website code, bypassing the native Default form. Most Spara customers use the Forms SDK approach because it gives Spara — and your existing site — full control over when the calendar drawer opens and what data is passed in.

**Why use the Forms SDK instead of the native Default form?**

* The Default form lives inside Default's hosted UI. With the Forms SDK, the form lives on your own page and you control the styling, validation, and submission flow.
* You can call the SDK from a CTA, after a custom qualification step, or from Spara's chat — instead of redirecting the lead off-page.
* It allows Spara and your own JavaScript to share the same booking surface, so the lead experiences a single seamless flow.

### What Spara needs from you

To wire up the Forms SDK on your site, share the following with your Spara CSM:

* **`form_id`** — the unique identifier for the Default form you want to trigger
* **`team_id`** — the Default team that owns the form
* **Submission script** — the snippet that calls Default's SDK to open the drawer (see Default's official guide: [Default Forms SDK](https://docs.default.com/articles/3276343596-forms-sdk?lang=en))

Spara will use these to configure the integration so the calendar drawer opens correctly from within the chat experience.

### What the drawer looks like

When the Forms SDK fires, Default opens a drawer over your page containing the booking flow. The lead picks a time and completes the booking without leaving your site. See Default's [Forms SDK documentation](https://docs.default.com/articles/3276343596-forms-sdk?lang=en) for live examples of the drawer in action.

## FAQ

### Why can Spara only prepopulate email?

Default's embed API currently supports limited field prepopulation. Unlike other calendar providers (such as Cal.com, which supports name, email, phone, and company), Default only accepts email as a prepopulated field.

### Does Spara know when a meeting is booked?

Yes. Spara detects when a calendar event has been scheduled through Default and can react accordingly — for example, by sending a confirmation message or progressing the lead through a workflow.


# ChiliCal

How Spara integrates with ChiliCal.

### Data flows

Unfortunately, ChiliCal only provides partial support for data prepopulating their calendar form, and no support for reading information from their calendars. Because of this, we do not recommend ChiliCal as a calendar solution.

<table data-full-width="true"><thead><tr><th>Spara can prepopulate...</th><th>Spara can read from submitted calendar...</th><th>Integration Notes</th></tr></thead><tbody><tr><td><ul><li>Email</li></ul></td><td><em>None</em></td><td><p>Spara should capture email address before showing a ChiliCal calendar.</p><p>Spara will prepopulate the calendar form's email field with this info.</p></td></tr></tbody></table>

### How to use Chili Piper with Spara

Spara's AI can intelligently push leads to schedule a call with your sales team.

For example, Spara may be tasked with ascertaining the number of employees at a lead's company. Once discovered, if the lead is at a company with >100 employees, Spara can prompt the lead to schedule a call. If the lead is at a company with <100 employees, Spara can instead prompt the leads towards a self-service sign up flow.

Spara can show a Chili Piper scheduler during as part of a conversation. This allows Spara to prequalify a lead before letting them schedule a meeting, or to determine which calendar link to use for each lead.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-45202325644fff4c3e6cf79d38970f24408ea911%2FSendoso%20-%20embedded%20calendar.png?alt=media" alt=""><figcaption></figcaption></figure>

### How to integrate Chili Piper Concierge with Spara

Provide your customer success representative with the url of your Chili Piper Concierge calendar widget. This will be embedded within Spara's interface.

You will also need to enable Chili Piper's JS API for inbound routing with Concierge. This enables Spara to load your Chili Piper concierge calendar as an embed. Make sure that "Third party form is Submitted" is selected as the trigger.

See [Chili Piper's documentation](https://help.chilipiper.com/hc/en-us/articles/32588330506643-Concierge-Snippet-and-JS-API-in-Demand-Conversion-Platform#01J5TW336Q1V1ZR5T6YD4DBB9B) for full instructions.

### Redirecting to a Spara webpage from Chili Piper Concierge

To redirect from a Chili Piper Concierge scheduled to Spara, you will need to set up Chili Piper to redirect to a URL containing form values in the redirect URL. This provides Spara with the information you lead just submitted to Chili Piper.

In the Redirect To settings, select "Enabled" for Include Form Values in Redirect URL - this ensures that Chili Piper includes lead data via query parameters for Spara to ingest. You can then map those query parameters inside the Spara Platform - see [Developer: Query Parameters](https://docs.spara.com/developers/spara-api/query-parameters) for more information.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-2ca3074e4da1cd8504fd8d31b466596b19fac884%2Fchili%20piper%20redirect.png?alt=media" alt=""><figcaption><p>How to include query parameters from your Chili Piper redirect</p></figcaption></figure>

### How to integrate Chili Piper (Legacy) with Spara

Provide your customer success representative with the full URL of your Chili Piper (Legacy) calendar widget. This will be embedded within Spara's interface. For example:

`https://yourdomain.chilipiper.com/book/me/firstname-lastname`

See [Chili Piper’s documentation](https://help.chilipiper.com/hc/en-us/articles/12601963874323-Embedding-A-Calendar-or-Booking-Link).


# Chili Piper Concierge

How Spara integrates with Chili Piper Concierge.

Spara supports two integration modes for Chili Piper Concierge: an **embedded widget** for Chat agents, and **conversational booking** for Voice agents.

***

## Chat agents: Embedded widget

{% hint style="warning" %}
Chili Piper Concierge's embedded widget provides only partial support for data pre-population, and no support for reading calendar data back into Spara. For Chat agents we generally recommend [Cal.com](/integrations/calendar-integrations/cal.com), [Calendly](/integrations/calendar-integrations/calendly), or [ChiliCal](/integrations/calendar-integrations/chilical), which offer fuller data round-trips.
{% endhint %}

### Data flows

<table data-full-width="true"><thead><tr><th>Spara can prepopulate...</th><th>Spara can read from submitted calendar...</th><th>Integration Notes</th></tr></thead><tbody><tr><td><ul><li>Email</li><li>First name</li><li>Last name</li><li>Company name</li><li>Company size</li></ul></td><td><ul><li>AssigneeID</li></ul></td><td><p>Spara should capture email address before showing a Chili Piper Concierge calendar.</p><p>Spara will prepopulate the calendar form's email field with this info.</p></td></tr></tbody></table>

### How to use Chili Piper with Spara

Spara's AI can intelligently push leads to schedule a call with your sales team.

For example, Spara may be tasked with ascertaining the number of employees at a lead's company. Once discovered, if the lead is at a company with >100 employees, Spara can prompt the lead to schedule a call. If the lead is at a company with <100 employees, Spara can instead prompt the leads towards a self-service sign up flow.

Spara can show a Chili Piper scheduler as part of a conversation. This allows Spara to prequalify a lead before letting them schedule a meeting, or to determine which calendar link to use for each lead.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-45202325644fff4c3e6cf79d38970f24408ea911%2FSendoso%20-%20embedded%20calendar.png?alt=media" alt=""><figcaption></figcaption></figure>

### How to integrate Chili Piper Concierge with Spara

Provide your customer success representative with the url of your Chili Piper Concierge calendar. This will be embedded within Spara's interface.

You will also need to enable Chili Piper's JS API for inbound routing with Concierge. This enables Spara to load your Chili Piper concierge calendar as an embed. Make sure that "Third party form is Submitted" is selected as the trigger.

See [Chili Piper's documentation](https://help.chilipiper.com/hc/en-us/articles/32588330506643-Concierge-Snippet-and-JS-API-in-Demand-Conversion-Platform#01J5TW336Q1V1ZR5T6YD4DBB9B) for full instructions.

### Redirecting to a Spara webpage from Chili Piper Concierge

To redirect from a Chili Piper Concierge scheduled to Spara, you will need to set up Chili Piper to redirect to a URL containing form values in the redirect URL. This provides Spara with the information you lead just submitted to Chili Piper.

In the Redirect To settings, select "Enabled" for Include Form Values in Redirect URL - this ensures that Chili Piper includes lead data via query parameters for Spara to ingest. You can then map those query parameters inside the Spara Platform - see [Developer: Query Parameters](https://docs.spara.com/developers/spara-api/query-parameters) for more information.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-2ca3074e4da1cd8504fd8d31b466596b19fac884%2Fchili%20piper%20redirect.png?alt=media" alt=""><figcaption><p>How to include query parameters from your Chili Piper redirect</p></figcaption></figure>

***

## Voice agents: Conversational booking

Voice agents can book meetings through Chili Piper Concierge conversationally — the same flow as Calendly or Cal.com. The agent checks availability, reads open slots aloud, and confirms the booking through natural conversation. No embedded widget or browser session is required.

### How it works

1. The Voice agent checks your Chili Piper router for available slots.
2. The agent reads available times aloud (e.g., "I have Tuesday at 2pm or Wednesday at 10am").
3. The lead picks a time conversationally.
4. The agent confirms contact details and books the meeting directly via the Concierge API.

### Setup

On the Voice agent's **Abilities** tab, select **Book meeting** and choose **Chili Piper Concierge** as the calendar provider. You will need:

* **Admin token** — A Chili Piper admin API token for your account.
* **Assignee slug** — The slug of the assignee or team in Chili Piper (e.g. `deputy`).
* **Router slug** — The slug of the routing rule to use for availability and booking.
* **Trigger** — How bookings are submitted. Select **Router Link** for voice-initiated bookings.


# HubSpot (Calendar)

How to integrate with HubSpot calendars.

### Data flows

While HubSpot allows limited pre-population of meeting form fields (email, first name, and last name), it does not provide access to read or write calendar events outside of its own interface, and therefore offers more restricted integration support compared to specialized scheduling providers.

<table data-full-width="true"><thead><tr><th>Spara can prepopulate...</th><th>Spara can read from submitted calendar...</th><th>Integration Notes</th></tr></thead><tbody><tr><td><ul><li>Email</li><li>First name</li><li>Last name</li></ul></td><td><ul><li>Email</li><li>First name</li><li>Last name</li></ul></td><td>Spara will read email address and other fields after a meeting has been scheduled.</td></tr></tbody></table>

### Implementation

{% hint style="info" %}
How Spara's AI uses your HubSpot calendar must be configured by Spara internally. Please contact your customer service representative to get started.
{% endhint %}

HubSpot calendars are embedded as an iFrame within Spara's interface. All HubSpot UX can be used by your lead in this format.

Spara requires a HubSpot calendar URL , for example:

```yaml
https://meetings-na2.hubspot.com/<name>
```


# RevenueHero

How to integrate with RevenueHero calendars.

### Data flows

The following are the fields Spara can pre-populate and read from RevenueHero calendar

<table data-full-width="true"><thead><tr><th>Spara can prepopulate...</th><th>Spara can read from submitted calendar...</th><th>Integration Notes</th></tr></thead><tbody><tr><td><ul><li>Email</li><li>First name</li><li>Last name</li><li>Company</li><li>IP Country</li></ul></td><td><ul><li>Email</li><li>First name</li><li>Last name</li></ul></td><td>Spara will read email address and other fields after a meeting has been scheduled.</td></tr></tbody></table>

### Implementation

{% hint style="info" %}
How Spara's AI uses your RevenueHero calendar must be configured by Spara internally. Please contact your customer service representative to get started.
{% endhint %}

RevenueHero calendars are embedded as an iFrame within Spara's interface. All RevenueHero UX can be used by your lead in this format.

Spara requires a RevenueHero calendar URL , for example:

```yaml
https://meet.<yourdomain>.com/inbound/product-website-spara-chatbot
```


# Zoom Scheduler

How to integrate with Zoom Scheduler calendars.

### Data flows

Unfortunately, Zoom Scheduler only provides partial support for data prepopulating their calendar form, and no support for reading information from their calendars. Because of this, we do not recommend Zoom Scheduler as a calendar solution.

<table data-full-width="true"><thead><tr><th>Spara can prepopulate...</th><th>Spara can read from submitted calendar...</th><th>Integration Notes</th></tr></thead><tbody><tr><td><em>None</em></td><td><ul><li>Email</li><li>First name</li><li>Last name</li><li>Phone number</li></ul></td><td>Spara will read email address and other fields after a meeting has been scheduled.</td></tr></tbody></table>

### Implementation

{% hint style="info" %}
How Spara's AI uses your Zoom Scheduler calendar must be configured by Spara internally. Please contact your customer service representative to get started.
{% endhint %}

Zoom Scheduler calendars are embedded as an iFrame within Spara's interface. All Zoom Scheduler UX can be used by your lead in this format.

Spara requires a Zoom Scheduler calendar URL , for example:

```yaml
https://scheduler.zoom.com/round-robin-345
```


# Custom Calendar

How to integrate with a custom calendar routing page.

### Data flows

Custom calendar allows Spara to support advanced routing setups where a form platform (e.g., HubSpot or Marketo) triggers a separate scheduling platform (e.g., Chili Piper, Default, etc.), or where a scheduling tool can be directly embedded. The scheduler must fire a postMessage event upon booking, so Spara can track call scheduling within the platform.

> Note: This solution is intended for cases where a native Spara calendar integration alone will not work. Because this setup is fully configurable, capabilities depend on the scheduler being used.

<table data-full-width="true"><thead><tr><th>Spara can prepopulate...</th><th>Spara can read from submitted calendar...</th><th>Integration Notes</th></tr></thead><tbody><tr><td>Any fields - customizable</td><td></td><td>Spara can detect a meeting scheduled only if the scheduler fires a success meeting booked event</td></tr></tbody></table>

### Implementation

{% hint style="info" %}
Spara builds your custom calendar so it can be configured within Spara agents. Please contact your customer success manager to get started.
{% endhint %}

#### How to use Custom Calendar in Spara

Spara hosts a standalone routing page that:

* Embeds your form
* Triggers your scheduling tool after submission
* Detects when a meeting is successfully booked

#### What to provide to Spara

To configure a custom calendar, provide your Customer Success representative with:

#### Form Details

* Form platform name
* Embed script
* Portal ID / Form ID (if applicable)
* Region (if applicable)

#### Scheduling Platform Details

* Scheduler name
* Embed script
* Any routing parameters required
* Documentation for the confirmed booking event (if available)

Spara will create a custom calendar HTML page that looks like below:

```yaml
https://spara-public.s3.amazonaws.com/custom_calendar.html
```


# Communications Integrations

How to configure Spara to send notifications to your communication platform.

Spara integrates with messaging platforms to send real-time notifications about lead activity. Connect your team's preferred platform under [**Settings > Integrations**](https://app.spara.co/settings/integrations), then configure which events trigger notifications in [**Settings > Notifications**](https://app.spara.co/settings/notifications) or via [Notify Step](/build/workflows/steps/notify).

| Platform                                                                     | Notification channels     | Notify sales rep    |
| ---------------------------------------------------------------------------- | ------------------------- | ------------------- |
| [Slack](/integrations/communications-integrations/slack)                     | Post to any Slack channel | DM the assigned rep |
| [Microsoft Teams](/integrations/communications-integrations/microsoft-teams) | Post to any Teams channel | *Not supported*     |
| [Webex](/integrations/communications-integrations/webex)                     | Post to any Webex room    | *Not supported*     |

## What Spara can and cannot access

Spara's communications integrations are designed for one purpose: posting outgoing notifications into channels you've connected. Spara does not read your team's conversations, store message history, or sync data out of your messaging platform back into Spara.

Because Slack and Microsoft Teams grant access through their standard OAuth scopes, the consent screen during install may list broad permissions (for example, read access to channels and messages) so that the underlying functionality — looking up a channel by name to post into it, surfacing the channel picker in Spara's settings — works correctly. Spara does not exercise those read permissions to ingest your messages, and no channel or message content from your Slack or Teams workspace is stored on Spara's side.

In practice, the only data flowing between Spara and your messaging platform is the notification content Spara generates (lead alerts, workflow updates, sales rep DMs) being posted into the specific channels you've selected.

If your security team needs a written attestation of this, contact your Spara customer success representative.


# Slack

Ask Spara questions from Slack and get Spara notifications in your channels.

Connecting Slack brings Spara to where your team already works. Anyone on your team can ask [Ask Spara](/platform/ask-spara) about agents, leads and analytics without opening the platform, and Spara can post notifications about live conversations with leads into the channel you choose.

### Step 1: Authentication

{% hint style="info" %}
You must be a Manager- or Integrator-level user to manage third party integrations.
{% endhint %}

Navigate to the [Integrations](https://app.spara.co/organization/integrations) page by clicking on the [Settings](https://app.spara.co/organization) link in the left hand navigation bar.

Click the "Authorize" button. This will lead you through an OAuth authentication flow. There are no further steps necessary upon completing this flow. You should see that the integration is "Enabled" within Spara's Integrations page.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-1a7852152150022eef19980c94d7c7a96239f024%2FIntegrations.png?alt=media" alt=""><figcaption></figcaption></figure>

### Step 2: Configure notifications

Once Slack is connected, choose which events notify Slack and where to send them from [**Settings > Notifications**](https://app.spara.co/organization/notifications). See [Notifications](/platform/settings/notifications).

## Ask Spara in Slack

Send the Spara app a direct message, or @-mention it in a channel, and Ask Spara answers in the thread. While it works, the message gets an 👀 reaction. To ask a follow-up, reply in the same thread. In a channel, @-mention the Spara app again in your reply, since it only sees channel messages that mention it.

Ask Spara in Slack can:

* **Answer how-to questions**: how a feature works or where to find a setting, with a link to the right page in Spara.
* **Answer analytics questions**: conversations, meetings, pipeline and other numbers from your account.
* **Look up leads and agents**: how an agent is configured, or why it responded the way it did.

Ask Spara in Slack is read-only. It can't edit agents, prompts, fields or anything else in your account, whatever your role. When you ask for a change, it explains what to change and links the page in Spara where you can make it. To make changes with Ask Spara, use it in the platform.

### Who can use it

Spara matches each person to their Spara user by the email address on their Slack profile. Ask Spara answers with that user's access, so it only sees what they can see in Spara. Someone without a Spara user in your account is asked to get an invite from an admin.

Only the person who started a thread can continue it. Anyone else can start their own thread.

{% hint style="warning" %}
In a channel, everyone in the channel can read Ask Spara's answers. Ask in a direct message when the answer involves lead details or numbers you don't want to share.
{% endhint %}

## Permissions and data use

When you connect Slack, Slack's authorization screen lists the OAuth scopes Spara requests. As with any Slack app, the screen describes what each scope *could* allow. This is what Spara uses them for.

<table data-full-width="true"><thead><tr><th>Scopes</th><th>Why Spara needs them</th></tr></thead><tbody><tr><td><code>app_mentions:read</code>, <code>im:history</code>, <code>im:read</code>, <code>im:write</code>, <code>mpim:history</code>, <code>mpim:read</code>, <code>mpim:write</code>, <code>chat:write</code>, <code>reactions:read</code>, <code>reactions:write</code>, <code>assistant:write</code></td><td>Receive the messages people send to the Spara app or that @-mention it, and reply in the thread. Slack only delivers direct messages to apps that hold the matching history scope.</td></tr><tr><td><code>chat:write</code>, <code>channels:read</code>, <code>groups:read</code>, <code>channels:join</code>, <code>channels:manage</code>, <code>incoming-webhook</code></td><td>List your channels during setup, join the channel you pick (or create it), and post notifications there.</td></tr><tr><td><code>users:read</code>, <code>users:read.email</code>, <code>users.profile:read</code>, <code>team:read</code></td><td>Match people in your workspace to their Spara users by email, so Ask Spara answers with the right access and notifications reach the right sales rep.</td></tr><tr><td>All other scopes, such as <code>channels:history</code>, <code>groups:history</code>, <code>search:read.public</code>, <code>files:read</code>, <code>canvases:write</code> and <code>reminders:write</code></td><td>Used only by Spara's sales assistant in Slack, for accounts that set it up on this app before it moved to its own Slack app. For every other account, Spara doesn't use them.</td></tr></tbody></table>

### What Spara will and will not do

**Spara will:**

* Read the messages people send to the Spara app or that @-mention it, and answer them in the thread.
* Save each question and answer in your Spara account as an Ask Spara conversation.
* Post notifications into the channel you configure.
* List your channels and workspace members so you can complete setup.

**Spara will not:**

* Read channel or direct-message history for Ask Spara or notifications. Ask Spara only sees messages addressed to it.
* Change anything in your Spara account from Slack.
* Monitor or index your Slack conversations.

## FAQ

### Can Ask Spara make changes from Slack?

No. In Slack, Ask Spara only answers questions. It tells you what to change and links the page in Spara where you can do it, or you can ask Ask Spara in the platform to make the change for you.

### Someone on my team gets asked for an invite. What's wrong?

Ask Spara couldn't find a Spara user with the email on their Slack profile. Invite them to Spara with that email from [**Settings > User Management**](https://app.spara.co/settings/user-management), then have them ask again.

### I disconnected Slack. What happens when I reconnect?

Reconnecting from [**Settings > Integrations**](https://app.spara.co/settings/integrations) turns Ask Spara and notifications back on.


# Microsoft Teams

How Spara integrates with Microsoft Teams.

Spara can send notifications to Microsoft Teams channels.

### Step 1: Authentication

{% hint style="info" %}
You must be a Manager- or Integrator-level user to manage third party integrations.
{% endhint %}

Navigate to the [Integrations](https://app.spara.co/organization/integrations) page by clicking on the [Settings](https://app.spara.co/organization) link in the left hand navigation bar.

Click the "Authorize" button. This will lead you through an OAuth authentication flow. There are no further steps necessary upon completing this flow. You should see that the integration is "Enabled" within Spara's Integrations page.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-1a7852152150022eef19980c94d7c7a96239f024%2FIntegrations.png?alt=media" alt=""><figcaption></figcaption></figure>

### Step 2: Configure notifications

Once Microsoft Teams is connected, choose which events notify Teams and which channel to send them to from [**Settings > Notifications**](https://app.spara.co/organization/notifications). See [Notifications](/platform/settings/notifications).

## Permissions and data use

When you connect Spara to Microsoft Teams, the admin consent screen lists the permissions Spara requests. Microsoft's consent dialog shows the maximum scope a permission *could* theoretically allow (the same broad language shown for many Teams integrations), not what Spara actually does. Spara's Teams integration exists for one purpose: to post automated notifications into the team channels you choose.

<table data-full-width="true"><thead><tr><th>Permission</th><th>What it grants</th><th>Why Spara needs it</th></tr></thead><tbody><tr><td><code>offline_access</code></td><td>Stay signed in between sessions (OAuth refresh token)</td><td>Deliver notifications without requiring manual re-authentication. Grants no additional data access.</td></tr><tr><td><code>User.Read</code></td><td>Sign in and read the connecting user's basic profile (name, email)</td><td>Confirm the identity of the admin setting up the integration.</td></tr><tr><td><code>Team.ReadBasic.All</code></td><td>Read team names and descriptions (metadata only)</td><td>Show your teams so you can choose where notifications go.</td></tr><tr><td><code>Channel.ReadBasic.All</code></td><td>Read channel names and descriptions (metadata only)</td><td>Show channels in the selected team so you can choose one.</td></tr><tr><td><code>ChannelMessage.Send</code></td><td>Send messages to team channels</td><td>Spara's core function: post notifications to the channel you configure.</td></tr><tr><td><code>Chat.Read</code></td><td>Read 1:1 or group chats (delegated)</td><td>Required by the Teams bot framework to establish a connection context. Spara does not read, store, or transmit chat content.</td></tr><tr><td><code>ChannelMessage.Read.All</code></td><td>Read a channel's messages (delegated)</td><td>Required by the bot framework for message-delivery confirmation. Spara does not read, index, store, or export channel messages.</td></tr></tbody></table>

### What Spara will and will not do

**Spara will:**

* Post automated notifications into the team channels you explicitly configure.
* Read team and channel names so you can select a target channel during setup.
* Maintain an authenticated connection to deliver those notifications.

**Spara will not:**

* Send messages to individual users or private 1:1 chats.
* Read, store, analyze, or export the content of any channel messages or chats.
* Access channels or teams outside of what you explicitly configure.
* Monitor, surveil, or index any Teams conversations.

### Delegated, not application, permissions

Every permission Spara requests is a **delegated** permission: Spara acts only on behalf of the signed-in user, within what that user is already allowed to do. Spara does **not** request **application** permissions, which would let an app act independently of any user and potentially reach all data across the organization. In practice, Spara cannot access Teams data for users who haven't authenticated with it, nor any channel or team outside what your admins configure.


# Webex

How Spara integrates with Webex.

Spara can send notifications to Webex channels.

### Step 1: Authentication

{% hint style="info" %}
You must be a Manager- or Integrator-level user to manage third party integrations.
{% endhint %}

Navigate to the [Integrations](https://app.spara.co/organization/integrations) page by clicking on the [Settings](https://app.spara.co/organization) link in the left hand navigation bar.

Click the "Authorize" button. This will lead you through an OAuth authentication flow. There are no further steps necessary upon completing this flow. You should see that the integration is "Enabled" within Spara's Integrations page.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-1a7852152150022eef19980c94d7c7a96239f024%2FIntegrations.png?alt=media" alt=""><figcaption></figcaption></figure>

### Step 2: Configure notifications

Once Webex is connected, choose which events notify Webex and which room to send them to from [**Settings > Notifications**](https://app.spara.co/organization/notifications). See [Notifications](/platform/settings/notifications).

### Reconnecting Webex

If Webex stops accepting Spara's access (for example, the authorizing account's password changed or the authorization was revoked), the integration shows **Reconnection required** under **Settings > Integrations**, and a To Do asks you to reconnect. Notifications aren't delivered until you do.

Open **Webex** and click **Reauthorize** to sign in again. Your rooms, notification settings, and workflow steps are kept, so nothing needs to be set up again.


# CRM Integrations

How to integrate Spara with your CRM.

Spara has native CRM integrations that enable bidirectional data syncs between your CRM and Spara. Syncing data from your CRM means Spara never reasks questions your team has already answered, and Spara's behavior can react to each lead based on where they are in your sales funnel.

Connect your CRM under [**Settings > Integrations**](https://app.spara.co/settings/integrations).

| CRM                                                         | Spara reads from CRM                                                                     | Spara writes to CRM                  |
| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------ |
| [Salesforce](/integrations/crm-integrations/salesforce)     | Any mapped field on Lead and Contact; specific fields on Account, Owner, and Opportunity | Any mapped field on Lead and Contact |
| [HubSpot (CRM)](/integrations/crm-integrations/hubspot-crm) | Any mapped Contact property; Company and Owner when enabled; Deals                       | Any mapped Contact property          |
| [Marketo](/integrations/crm-integrations/marketo)           | Any mapped Lead field                                                                    | Any mapped Lead field                |

In addition, Spara provides [Developer: Webhooks](https://docs.spara.com/developers/spara-api/webhooks) and [Developer: Web API](https://docs.spara.com/developers/spara-api/web-api) for completely customizable workflows and data flows into and out of your CRM.

## How the native integration works

Spara's native integrations are designed to work out of the box with a simple, opinionated sync model. Two assumptions drive everything:

1. **Spara creates a CRM record as soon as it knows a lead's email address.** The moment an email is captured (in chat, on a call, or via a webform), Spara matches the lead to an existing CRM record or creates a new one (if you've turned on creating new records). Spara does not wait for additional fields to be gathered first.
2. **Spara pushes every update, as it happens.** Each time a lead's field changes in Spara (a new answer gathered in conversation, an enrichment result, a booked meeting), Spara writes the mapped fields to the CRM record. Conversation transcripts sync shortly after a conversation goes quiet.

Both behaviors require that you grant Spara permission to write: sync only runs for the record types you turn on, and only within the permissions of the CRM user that authorized the connection.

{% hint style="info" %}
Need different behavior, for example only creating a CRM record once a set of required fields is known? Custom sync restrictions are available for Enterprise customers. See [Guide: Working Around CRM Sync Limitations](https://docs.spara.com/guides/integration-guides/crm-sync-workarounds).
{% endhint %}

## Objects Spara syncs

Spara's data model centers on three core objects, **Lead**, **Account**, and **Owner**, plus read-only Deal data for analytics. For a tour of the objects and the full field reference, see [Developer: Spara Objects & Fields](https://docs.spara.com/developers).

| Spara object                   | CRM equivalent                                           | Spara reads        | Spara writes   |
| ------------------------------ | -------------------------------------------------------- | ------------------ | -------------- |
| Lead                           | Salesforce Lead & Contact; HubSpot Contact; Marketo Lead | Yes                | Yes            |
| [Accounts](/pipeline/accounts) | Salesforce Account; HubSpot Company                      | Yes                | No (read-only) |
| [Owners](/pipeline/owners)     | Salesforce User; HubSpot Owner                           | Yes                | No (read-only) |
| Deal                           | Salesforce Opportunity; HubSpot Deal                     | Yes, for analytics | No (read-only) |

Spara also records every lead interaction (messages, calls, emails, meetings) as **Events** in the Spara platform. Events power [Analytics](/pipeline/analytics) and workflow triggers, but are not yet available for CRM sync as structured activity records. Conversation content can still reach your CRM; see each CRM's page for how transcripts sync.

## Key limitations

The native integration favors simplicity over configurability. Be aware of these boundaries:

* **Writes go to Lead and Contact records only.** Spara never updates Accounts, Owners, Deals, or Opportunities in your CRM; those objects are read-only.
* **Salesforce Campaigns sync on request.** Spara can sync Campaigns and Campaign Members for use in workflow criteria; your Spara account team turns this on. See [Developer: Salesforce Campaigns & Campaign Members](https://docs.spara.com/developers/data-model/data-model/campaign).
* **Other CRM objects outside the core model are not synced directly.** Custom objects have no Spara equivalent. For Enterprise customers, Spara's engineering team can map fields from unsupported CRM objects onto Spara's Lead, Account, and Owner objects.
* **Records are created as soon as an email is known.** To wait for more, add a **Create condition** in your [Salesforce](/integrations/crm-integrations/salesforce#create-condition) or [HubSpot (CRM)](/integrations/crm-integrations/hubspot-crm#writing-to-hubspot-contacts) settings. Only admins can edit it.
* **Import Rules (which CRM records are imported as new Leads) are configured by your Spara customer success representative**, not self-serve.

For workarounds to each of these, see [Guide: Working Around CRM Sync Limitations](https://docs.spara.com/guides/integration-guides/crm-sync-workarounds).


# HubSpot (CRM)

How Spara syncs lead data with HubSpot CRM, creates Contacts, and imports Contacts with Import Rules.

Spara integrates with HubSpot to keep your CRM in sync with lead activity. Once connected, Spara can write conversation data and field values to HubSpot Contacts (Push), and import existing HubSpot Contacts into Spara as Leads (Import).

For step-by-step setup instructions, see [Guide: Connecting HubSpot](https://docs.spara.com/guides/integration-guides/connecting-hubspot).

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-a8825aac0dd22079cb476e677ca0046d9e8bde8d%2FHubSpot%20Integration%20Settings.png?alt=media" alt=""><figcaption><p>The HubSpot integration settings page, showing sync, writing, and import settings.</p></figcaption></figure>

| HubSpot Object | Spara writes to HubSpot | Spara reads from HubSpot              |
| -------------- | ----------------------- | ------------------------------------- |
| Contact        | Any mapped property     | Any mapped property                   |
| Company        | *None* (read-only)      | Firmographics; see Company Data below |
| Owner          | *None* (read-only)      | Name and email; see Owner Data below  |
| Deal           | *None* (read-only)      | Deal fields; see Deal Data below      |

## Sync Contacts

The **Sync Contacts** toggle at the top of the Contacts tab turns Contact sync on or off:

* **On**: HubSpot Contacts linked to a Spara Lead sync both ways according to each field's write rule (see [#fields-synced-to-from-crm](#fields-synced-to-from-crm "mention")). Spara pushes conversation insights and field values into those Contacts, and pulls their changes back.
* **Off**: Nothing syncs between Spara and HubSpot Contacts in either direction, and the settings below it don't apply.

## Writing to HubSpot Contacts

While sync is on, the **Writing to HubSpot Contacts** panel sets which HubSpot Contacts Spara can update or create:

* **Create & update**: Spara updates the Contact linked to a Spara Lead, or one that matches by email address, and creates a new Contact when none matches.
* **Update only**: Spara updates linked and matching Contacts, but never creates new ones. Use this when you want HubSpot record creation to stay under your team's control.

With **Create & update**, you can also add a **Create condition**. Spara creates a new Contact only when the lead matches the condition, for example once a company name is known. The condition uses the same filters as Workflows. Only admins can edit it. An email address is always required. A lead that doesn't match yet is retried as soon as the missing information is captured. Matching and updating existing Contacts are not affected.

### How the sync operates

Spara's sync is event-driven, not scheduled:

* **A Contact is created or matched as soon as Spara knows an email address.** The first time an email is captured, whether in chat, on a call, or via a webform, Spara looks for a matching Contact (by stored HubSpot ID first, then email address) and, depending on your settings, updates it or creates a new one. Unless you set a create condition, Spara does not wait for other fields like name or company to be gathered first.
* **Property updates push immediately.** Every time a mapped Spara field changes (a new answer in conversation, a booked meeting, an enrichment result), Spara writes it to HubSpot right away.
* **Conversation transcripts push shortly after the conversation goes quiet.** Transcript syncs are batched, so HubSpot receives one consolidated update a few minutes after the last message rather than one write per message.
* **Import Rules run every few minutes.** New HubSpot Contacts matching your Import Rules are imported as Spara Leads continuously.
* **Linked Contacts stay in sync.** While Contact sync is on, HubSpot Contacts already linked to a Spara Lead have their changes pulled every few minutes according to your write rules, whether or not they match your Import Rules.
* **Deal data syncs nightly.**

### Email logging

Emails Spara exchanges with a lead are logged on the matched Contact as HubSpot email engagements. Logging is on by default; an admin can turn it off with the **Log emails** toggle on the Contacts tab of the [**HubSpot settings page**](https://app.spara.co/settings/integrations/hubspot/manage), for example when HubSpot is connected only to read Companies and Owners alongside another CRM. Emails are not logged while Contact sync is off, and emails sent while logging is off are not logged later if it is turned back on.

{% hint style="info" %}
**Common CRM integration concerns**

The behaviors above are the defaults. Each has a control or workaround, covered in full in [Guide: Working Around CRM Sync Limitations](https://docs.spara.com/guides/integration-guides/crm-sync-workarounds):

* [**Use data from HubSpot objects Spara doesn't support**](https://docs.spara.com/guides/integration-guides/crm-sync-workarounds#use-data-from-crm-objects-spara-doesnt-support): map fields from custom or other unsupported objects onto Spara's core objects (Enterprise).
* [**Require fields before a Contact is created**](https://docs.spara.com/guides/integration-guides/crm-sync-workarounds#require-fields-before-a-crm-record-is-created): add a **Create condition** under **Writing to HubSpot Contacts** so Spara holds Contact creation until more than an email is known.
* [**Keep Spara from overwriting HubSpot data**](https://docs.spara.com/guides/integration-guides/crm-sync-workarounds#keep-spara-from-overwriting-crm-data): set the Spara → CRM write rule to **Set if empty** or **Read-only**, or turn off **Sync Contacts**.
* [**Write to Companies, Deals, or other objects**](https://docs.spara.com/guides/integration-guides/crm-sync-workarounds#write-to-accounts-opportunities-or-other-objects): route data through Webhooks, the API workflow step, or the Web API.
* [**Log Spara activity in HubSpot**](https://docs.spara.com/guides/integration-guides/crm-sync-workarounds#log-spara-activity-in-your-crm): sync transcripts to a Contact property (emails are logged as engagements automatically), or build activity records from Webhooks.
* [**Control which HubSpot Contacts enter Spara**](https://docs.spara.com/guides/integration-guides/crm-sync-workarounds#control-which-crm-records-enter-spara): Import Rules filter on any Contact property; configured with your Spara team.
  {% endhint %}

## Import Rules

Import Rules control which existing HubSpot Contacts are imported into Spara as new Leads. This is useful for leads that exist in HubSpot but have not yet interacted with a Spara agent. Spara can import them so your agents and workflows can proactively reach out. Import Rules can filter on any HubSpot Contact property; by default, Spara only imports Contacts that have an email address. The **Import Contacts** toggle turns importing on or off.

Import Rules only decide which Contacts become new Spara Leads. They don't affect how Contacts already linked to a Spara Lead sync; that is controlled by the **Sync Contacts** toggle in [#sync-contacts](#sync-contacts "mention").

{% hint style="info" %}
Import Rules are configured by your Spara customer success representative.
{% endhint %}

## Recognizing returning visitors

If your site runs the HubSpot tracking code, Spara recognizes visitors HubSpot already knows. When a visitor opens the Spara chat, Spara reads HubSpot's `hubspotutk` cookie and looks up the matching HubSpot Contact. If the Contact has an email, Spara fills in their email, name, company and any mapped fields and links the Lead to that Contact, so the agent doesn't ask for information you already have.

This turns on automatically once HubSpot is connected to Spara.

* Only visitors HubSpot has already identified, for example through a HubSpot form, are recognized. Anonymous visitors go through the normal conversation.
* Anything the visitor has already provided to Spara is never overwritten.
* If you use Spara's cookie consent integration, the cookie isn't read until the visitor consents.

This is the reverse of [Guide: Setting Up HubSpotUTK Cookie Tracking](https://docs.spara.com/guides/integration-guides/setting-up-hubspotutk-cookie-tracking), which tells HubSpot about emails Spara captures.

## Fields synced to/from CRM

Field mappings are edited on each field in the [**Data Model**](https://app.spara.co/data-model). Open a field and use its **HubSpot sync** section, which has a slot for each HubSpot object the field can map to: **Contact** for Lead fields, **Company** for Account fields, and **Owner** for Owner fields. Save your edits with the page's **Save changes** prompt.

Each slot defines:

* **HubSpot field**: the HubSpot property the Spara field maps to
* **HubSpot → Spara**: how Spara writes the HubSpot value into the Spara field
* **Spara → HubSpot**: how Spara writes the Spara value into the HubSpot property

Each direction has its own write rule:

* **Overwrite**: replace any existing value
* **Set if empty**: write only when the receiving field is empty
* **Read-only**: never write in this direction

Company and Owner mappings are pull-only (**Pulled from HubSpot**). When HubSpot marks a property read-only (such as calculated properties), or the Spara field is [Data Model](/build/data-model#what-is-a-read-only-field), **Spara → HubSpot** is locked to **Read-only**. Likewise, **HubSpot → Spara** is locked to **Read-only** for fields Spara sets itself, such as GCLID, UTM parameters, and conversation summaries and transcripts.

The field page flags mapping problems in plain language, such as a mapping that syncs nothing because both directions are **Read-only**, mismatched types, or picklist values HubSpot would reject. See [Data Model](/build/data-model#crm-field-mappings) for the full list, and for **Suggest fields**, which suggests HubSpot Contact mappings from the Data Model page.

The Email field is always mapped automatically and cannot be removed. You can map as many additional fields as needed. Field mappings apply in both directions, each according to its own write rule.

### Reviewing mappings in HubSpot settings

Each tab in the HubSpot settings page (Contacts, Accounts, Owners) shows a read-only **Fields synced to/from CRM** list (**Fields synced from CRM** for Accounts and Owners). Fields with mapping problems are listed first, each row opens its field in the Data Model, and **Manage in Data Model** takes you to the Data Model page. If that object's sync is off, the list says so, since those mappings don't run.

## Company Data

When company syncing is enabled, Spara reads the Company associated with each matched Contact, including name, domain, website, industry, employee count, annual revenue, and city. Synced companies appear on the [Accounts](/pipeline/accounts) page, and their fields are available in workflow conditions and agent personalization.

Company data is read-only: Spara never creates or updates HubSpot Companies.

## Owner Data

When owner syncing is enabled, Spara reads the assigned owner from matching HubSpot Contact records. If an owner is found and active, their details are available in Spara, including name and email, and appear in the lead's detail view and on the [Owners](/pipeline/owners) page.

Owner data is available as fields in workflow conditions and agent personalization, so you can reference a lead's assigned rep by name in emails, chat messages, or routing logic.

## Deal Data

Spara reads HubSpot Deal data nightly to power pipeline and revenue reporting in [Analytics](/pipeline/analytics), including which deals Spara-engaged leads influenced. Spara reads each Deal's name, amount, stage, close date, currency, and open/closed/won status. Deal data is read-only: Spara never creates or updates HubSpot Deals.

## Limitations

* **Writes are Contact-only.** Companies, Owners, and Deals are read-only. Spara cannot update them when it learns something new. HubSpot Lead objects are not synced; Spara Leads map to HubSpot Contacts.
* **Records are created as soon as an email is known.** To wait for more, add a **Create condition** under [#writing-to-hubspot-contacts](#writing-to-hubspot-contacts "mention").
* **HubSpot's required properties must be mapped.** If your portal requires properties when a Contact is created (for example **Legal basis for processing contact's data** under HubSpot's GDPR settings, or properties marked required on the Contact object), HubSpot refuses any Contact that lacks them. Map a Spara fact to each required property, or stop requiring it in HubSpot. Until then, each affected Lead shows a **Couldn't create this record** entry in the sync log naming the properties, and Spara still updates the Contact once HubSpot has one for that email (for example from a form submission).
* **Spara Events are not synced as structured activity.** Conversation transcripts sync through a mapped Contact property, and emails Spara exchanges with a lead are logged as HubSpot email engagements (an admin can turn this off with **Log emails** on the Contacts tab of the HubSpot settings page), but individual events (page visits, calls, meetings) are not written as HubSpot activities.
* **Unsupported objects require custom mapping.** Fields from HubSpot objects Spara doesn't model can be mapped onto Spara's Lead, Account, and Owner objects by Spara's engineering team, available for Enterprise customers.

For practical workarounds, see [Guide: Working Around CRM Sync Limitations](https://docs.spara.com/guides/integration-guides/crm-sync-workarounds).

## Sync Logs

The **Logs** tab on the [**HubSpot settings page**](https://app.spara.co/settings/integrations/hubspot/manage) shows every sync between Spara and HubSpot, newest first. Each entry records what happened (a contact created or updated, fields that didn't sync, a sync skipped because of your settings, or a connection problem like an expired token) along with the Lead it affected, the HubSpot record, and how many fields synced.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-db930a71a8f69b8f3a33ebb0f130c8dc167e7bb7%2FHubSpot%20Sync%20Logs.png?alt=media" alt=""><figcaption><p>The Sync Logs tab, showing each sync's status, direction, Lead, HubSpot record, and field counts.</p></figcaption></figure>

Filter the list by status (**Synced**, **Needs attention**, or **Failed**), direction, or timeframe. Search covers the technical detail behind each entry as well as its summary, so you can look up a HubSpot error code or a property name and find every record hitting the same problem.

Select an entry to see its details:

* A plain-language explanation of what happened, and what to do about it, with a link to the setting that fixes it
* The Lead and the HubSpot record involved
* Every field the sync moved, shown as the Spara field, the HubSpot property it maps to, and the value
* For any field HubSpot rejected, the reason HubSpot gave. For example, a property that no longer exists, or a value that isn't one of its defined options

Each Lead also has a **CRM sync** row in its details showing that Lead's most recent sync outcome, which opens the same view. That answers "did this Lead reach HubSpot?" without leaving the Lead.

## FAQ

### How does Spara match a Lead to a HubSpot Contact?

Spara matches by stored HubSpot Contact ID first, then by email address. As soon as a lead provides their email in a conversation, Spara attempts to find a matching Contact and begin syncing.

### Will Spara overwrite existing data in HubSpot?

By default, yes. New field mappings use **Overwrite** in both directions. Set **Spara → HubSpot** to **Set if empty** to protect existing HubSpot data, or to **Read-only** so Spara never writes that property.

### Can Spara update HubSpot Companies or Deals?

No. Spara only writes to Contacts. If you need Spara data written to other objects, use [Developer: Webhooks](https://docs.spara.com/developers/spara-api/webhooks) with your own automation. See [Guide: Working Around CRM Sync Limitations](https://docs.spara.com/guides/integration-guides/crm-sync-workarounds).

### What happens if HubSpot is disconnected?

Syncing stops immediately. Your field mappings are preserved so you can resume with the same configuration after reconnecting. To reconnect, go to [**Settings > Integrations**](https://app.spara.co/settings/integrations) and click **Authorize** on the HubSpot card.


# Marketo

How Spara integrates with Marketo.

Spara supports bidirectional data syncs with Marketo.

For sending data to Marketo, Spara supports:

* Writing entire conversation histories
* Writing structured data, ex. the answer a lead gives to a specific question

Syncing data from Marketo to Spara streamlines your buyer's sales process by:

* Spara never reasks a question
* Spara's behavior can react to each lead based on where they are in your sales funnel
* Syncs can be triggered at any point in the conversation

### Authentication

{% hint style="info" %}
You must be a Manager-level user to manage third party integrations. You will likely want the individual who manages your Marketo deployment to complete these instructions.
{% endhint %}

Click the "Organization Settings" link in the left hand navigation bar. Then click the "Integrations" tab.

Click "Authorize" within the Marketo module. This will lead you through an authentication flow. There are no further steps necessary upon completing this flow. You should see that Marketo is "Enabled" within Spara's Integrations page.

The Marketo API user you connect with needs a role that has these permissions (Marketo **Admin > Users & Roles**):

* **Read-Write Lead**, to match, create, and update Leads
* **Read-Only Activity**, to read Lead changes so Spara can pull updates from Marketo

If the role is missing one of these, Marketo refuses the call. Spara then records a "Marketo denied Spara's lead pull" entry in your sync log and keeps retrying every few minutes, so syncing resumes on its own once the permission is granted.

### Data Syncing

Spara will automatically sync all conversation data to matching `Lead` objects in Marketo. This includes the full conversation history.

Spara matches data based on supplied [Developer: Query Parameters](https://docs.spara.com/developers/spara-api/query-parameters). As soon as an email is captured in the Spara chat, Spara attempts to match the `email` field to a Marketo `Lead` object with an identical email property. Data continues to sync throughout the conversation.

To sync additional fields, open a field in the [**Data Model**](https://app.spara.co/data-model) and map it to a Marketo `Lead` field in its **Marketo sync** section. Each mapping has a write rule per direction (**Marketo → Spara** and **Spara → Marketo**): **Overwrite**, **Set if empty**, or **Read-only**. See [Data Model](/build/data-model#crm-field-mappings).

Linked Leads stay in sync both ways. Spara pushes field changes to the Marketo Lead right away, and pulls changes from Marketo every few minutes, each according to the field's write rule. When Marketo is first connected, the initial pull covers Leads created in Marketo in the last 30 days.

The Marketo settings page shows a read-only **Fields synced to/from CRM** list, with mapping problems first and **Manage in Data Model** to edit them.

### Import Rules

Import Rules control which existing Marketo Leads are imported into Spara as new Leads. This is useful for leads that exist in Marketo but have not yet interacted with a Spara agent. Spara can import them so your agents and workflows can proactively reach out. Import Rules can filter on any Marketo Lead field; by default, Spara only imports Leads that have an email address. The **Import Leads** toggle on the [**Marketo settings page**](https://app.spara.co/settings/integrations/marketo/manage) turns importing on or off.

Import Rules only decide which Leads become new Spara Leads. They don't affect how Leads already linked to a Spara Lead sync; that is controlled by the **Sync Leads** toggle above them.

{% hint style="info" %}
Import Rules are configured by your Spara customer success representative.
{% endhint %}

### Recognizing returning visitors

If your site runs Marketo's Munchkin tracking script, Spara recognizes visitors Marketo already knows. When a visitor opens the Spara chat, Spara reads the Munchkin `_mkto_trk` cookie and looks up the matching Marketo `Lead`. If the lead has an email, Spara fills in their email, name, company and any mapped fields, so the agent doesn't ask for information you already have.

This turns on automatically once Marketo is connected. There's nothing else to set up.

* Only visitors Marketo has already identified are recognized. Anonymous visitors go through the normal conversation.
* Anything the visitor has already provided to Spara is never overwritten.
* If you use Spara's cookie consent integration, the cookie isn't read until the visitor consents.


# Salesforce

How Spara syncs lead data with Salesforce, creates records, and imports records with Import Rules.

Spara integrates with Salesforce to keep your CRM in sync with lead activity. Once connected, Spara can write conversation data and field values to Salesforce Lead and Contact objects (Push), and import existing Salesforce records into Spara as Leads (Import).

For step-by-step setup instructions, see [Guide: Connecting Salesforce](https://docs.spara.com/guides/integration-guides/connecting-salesforce).

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-e12b102ee61939d7dc3b758fdb7a5c43a0924c83%2FSalesforce%20Integration%20Settings.png?alt=media" alt=""><figcaption><p>The Salesforce integration settings page (Leads tab), showing sync, writing, and import settings.</p></figcaption></figure>

| Salesforce Object | Spara writes to Salesforce | Spara reads from Salesforce             |
| ----------------- | -------------------------- | --------------------------------------- |
| Lead              | Any mapped field           | Any mapped field                        |
| Contact           | Any mapped field           | Any mapped field                        |
| Account           | *None* (read-only)         | Specific fields; see Account Data below |
| Owner (User)      | *None* (read-only)         | Specific fields; see Owner Data below   |
| Opportunity       | *None* (read-only)         | Deal fields; see Opportunity Data below |

## Sync Leads and Contacts

Lead and Contact sync are configured separately under the Contacts and Leads tabs in [**Settings > Integrations > Salesforce**](https://app.spara.co/settings/integrations/salesforce/manage). The **Sync Leads** / **Sync Contacts** toggle at the top of each tab turns sync on or off for that record type:

* **On**: Salesforce records linked to a Spara Lead sync both ways according to each field's write rule (see [#fields-synced-to-from-crm](#fields-synced-to-from-crm "mention")).
* **Off**: Nothing syncs between Spara and that record type in either direction, and the settings below it don't apply.

A record type the connected Salesforce user can't see stays off, and its tab is read-only until that user is granted access to it.

## Writing to Salesforce Leads and Contacts

While sync is on, the **Writing to Salesforce Leads** and **Writing to Salesforce Contacts** panels set which Salesforce records Spara can update or create:

* **Create & update**: Spara updates the Salesforce record linked to a Spara Lead, or one that matches by email address or phone number, and creates a new record when none matches.
* **Update only**: Spara updates linked and matching records, but never creates new ones. Use this when you want Salesforce record creation to stay under your team's control.
* **Create only**: Spara creates a new Salesforce record for every Spara Lead not yet linked, without matching existing records. Records Spara created stay in sync.

#### Only write to Salesforce Leads if no matching Contact exists

Many Salesforce teams use Leads for people who aren't in Salesforce yet and Contacts for people who are. On the Leads tab, turn on **Only write to Salesforce Leads if no matching Contact exists** to keep it that way. When a Spara Lead is already linked to a Salesforce Contact, or a Contact matches its email address, Spara leaves the Lead alone: it neither creates nor updates one, and logs the skip in the sync log. The Contact itself syncs according to the Contacts tab, so with Contacts on **Update only** an existing Contact is updated and no duplicate Lead appears. With Contacts on **Create & update**, a brand-new person becomes a Contact rather than a Lead, and someone who already has a Lead gets a Contact too, after which the Lead is left alone.

Spara reads Contacts for this check even when Contact sync is off, so the connected Salesforce user needs read access to Contacts. If Spara can't read Contacts, Leads are written as if the option were off until access is restored. The option has no effect while Lead sync is off.

#### Create condition

When **Create & update** or **Create only** is selected, you can add a **Create condition** to control when Spara creates a new record. For example, you might create a Salesforce Lead only once Spara knows the lead's last name and company. The condition uses the same filters as Workflows. Combine Spara fields with **and** or **or**, using operators such as **is defined**.

* Only admins can edit the create condition. Other users see it read-only.
* An email address is always required. It is shown as a locked first row.
* **Use Salesforce required fields** adds the fields Salesforce needs to create a record: **Last name** and **Company** for Leads, and **Last name** for Contacts. Without them, Spara fills those fields with `UNKNOWN`.
* If a lead doesn't meet the condition yet, Spara doesn't create the record and logs the skip in the sync log. As soon as the missing information is captured, Spara tries again.
* The condition only applies to creating records. Matching and updating existing Salesforce records work as before.

These settings are limited by the permissions of the Salesforce user that authorized the connection. If that user cannot edit Leads in Salesforce, Lead sync is turned off. If the user can edit Leads but not create them, Lead sync is set to **Update only**.

### How the sync operates

Spara's sync is event-driven, not scheduled. Understanding the timing helps you predict exactly what appears in Salesforce and when:

* **A record is created or matched as soon as Spara knows an email address.** The first time an email is captured, whether in chat, on a call, or via a webform, Spara looks for a matching Salesforce record and, depending on your settings, updates it or creates a new one. Unless you set a [create condition](#create-condition), Spara does not wait for other fields like name or company to be gathered first.
* **Field updates push immediately.** Every time a mapped Spara field changes (a new answer in conversation, a booked meeting, an enrichment result), Spara writes it to Salesforce right away.
* **Conversation transcripts push shortly after the conversation goes quiet.** Transcript syncs are batched, so Salesforce receives one consolidated update a few minutes after the last message rather than one write per message.
* **Import Rules run every few minutes.** New Salesforce records matching your Import Rules are imported as Spara Leads continuously.
* **Linked records stay in sync.** While sync is on for a record type, Salesforce Leads and Contacts already linked to a Spara Lead have their changes pulled every few minutes according to your write rules, whether or not they match your Import Rules.
* **Opportunity data syncs nightly.**

### How matching works

When looking for an existing record, Spara matches in this order:

1. **Salesforce ID**: a stored Salesforce Lead ID (`salesforce_lead_id`) or Contact ID (`salesforce_contact_id`), captured from a previous sync or passed in via [Developer: Query Parameters](https://docs.spara.com/developers/installation/query-parameters)
2. **Email address**
3. **Phone number**

Matching is automatic. You do not need to set up explicit ID syncing. If multiple Salesforce records share the same email or phone number, Spara syncs to the most recently created one.

{% hint style="info" %}
**Common CRM integration concerns**

The behaviors above are the defaults. Each has a control or workaround, covered in full in [Guide: Working Around CRM Sync Limitations](https://docs.spara.com/guides/integration-guides/crm-sync-workarounds):

* [**Use data from Salesforce objects Spara doesn't support**](https://docs.spara.com/guides/integration-guides/crm-sync-workarounds#use-data-from-crm-objects-spara-doesnt-support): map fields from custom objects or Opportunities onto Spara's core objects (Enterprise). For Campaigns, use campaign sync instead (see [Developer: Salesforce Campaigns & Campaign Members](https://docs.spara.com/developers/data-model/data-model/campaign)).
* [**Require fields before a record is created**](https://docs.spara.com/guides/integration-guides/crm-sync-workarounds#require-fields-before-a-crm-record-is-created): add a **Create condition** so Spara holds record creation until more than an email is known.
* [**Keep Spara from overwriting Salesforce data**](https://docs.spara.com/guides/integration-guides/crm-sync-workarounds#keep-spara-from-overwriting-crm-data): set the Spara → CRM write rule to **Set if empty** or **Read-only**, or turn off **Sync Leads** / **Sync Contacts**.
* [**Write to Accounts, Opportunities, or other objects**](https://docs.spara.com/guides/integration-guides/crm-sync-workarounds#write-to-accounts-opportunities-or-other-objects): route data through Webhooks, the API workflow step, or the Web API.
* [**Log Spara activity in Salesforce**](https://docs.spara.com/guides/integration-guides/crm-sync-workarounds#log-spara-activity-in-your-crm): sync transcripts to a text field, enable Task logging, or build activity records from Webhooks.
* [**Control which Salesforce records enter Spara**](https://docs.spara.com/guides/integration-guides/crm-sync-workarounds#control-which-crm-records-enter-spara): Import Rules filter on any Lead or Contact field; configured with your Spara team.
  {% endhint %}

## Import Rules

Import Rules control which existing Salesforce records are imported into Spara as new Leads. This is useful for leads that exist in Salesforce but have not yet interacted with a Spara agent. Spara can import them so your agents and workflows can proactively reach out.

Import Rules are defined as a filter on any Salesforce Lead or Contact field, for example only records from a specific lead source, region, or campaign. By default, Spara only imports records that have an email address. The **Import Leads** / **Import Contacts** toggle turns importing on or off.

Import Rules only decide which records become new Spara Leads. They don't affect how records already linked to a Spara Lead sync; that is controlled by the **Sync Leads** / **Sync Contacts** toggle in [#sync-leads-and-contacts](#sync-leads-and-contacts "mention").

{% hint style="info" %}
Import Rules are configured by your Spara customer success representative. Contact your Spara team to set up or change them.
{% endhint %}

## Fields synced to/from CRM

Field mappings are edited on each field in the [**Data Model**](https://app.spara.co/data-model). Open a field and use its **Salesforce sync** section, which has a slot for each Salesforce object the field can map to: **Contact** and **Lead** for Lead fields, **Account** for Account fields, and **Owner** for Owner fields. Leads and Contacts are mapped independently. Save your edits with the page's **Save changes** prompt.

Each slot defines:

* **Salesforce field**: the Salesforce field the Spara field maps to
* **Salesforce → Spara**: how Spara writes the Salesforce value into the Spara field
* **Spara → Salesforce**: how Spara writes the Spara value into the Salesforce field

Each direction has its own write rule:

* **Overwrite**: replace any existing value
* **Set if empty**: write only when the receiving field is empty
* **Read-only**: never write in this direction

Account and Owner mappings are pull-only (**Pulled from Salesforce**). When Salesforce doesn't let Spara write a field (formula, auto-number, and system fields, or fields the integration user can't edit), or the Spara field is [Data Model](/build/data-model#what-is-a-read-only-field), **Spara → Salesforce** is locked to **Read-only**. Likewise, **Salesforce → Spara** is locked to **Read-only** for fields Spara sets itself, such as GCLID, UTM parameters, and conversation summaries and transcripts.

The field page flags mapping problems in plain language, such as a mapping that syncs nothing because both directions are **Read-only**, mismatched types, or picklist values Salesforce would reject. See [Data Model](/build/data-model#crm-field-mappings) for the full list, and for **Suggest fields**, which suggests Salesforce Lead and Contact mappings from the Data Model page.

The Email field is always mapped automatically. You can map as many additional fields as needed, including the full conversation history via the **Conversation transcript (all channels)** Spara field.

Field mappings work in both directions: the same mapping that pushes a Spara field to Salesforce also pulls that Salesforce field into Spara, each according to its own write rule. For example, to bring a Salesforce field into Spara without Spara ever changing it in Salesforce, set **Salesforce → Spara** to **Overwrite** and **Spara → Salesforce** to **Read-only**.

### Reviewing mappings in Salesforce settings

Each tab in the Salesforce settings page (Contacts, Leads, Accounts, Owners) shows a read-only **Fields synced to/from CRM** list (**Fields synced from CRM** for Accounts and Owners). Fields with mapping problems are listed first, each row opens its field in the Data Model, and **Manage in Data Model** takes you to the Data Model page. If that object's sync is off, the list says so, since those mappings don't run.

## Account Data

When a matching Salesforce Account is found, Spara reads and stores the following fields automatically:

* `salesforce_account_id`: the unique identifier of the Salesforce Account
* `salesforce_account_name`: the Account name (usually the company name)
* `salesforce_account_owner_email`: the email of the Account's assigned owner

Accounts are matched using this priority order:

1. Converted Lead: if the Lead was previously converted, the associated Account is returned
2. Matching Contact: the Account linked to the most recently created Contact with the same email
3. Matching Company Name: if the user provides a company name that exactly matches an Account name

When account syncing is enabled, matched Accounts also appear on the [Accounts](/pipeline/accounts) page with their firmographics (website, industry, employee count, annual revenue, and billing city).

Account data is read-only: Spara never creates or updates Salesforce Accounts.

## Owner Data

When a matching Salesforce Owner (assigned sales rep) is found and active, Spara reads and stores:

* `salesforce_assigned_sales_rep_id`
* `salesforce_assigned_sales_rep_name`
* `salesforce_assigned_sales_rep_email`

If a matching Account also has an assigned owner:

* `salesforce_account_owner_id`
* `salesforce_account_owner_name`
* `salesforce_account_website`

Owner data is available in workflow conditions and agent personalization, so you can reference a lead's assigned rep by name in emails, chat, or routing logic. Owners also appear on the [Owners](/pipeline/owners) page.

The `salesforce_*` id fields above are legacy. Prefer the Account and Owner fields on the lead, which work for any CRM: `lead_account_crm_id`, `lead_owner_crm_id`, and `lead_account_owner_crm_id`, alongside `lead_owner_email`, `lead_account_company_name`, and the rest listed in [https://github.com/spara-ai/spara-app/tree/main/gitbook/developers/data-model/account.md](https://github.com/spara-ai/spara-app/tree/main/gitbook/developers/data-model/account.md "mention") and [https://github.com/spara-ai/spara-app/tree/main/gitbook/developers/data-model/owner.md](https://github.com/spara-ai/spara-app/tree/main/gitbook/developers/data-model/owner.md "mention").

## Opportunity Data

Spara reads Salesforce Opportunity data nightly to power pipeline and revenue reporting in [Analytics](/pipeline/analytics), including which deals Spara-engaged leads influenced. Spara reads each Opportunity's name, amount, stage, close date, currency, and open/closed/won status.

Two things to know:

* Opportunities are linked to leads through Salesforce **Contact Roles**, so deal reporting requires Contact sync to be enabled.
* Opportunity data is read-only. Spara never creates or updates Salesforce Opportunities.

## Conversation and Email Sync

Spara can write conversation activity to Salesforce in three ways:

* **Conversation transcript to a text field.** Map the **Conversation transcript (all channels)** Spara field to any Salesforce long-text field in that field's **Salesforce sync** section in the Data Model. Spara writes the full transcript across chat, email, SMS, phone calls and product demos, updated as the conversation progresses. A transcript longer than the field keeps its most recent messages, with a note at the top saying so.
* **Conversation transcript as a Salesforce Task.** Spara can additionally log each conversation as a Task attached to the Lead or Contact, assigned to the lead's Salesforce owner. Contact your Spara team to enable this; it requires the lead to have an assigned owner in Salesforce.
* **Emails as Salesforce email records.** Emails exchanged between Spara and a lead are logged to the matched Lead or Contact as native Salesforce email activity.

Email logging is on by default and is set separately for Contacts and Leads with the **Log emails** toggle on each tab of the [**Salesforce settings page**](https://app.spara.co/settings/integrations/salesforce/manage). An email goes to the matched Contact when there is one, otherwise to the Lead, and is skipped when that record type has logging or sync turned off. An admin can turn it off for both, for example when Salesforce is connected only to read Accounts and Owners alongside another CRM. Emails sent while it is off are not logged later if it is turned back on.

## Limitations

The native Salesforce integration is intentionally opinionated. Current limitations to plan around:

* **Writes are Lead and Contact only.** Accounts, Owners, Opportunities, and Campaigns are read-only. Spara cannot update them when it learns something new about a company or deal.
* **Campaign sync is set up by Spara.** When your Spara account team turns on campaign sync, Campaigns and Campaign Members sync into Spara for use in workflow criteria. See [Developer: Salesforce Campaigns & Campaign Members](https://docs.spara.com/developers/data-model/data-model/campaign).
* **Unsupported objects require custom mapping.** Fields from Salesforce objects Spara doesn't model (custom objects, Opportunities beyond analytics, etc.) can be mapped onto Spara's Lead, Account, and Owner objects by Spara's engineering team, available for Enterprise customers.
* **Records are created as soon as an email is known.** Salesforce requires a last name (and company, for Leads) on every record, so when Spara creates a record before those fields are captured, it fills them with the placeholder `UNKNOWN` and updates them as the real values arrive. To wait for those fields instead, add a [create condition](#create-condition) and turn on **Use Salesforce required fields**.
* **Spara Events are not synced as structured activity.** Individual events (page visits, calls, meetings booked) are recorded in Spara and power Analytics and workflows, but are not written to Salesforce as Task or Event records. Conversation activity reaches Salesforce through the mechanisms in [#conversation-and-email-sync](#conversation-and-email-sync "mention").

For practical workarounds to each of these, see [Guide: Working Around CRM Sync Limitations](https://docs.spara.com/guides/integration-guides/crm-sync-workarounds).

## Sync Logs

The **Logs** tab on the [**Salesforce settings page**](https://app.spara.co/settings/integrations/salesforce/manage) shows every sync between Spara and Salesforce, newest first. Each entry records what happened (a record created or updated, fields that didn't sync, a sync skipped because of your settings, or a connection problem like an expired token) along with the Lead it affected, the Salesforce record, and how many fields synced.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-05b5698d2f215a6e1ac2418ad5126a7da85cb234%2FSalesforce%20Sync%20Logs.png?alt=media" alt=""><figcaption><p>The Sync Logs tab, showing each sync's status, direction, Lead, Salesforce record, and field counts.</p></figcaption></figure>

Filter the list by status (**Synced**, **Needs attention**, or **Failed**), direction, or timeframe. Search covers the technical detail behind each entry as well as its summary, so you can look up a Salesforce error code or a field name and find every record hitting the same problem.

Select an entry to see its details:

* A plain-language explanation of what happened, and what to do about it, with a link to the setting that fixes it
* The Lead and the Salesforce record involved
* Every field the sync moved, shown as the Spara field, the Salesforce field it maps to, and the value
* For any field Salesforce rejected, the reason Salesforce gave. For example, a field that no longer exists, or a value that isn't one of its picklist options

Each Lead also has a **CRM sync** row in its details showing that Lead's most recent sync outcome, which opens the same view. That answers "did this Lead reach Salesforce?" without leaving the Lead.

## FAQ

### How does Spara match a Lead to a Salesforce record?

Spara matches by stored Salesforce ID first, then email address, then phone number. Matching is automatic; you do not need to configure ID syncing in your field mappings.

### Can I sync to both Lead and Contact objects?

Yes. Leads and Contacts are configured independently, and a Spara Lead can sync to both a Salesforce Lead and a Contact simultaneously. If you'd rather Spara never touch a Lead for someone who is already a Contact, turn on **Only write to Salesforce Leads if no matching Contact exists** on the Leads tab (see [#only-write-to-salesforce-leads-if-no-matching-contact-exists](#only-write-to-salesforce-leads-if-no-matching-contact-exists "mention")).

### Can Spara sync the full conversation history to Salesforce?

Yes. Open the **Conversation transcript (all channels)** field in the [**Data Model**](https://app.spara.co/data-model) and map it to any text field in Salesforce in its **Salesforce sync** section, or ask your Spara team to enable Task logging. See [#conversation-and-email-sync](#conversation-and-email-sync "mention").

### Will Spara overwrite existing data in Salesforce?

By default, yes. New field mappings use **Overwrite** in both directions. Set **Spara → Salesforce** to **Set if empty** to protect existing Salesforce data, or to **Read-only** so Spara never writes that field.

### Can Spara update Salesforce Accounts or Opportunities?

No. Spara only writes to Lead and Contact records. Account, Owner, and Opportunity data is read-only. If you need Spara data written to other objects, use [Developer: Webhooks](https://docs.spara.com/developers/spara-api/webhooks) with your own automation. See [Guide: Working Around CRM Sync Limitations](https://docs.spara.com/guides/integration-guides/crm-sync-workarounds).

### Why do some Spara-created records show "UNKNOWN" as the name or company?

Salesforce requires those fields on every record, and Spara creates the record as soon as it captures an email, sometimes before a name or company is known. Spara fills the gaps with `UNKNOWN` and replaces them automatically as the real values are gathered.

### Can I stop Spara from creating new Salesforce records?

Yes. Choose **Update only** for Leads or Contacts, and Spara will sync matching records but never create new ones.

## Troubleshooting

### Integration user setup and permissions

The most common cause of sync problems is an integration user that isn't set up correctly or doesn't have the permissions Spara needs. Sync settings and field access are limited by the permissions of the Salesforce user that authorized the connection, so a misconfigured user can silently block record creation or updates. This walkthrough covers how to check and fix the integration user:

{% embed url="<https://www.loom.com/share/9e2672867b9e4975a9404605b94806d8>" %}

### OAuth Error on connect

If you see an OAuth Error during authorization, two options:

**Option 1:** Have your Salesforce admin log into Spara and connect directly.

**Option 2:** Your Salesforce admin creates an external connected app and grants API permissions. The connected app should enable read/create/edit access on Leads and Contacts.

### Reconnection required

If the Salesforce card shows "Reconnection required," Spara's access token has expired. Go to [**Settings > Integrations > Salesforce**](https://app.spara.co/settings/integrations/salesforce/manage), click **Deauthorize**, then authorize again.

### Disconnecting

To disconnect Salesforce, go to [**Settings > Integrations > Salesforce**](https://app.spara.co/settings/integrations/salesforce/manage) and click **Deauthorize**. Your field mappings and sync configuration are preserved if you reconnect later.


# Document Sync Integrations

How to sync documents to Spara for AI training.

Spara can sync documents from your team's knowledge repositories to train AI agents. Synced documents are added to your [Knowledge](/build/knowledge) base, giving agents the context they need to answer questions accurately.

Connect a document source under [**Settings > Integrations**](https://app.spara.co/settings/integrations).

| Platform                                                              | Supported content                             |
| --------------------------------------------------------------------- | --------------------------------------------- |
| [Google Drive](/integrations/document-sync-integrations/google-drive) | Google Docs, PDFs, and other text-based files |
| [Sharepoint](/integrations/document-sync-integrations/sharepoint)     | SharePoint documents and pages                |
| [Confluence](/integrations/document-sync-integrations/confluence)     | Confluence pages and spaces                   |
| [Notion](/integrations/document-sync-integrations/notion)             | Notion pages and databases                    |

Spara supports syncing the following document types:

* Google Docs
* Microsoft Word (.docx)
* PDFs
* Rich text and Markdown formats

#### Why doesn't Spara support spreadsheet or slide formats?

Some file formats generally result in poor performance when ingested by large language models. Spara does not support the following file formats:

* Slides (ex. Powerpoint, Google Slides) are often mostly visual. Any text ingested by the LLM will be missing the necessary context of slide structure or visual elements.
* Spreadsheets (ex. Excel, Google Sheets) are mostly numerical information without sufficient language context to be useful to a large language model.


# Confluence

How to sync Confluence pages to Spara for AI training.

Spara syncs pages from your Confluence Cloud workspace to train your AI agents. Synced pages are added to your [Knowledge](/build/knowledge) base, giving agents the context they need to answer questions about your products, processes, and internal documentation.

## Setup

{% stepper %}
{% step %}

### Connect Confluence

Navigate to [**Settings > Integrations**](https://app.spara.co/settings/integrations) and click **Connect** next to Confluence. Complete the Atlassian OAuth flow to authorize Spara to access your Confluence instance.
{% endstep %}

{% step %}

### Select pages and spaces

After connecting, use the file picker to browse your Confluence spaces, folders, and pages. Select the content you want to sync. You can select entire spaces or folders to sync all pages within them.
{% endstep %}

{% step %}

### Pages sync automatically

Spara periodically syncs your selected content, picking up new pages and changes automatically. Page content is extracted as plain text and added to your Knowledge base.
{% endstep %}
{% endstepper %}

## Supported content

| Content type              | Supported |
| ------------------------- | --------- |
| Confluence pages          | Yes       |
| Folders and nested pages  | Yes       |
| Spaces (all pages within) | Yes       |
| Attachments               | No        |
| Comments                  | No        |

## How syncing works

* **Periodic sync** — Spara re-scans your selected spaces and folders on a regular interval to detect new and updated pages
* **HTML to text** — Confluence page content is stored as HTML internally. Spara extracts the plain text content for AI training, stripping out formatting markup
* **Space hierarchy** — Confluence's space and folder structure is preserved in the Spara Knowledge UI

## FAQ

### Which version of Confluence does Spara support?

Spara supports **Confluence Cloud** (hosted at `*.atlassian.net`). Confluence Data Center (self-hosted) is not supported.

### Can I sync from multiple spaces?

Yes. The file picker shows all spaces in your Confluence instance. You can select pages from any combination of spaces.


# Google Drive

How Spara integrates with Google Drive


# Notion

How Spara integrates with Notion.

Spara can sync documents from your Notion workspace to use as knowledge for your AI agents.

### Authentication

{% hint style="info" %}
You must be a Manager-level user to manage third party integrations.
{% endhint %}

Click the "Organization Settings" link in the left hand navigation bar. Then click the "Integrations" tab.

Click "Authorize" within the Notion module. This will lead you through a Notion authentication flow. There are no further steps necessary upon completing this flow. You should see that Spara is "Enabled" within Spara's Integrations page.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-e33b9e5b82b4e7c642a5d242d3669bc2bec9e1e8%2FScreenshot%202024-07-22%20at%204.24.44%E2%80%AFPM.png?alt=media" alt=""><figcaption><p>Click "Authorize" to integrate Notion with Spara.</p></figcaption></figure>

### Usage

Once connected, Spara can sync selected Notion pages and databases as knowledge sources for your AI agents. Synced documents are automatically kept up to date.

For more specific configuration options, please contact your customer support representative.


# Sharepoint

How to sync SharePoint documents to Spara for AI training.

Spara syncs documents from your SharePoint Online sites and document libraries to train your AI agents. Synced documents are added to your [Knowledge](/build/knowledge) base, giving agents the context they need to answer questions about your products, policies, and processes.

## Setup

{% stepper %}
{% step %}

### Connect SharePoint

Navigate to [**Settings > Integrations**](https://app.spara.co/settings/integrations) and click **Authorize** next to SharePoint, then choose how Spara should authenticate:

* **User Authentication (Delegated)** — sign in with a Microsoft account. Spara accesses SharePoint as that user, so it can only see what they can see, and the connection stops working if the user leaves or their password changes.
* **Application Authentication (App-Only / Unattended)** — Spara accesses SharePoint through an application registered in your Microsoft Entra tenant, with no user attached. Your IT admin controls exactly which sites the application can read. This is Microsoft's recommended setup for ongoing syncs. See [App-only access](#app-only-access) below for the setup.
  {% endstep %}

{% step %}

### Select documents

After connecting, use the file picker to browse your SharePoint sites, document libraries, and folders. Select the files and folders you want to sync. You can select entire folders to sync all supported files within them, including subfolders.
{% endstep %}

{% step %}

### Documents sync automatically

Spara periodically syncs your selected documents and folders, picking up new files and changes automatically. Documents are processed and added to your Knowledge base.
{% endstep %}
{% endstepper %}

## App-only access

App-only access ties the connection to an application your IT team registers in Microsoft Entra instead of to an individual's account. Permissions are set centrally and can be limited to specific SharePoint sites.

{% stepper %}
{% step %}

### Register an application in Microsoft Entra

In the [Azure portal](https://portal.azure.com), open **Microsoft Entra ID > App registrations** and click **New registration**. Give it a name like "Spara SharePoint sync" and register it for your organization only (single tenant). No redirect URI is needed.

From the app's **Overview** page, copy the **Application (client) ID** and the **Directory (tenant) ID**.
{% endstep %}

{% step %}

### Create a client secret

Open **Certificates & secrets > New client secret**, choose an expiry, and copy the secret **Value** right away — it is only shown once. Set a reminder to rotate it before it expires; when it does, reconnect SharePoint in Spara with the new secret.
{% endstep %}

{% step %}

### Grant application permissions

Open **API permissions > Add a permission > Microsoft Graph > Application permissions** and add one of:

| Scope            | Use when                                                 |
| ---------------- | -------------------------------------------------------- |
| `Sites.Selected` | You want to limit Spara to specific sites (recommended). |
| `Sites.Read.All` | Spara may read every site in the tenant.                 |

Then click **Grant admin consent** for your tenant.

If you chose `Sites.Selected`, a SharePoint administrator must also grant the application **read** access to each site Spara should sync. This is done with the Microsoft Graph [site permissions API](https://learn.microsoft.com/en-us/graph/api/site-post-permissions) or PnP PowerShell:

```powershell
Grant-PnPAzureADAppSitePermission -AppId "<client id>" -DisplayName "Spara SharePoint sync" -Site "https://contoso.sharepoint.com/sites/sales" -Permissions Read
```

{% endstep %}

{% step %}

### Connect in Spara

In Spara, click **Use app-only access** on the SharePoint card and enter the **Tenant ID**, **Client ID**, and **Client Secret** from the steps above.
{% endstep %}

{% step %}

### Add your sites

Sites granted through `Sites.Selected` do not appear in the site list, because the application is not allowed to browse the tenant. In the file picker, paste each site's URL into **Add a site by URL** to load it, then select its libraries and folders as usual.
{% endstep %}
{% endstepper %}

## Supported file types

| File type                        | Supported |
| -------------------------------- | --------- |
| Word documents (`.docx`, `.doc`) | Yes       |
| PDFs (`.pdf`)                    | Yes       |
| Text files (`.txt`)              | Yes       |
| Excel (`.xlsx`, `.xls`)          | No        |
| PowerPoint (`.pptx`, `.ppt`)     | No        |
| Images, videos, audio            | No        |

{% hint style="info" %}
When you select a folder, Spara syncs all supported file types within it and its subfolders. Unsupported file types (like images or Excel files) are skipped automatically.
{% endhint %}

## How syncing works

* **Periodic sync** — Spara re-scans your selected folders on a regular interval to detect new, modified, and deleted files
* **Folder hierarchy** — The folder structure from SharePoint is preserved in the Spara Knowledge UI for easy navigation
* **Deleted files** — If a file is removed from SharePoint, it is automatically removed from your Knowledge base on the next sync

## FAQ

### Can I sync from multiple SharePoint sites?

Yes. The file picker shows all sites in your SharePoint tenant. You can select documents from any combination of sites and libraries.

### How quickly do changes appear?

Document changes are picked up during the next periodic sync cycle. For immediate updates, you can trigger a manual sync from the Knowledge page.


# Google Analytics 4 (GA4) Integration

How Spara integrates with Google Analytics 4.

Spara fires conversion events into Google Analytics 4 so you can measure how much pipeline and revenue your AI conversations are driving. Once events are flowing, you can break down Spara conversions by traffic source, build funnel views, and pipe the same events into Google Ads or other ad platforms for smarter bidding.

The native integration sends five events to your GA4 property:

| Event name in GA4          | When it fires                                                 |
| -------------------------- | ------------------------------------------------------------- |
| `spara_loaded_via_spara`   | Spara loads on a page for a visitor                           |
| `lead_engaged_via_spara`   | A visitor sends their first message in a Spara conversation   |
| `email_captured_via_spara` | Spara captures a lead's email address (form, qualifier, etc.) |
| `calendar_shown_via_spara` | The booking calendar is displayed to the lead                 |
| `demo_scheduled_via_spara` | The lead books a meeting inside Spara                         |

## Choosing how to fire events

There are two ways to get Spara events into GA4. Pick one based on whether you need the events outside of GA4.

* **Spara native integration**: Spara sends the five events above directly from its servers to your GA4 property. Quick to set up and covers all five events, but events only land in GA4. Best when GA4 is your only destination.
* **JavaScript events via Google Tag Manager**: you subscribe to Spara's JavaScript events on your site and push them into the `dataLayer` yourself, under event names you choose. More setup, but the same event can fan out to GA4, Google Ads, Meta, LinkedIn, and any other tag you configure. Best for marketing teams running paid campaigns across multiple platforms.

{% hint style="warning" %}
Spara does not push anything into your page's `dataLayer` on its own. The native integration sends events server-side, so Google Tag Manager never sees them, and GTM triggers listening for the `_via_spara` event names will not fire. To use GTM, add the script in [#step-1-push-spara-events-into-the-datalayer](#step-1-push-spara-events-into-the-datalayer "mention").
{% endhint %}

The rest of this page covers both setup paths, then how to analyze the data once it's flowing.

## Option 1: Native integration

### Step 1: Authentication

{% hint style="info" %}
You must be a Manager- or Integrator-level user to manage third-party integrations.
{% endhint %}

Navigate to [**Settings > Integrations**](https://app.spara.co/settings/integrations) and click **Authorize** on the Google Analytics card to start the Google OAuth flow.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-8bf4ae957c843c9f4d78274157a4c062770d9ccc%2FScreenshot%202026-01-16%20at%201.43.35%E2%80%AFPM.png?alt=media" alt=""><figcaption></figcaption></figure>

After granting access, Google may show an unverified-app warning. You can either wait for Google to verify the app (this can take a few days) or bypass it by selecting **Advanced > Go to Spara** to continue.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-653da042fc98afe4b1e1ed9c85988db2009b0b59%2FScreenshot%202026-01-16%20at%2012.49.52%E2%80%AFPM.png?alt=media" alt="" width="375"><figcaption></figcaption></figure>

### Step 2: Configure Google Analytics

Select the GA4 property to receive Spara's conversion events and choose which of the five events to send.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-3f18dce6bdcf1e749a10b6adaf97ea40bbbaad91%2FGA4.png?alt=media" alt=""><figcaption></figcaption></figure>

That's it — Spara starts sending the selected events to your property on the next conversation.

## Option 2: Google Tag Manager

This path lets you forward Spara events to GA4 and any other tag in your container, such as Google Ads, Meta Pixel, or LinkedIn Insight Tag.

### Step 1: Push Spara events into the dataLayer

Add a script after the Spara embed script on your site that subscribes to Spara's events with `SparaActions` and pushes each one into the `dataLayer`. You choose the event names; the example below uses `spara_engaged`, `spara_email_captured`, and `spara_demo_scheduled`.

```html
<script type="text/javascript" src="https://app.spara.co/embed-<app_id>.js"></script>
<script>
  window.dataLayer = window.dataLayer || [];

  // onMessageSent fires on every message; only push the first one.
  var sparaEngaged = false;
  SparaActions.onMessageSent(function (e) {
    if (sparaEngaged) return;
    sparaEngaged = true;
    window.dataLayer.push({ event: 'spara_engaged', spara_form_factor: e.formFactor });
  });

  SparaActions.onEmailCaptured(function (e) {
    window.dataLayer.push({ event: 'spara_email_captured', spara_form_factor: e.formFactor });
  });

  SparaActions.onMeetingBooked(function (e) {
    window.dataLayer.push({ event: 'spara_demo_scheduled', spara_form_factor: e.formFactor });
  });
</script>
```

See [Developer: Javascript API](https://docs.spara.com/developers/spara-api/javascript-api) for every available event and its payload. To track when Spara loads, use the `Spara.onSparaLoad()` callback described on the same page.

{% hint style="info" %}
There is no JavaScript event for the booking calendar being shown, so a GTM-only setup cannot track the equivalent of `calendar_shown_via_spara`. Use the native integration if you need that event.
{% endhint %}

### Step 2: Get your GA4 Measurement ID

1. Log in to [analytics.google.com](https://analytics.google.com).
2. Click **Admin** (gear icon, bottom-left).
3. Navigate to **Data collection and modification > Data Streams**.
4. Open your website data stream and copy the **Measurement ID** (starts with `G-`).

### Step 3: Create the GA4 tag in GTM

1. Log in to [tagmanager.google.com](https://tagmanager.google.com) and open your workspace.
2. Click **Tags > New**.
3. Name the tag (e.g., `GA4 - Spara Event`).
4. Set **Tag Configuration > Google Analytics: GA4 Event**.
5. Paste your **Measurement ID** and set an **Event Name** (this is the name that appears in your GA4 reports — e.g., `spara_conversion`).

### Step 4: Configure the trigger

1. Click the **Triggering** box, then **+** to create a new trigger.
2. Name it (e.g., `Trigger - Spara Demo Booked`).
3. Set **Trigger Configuration > Custom Event**.
4. Set **Event Name** to the event name your script from Step 1 pushes (e.g., `spara_demo_scheduled`). The name must match your `dataLayer.push` call exactly.
5. **Save** the trigger.

To track multiple Spara events, repeat with a separate tag and trigger for each event name.

### Step 5: Publish

Save the tag, submit your container, and publish a new workspace version.

### Step 6: Verify with Preview mode

Before assuming everything works, test with GTM's **Preview** mode:

1. In your workspace, click **Preview** (top-right). Enter your site URL and click **Connect** — a new window opens with a "Tag Assistant Connected" badge.
2. In that window, perform the action Spara should fire for (e.g., book a demo through Spara).
3. Back in the Tag Assistant tab, look for your event name in the left-hand event list. Click it.
4. Under **Tags Fired**, confirm your GA4 - Spara Event tag is listed. If it's under **Tags Not Fired**, click in to see which trigger condition failed.

## Analyzing Spara conversions in GA4

Once events are flowing, mark `demo_scheduled_via_spara` as a primary conversion event in GA4 — a Spara-booked demo is the direct equivalent of a form-fill demo request and should be treated the same way in your reporting.

The examples below use the native integration's event names. If you send events through GTM, substitute the names your script pushes.

A few views that are worth knowing about:

* **Acquisition reports** — which traffic sources (paid, organic, social) drive Spara conversions.
* **Explore > Funnel exploration** — multi-step paths like "visited pricing → engaged with Spara → booked demo."
* **Explore > Segment overlap** — see which leads converted through Spara vs. through your form, and where they overlap.
* **Google Ads integration** — feed Spara conversion events back into Google Ads for smarter bidding.

{% hint style="info" %}
Keep your existing form-submit event firing alongside Spara events. Spara doesn't replace your form — and `lead_engaged_via_spara` often assists form fills that happen later in the session, after the lead's questions are answered.
{% endhint %}

### Building a funnel view

To see "did A then B at any point in the session" (not strictly adjacent steps), use a Funnel exploration:

1. Go to **Analytics > Explore > Blank exploration** and switch the **Technique** to **Funnel exploration**.
2. Click the ✏️ icon next to **STEPS** to open the funnel editor.
3. **Step 1**: name it `Session start`, add condition → event `session_start`. Leave "directly followed by" **off** so other events can occur in between.
4. **Step 2**: name it `Spara engaged`, add condition → event `lead_engaged_via_spara`.
5. **Step 3**: name it `Demo booked`, add condition → event `demo_scheduled_via_spara`.
6. Click **Apply**.

### Building a segment overlap

A segment overlap reveals whether the same users trigger two different events — useful for questions like "do leads who engage with Spara also book demos through our form?"

1. Go to **Analytics > Explore > Blank exploration** and switch the **Technique** to **Segment overlap**.
2. In the **Segments** panel, click **+ > New user segment**. Name it (e.g., "Triggered Event A"), set condition → **Event name exactly matches** `<event_a_name>`, save.
3. Repeat for the second event.
4. Drag both segments into the **Segments** slot of the **Tab settings** panel.
5. Optionally add a **Breakdown dimension**, set a date range — GA4 renders the Venn diagram and overlap table.

## Ad platform tracking: who owns what

Customers running paid ads almost always ask what Spara handles vs. what they need to wire up in GTM. Use this split.

**Your responsibility (in GTM and on your site):**

* **UTM parameters** — set these in your ad campaign URLs. Spara reads whatever is on the URL when a conversation starts.
* **Conversion pixels** — the Google Ads tag, Meta Pixel, LinkedIn Insight Tag, and others live in your GTM container and fire on the same Spara events. Map your demo-booked event (and any other Spara events you push) to each platform's conversion action.
* **Click IDs** — `gclid` (Google), `fbclid` (Meta), `li_fat_id` (LinkedIn), and `msclkid` (Microsoft) need to land on the page when Spara loads. Keep auto-tagging on and avoid redirects that strip them.
* **Cookie consent** — if you use a consent management platform (OneTrust, Cookiebot, etc.), you're responsible for the consent gate that allows Spara, GA4, and ad pixels to fire.

**Spara's responsibility:**

* Captures UTMs and click IDs present on the page when a conversation starts, stores them on the lead record, and includes them in lead exports.
* Sends the five events to GA4 when the native integration is connected, and exposes JavaScript events (`SparaActions`) that your site can push into the `dataLayer` for GTM.
* Passes lead data and attribution to your CRM.

## FAQ

### Which integration option should I pick?

If GA4 is your only destination, use the native integration — it takes minutes. If you're running paid ads on Google, Meta, LinkedIn, or any other platform that needs the same conversion signal, use GTM so a single event fans out to every tag in your container.

### Can I use both at once?

You can, but it's not recommended — you risk double-counting conversions. Pick the path that matches your reporting setup.

### Does Spara capture UTM parameters?

Yes. Spara captures UTMs and click IDs (`gclid`, `fbclid`, `li_fat_id`, `msclkid`) present on the page when a conversation starts, stores them on the lead record, and includes them in exports and CRM syncs.

### Which event should I mark as my primary conversion?

`demo_scheduled_via_spara` (or the demo-booked event your GTM script pushes). It's the direct equivalent of a demo-request form submit and should be treated the same way in GA4 and downstream ad platforms.


# Signals Integrations

Third-party data providers that identify and enrich the leads engaging with your Spara agents.

Signals integrations connect Spara to third-party data providers that resolve who is visiting your site and fill in what you know about them. The data flows directly into your [Leads](/pipeline/leads), where it powers agent personalization, workflow conditions, and CRM syncing.

Spara currently supports three Signals providers:

| Provider                                                       | What it does                                                                                | When it runs                                |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------- |
| [Vector (Deanonymization)](/integrations/signals/vector)       | Deanonymization: identifies the person visiting your site before they introduce themselves  | On page visit or chat engagement            |
| [Bombora (Deanonymization)](/integrations/signals/bombora)     | Deanonymization: resolves the visitor's company and firmographics (industry, size, revenue) | On every page visit (All Site Traffic mode) |
| [Explorium (Lead Enrichment)](/integrations/signals/explorium) | Lead enrichment: adds contact and company data to leads with a known work email             | When a lead's work email is captured        |

Vector and Bombora are the deanonymization providers, chosen with your Spara point of contact. Vector aims at person-level identity, Bombora at company-level firmographics, and an account deanonymizing all website visitors can run both.

{% hint style="info" %}
You can view your Signals configuration — and what each provider has returned for your Leads — under **Settings > Signals** in the Spara platform. Signals are managed by Spara: contact your CSM to enable a provider or change your configuration. Once enabled, the data flows automatically with no configuration required on your side.
{% endhint %}

## How the two providers work together

Deanonymization and enrichment are complementary stages of the same funnel:

1. **Vector** or **Bombora** makes the first guess at who an anonymous visitor is, using IP and identity-resolution signals. No email required.
2. **Explorium** fills in the full picture once a lead's work email is known, layering on verified contact and company data.

A single lead can benefit from both stages: deanonymization identifies them on their first visit, and Explorium enriches them the moment they share their email.

## Where the data lands

All Signals data is written to fields on the lead record, following the structure described in [Data Model](/build/data-model). That means it can be used anywhere lead fields are used:

* **Agent context** so agents can reference the lead's company, role, and background in conversation
* **Workflow conditions** in [Workflows](/build/workflows), for example enrolling visitors from target accounts
* **CRM syncing** through your [CRM Integrations](/integrations/crm-integrations) field mappings

For a walkthrough of how fields map to your CRM objects, see [Developer: Spara Objects & Fields](https://docs.spara.com/developers/data-model).


# Vector (Deanonymization)

Identify anonymous website visitors with Vector's identity resolution before they introduce themselves.

[Vector](https://www.vector.co) is Spara's [Deanonymization](/pipeline/leads/deanonymization) provider. When a visitor lands on a page where Spara is installed, Vector attempts to match them to a known person or company using privacy-safe identity resolution. A successful match gives your agents context about who they're talking to before the visitor has typed a single message, and can create a lead record for a visitor who never engages at all.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-232322d6f60f43a663830294e413861985838941%2FDeanonymization.png?alt=media" alt=""><figcaption><p>The Leads page distinguishes self-identified leads (green check) from deanonymized visitors (yellow warning).</p></figcaption></figure>

## Enabling Vector

Your current provider and trigger mode are visible under **Settings > Signals** in the Spara platform. The settings are managed by Spara: your Spara point of contact enables Vector for your account and configures which trigger mode applies:

| Mode                    | When it runs                                        | Notes                                                          |
| ----------------------- | --------------------------------------------------- | -------------------------------------------------------------- |
| Off                     | Never runs                                          |                                                                |
| On engagement (default) | When a visitor sends at least one message in chat   | Default for accounts with Vector enabled                       |
| All Site Traffic        | On every page visit, regardless of chat interaction | Additional charge; coordinate with your Spara point of contact |

Once enabled, matched data flows into your lead records automatically. There is nothing to configure on your side.

Each account runs one deanonymization provider at a time. If your team cares more about account-level signals than individual identities, [Bombora (Deanonymization)](/integrations/signals/bombora) is the company-level alternative.

## Fields captured

When Vector resolves a visitor, Spara writes the match to dedicated deanonymization fields on the lead record. Keeping these separate from visitor-provided fields means a probabilistic match never overwrites information the lead gave you directly.

| Field                             | Description                                             |
| --------------------------------- | ------------------------------------------------------- |
| Deanonymized First name           | Contact's first name, when matched at the person level  |
| Deanonymized Last name            | Contact's last name, when matched at the person level   |
| Deanonymized Email                | Business email when available, otherwise personal email |
| Deanonymized Job title            | Contact's current role                                  |
| Deanonymized Department           | Contact's functional area                               |
| Deanonymized LinkedIn URL         | Contact's LinkedIn profile                              |
| Deanonymized Company name         | Matched company                                         |
| Deanonymized Company domain       | Matched company's website domain                        |
| Deanonymized Company LinkedIn URL | Matched company's LinkedIn page                         |
| Deanonymized First visit at       | Timestamp of the visitor's first tracked visit          |
| Deanonymized Last visit at        | Timestamp of the visitor's most recent tracked visit    |
| Deanonymized Unique pages visited | Count of distinct pages the visitor has viewed          |

Spara also captures the visitor's browsing journey from Vector, including first-touch UTM parameters (source, medium, campaign, content, term), page view history, and audience segment membership. This journey data is stored on the lead's deanonymization profile.

All fields follow the structure described in [Data Model](/build/data-model). Not every field is populated on every match; person-level fields are only present when Vector resolves the specific individual, not just their company.

## Match rates

Deanonymization is probabilistic. Expect:

* **Person-level matches** on roughly 15 to 30% of US-based traffic, depending on your visitor base and Vector's coverage of that audience.
* **Company-level matches** at a meaningfully higher rate, since corporate IPs and networks resolve to a company even when the individual can't be identified.
* **US-only coverage.** Vector is geofenced to the United States to comply with US privacy regulations. International visitors are not matched.
* **Email is rarely returned.** Vector's dataset does not reliably include email addresses. Collecting email through the conversation remains the most reliable path to email capture.

## Using the data

Because Vector's matches are written as lead fields, they work everywhere fields work:

* **Workflow enrollment**: reference deanonymized fields in [Workflows](/build/workflows) conditions, for example "Deanonymized Company domain is defined", to act on visitors from target accounts even if they never chat.
* **CRM syncing**: map deanonymized fields to CRM properties in your [CRM Integrations](/integrations/crm-integrations) settings.
* **Lead review**: the [**Leads**](https://app.spara.co/leads) page includes an Identification filter to segment self-identified leads from deanonymized ones.

For how deanonymized leads appear in the platform, including identity confidence icons, see [Deanonymization](/pipeline/leads/deanonymization).

## FAQ

### Do I need to change my website to use Vector?

No code changes are needed beyond the standard Spara snippet. However, Vector requires customers to update their Privacy Policy and Consent Management Platform (CMP) to disclose the use of third-party data partners. Confirm with your Spara point of contact if you have not already done so.

### Can Vector data overwrite what a lead told us in chat?

No. Vector's matches are written to dedicated deanonymized fields, separate from visitor-provided fields. Visitor-provided data always takes precedence in the lead's identity.

### Is Vector compliant with privacy regulations?

Vector uses privacy-safe data sources and does not rely on third-party cookies. Vector is SOC 2 Type 2, GDPR, and CCPA compliant.


# Bombora (Deanonymization)

Resolve anonymous website visitors to their company with Bombora's firmographic data.

[Bombora](https://bombora.com) is an alternative [Deanonymization](/pipeline/leads/deanonymization) provider to [Vector (Deanonymization)](/integrations/signals/vector). Where Vector attempts to identify the specific person visiting your site, Bombora resolves the visitor's **company** and describes it with firmographic labels: industry, company size, and revenue, plus the visitor's professional group and seniority band.

Each account uses one deanonymization provider, chosen with your Spara point of contact. Bombora is a good fit when your team acts on account-level signals (which companies are visiting) rather than individual identities.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-232322d6f60f43a663830294e413861985838941%2FDeanonymization.png?alt=media" alt=""><figcaption><p>Deanonymized visitors appear on the Leads page alongside self-identified leads.</p></figcaption></figure>

## Enabling Bombora

Your current provider and trigger mode are visible under **Settings > Signals** in the Spara platform. The settings are managed by Spara: your Spara point of contact enables Bombora for your account.

{% hint style="info" %}
Bombora runs in **All Site Traffic** mode only: it resolves visitors on every page visit, whether or not they engage with chat. This mode carries an additional charge; coordinate with your Spara point of contact.
{% endhint %}

## Fields captured

When Bombora resolves a visitor's company, Spara writes the match to dedicated deanonymization fields on the lead record:

| Field                           | Description                                                    |
| ------------------------------- | -------------------------------------------------------------- |
| Deanonymized Company name       | Matched company                                                |
| Deanonymized Company domain     | Matched company's website domain                               |
| Deanonymized Industry           | Company's industry (e.g., Finance, Software)                   |
| Deanonymized Company size       | Employee-count band (e.g., "XXLarge (10,000+ Employees)")      |
| Deanonymized Revenue            | Annual revenue band (e.g., "XXLarge ($1B+)")                   |
| Deanonymized Professional group | Visitor's professional function (e.g., "Finance Professional") |
| Deanonymized Seniority          | Visitor's seniority band (e.g., "C-suite")                     |

These labels come from Bombora's fixed taxonomy, which is the same vocabulary Spara's condition builders offer as dropdown options. That means Bombora-resolved fields plug directly into workflow conditions and preview targeting without any value mapping on your side.

All fields follow the structure described in [Data Model](/build/data-model).

{% hint style="warning" %}
Bombora resolves companies, not people. It does not return the visitor's name, email, or LinkedIn profile. Professional group and seniority describe the visitor in aggregate terms, not their identity. If person-level identification matters more to your team, discuss [Vector (Deanonymization)](/integrations/signals/vector) with your Spara point of contact.
{% endhint %}

## Match rates

Bombora identifies at the company level, which resolves at a higher rate than person-level identification: corporate networks and IPs frequently map to a company even when the individual can't be identified. Actual rates depend on your visitor mix; traffic from home networks, mobile carriers, and VPNs is less likely to resolve. Your Spara point of contact can share expected coverage for your audience.

## Using the data

* **Workflow enrollment**: reference Bombora fields in [Workflows](/build/workflows) conditions, for example "Deanonymized Company size is XXLarge (10,000+ Employees)", to act on visits from your target segment.
* **CRM syncing**: map deanonymized fields to CRM properties in your [CRM Integrations](/integrations/crm-integrations) settings.
* **Lead review**: deanonymized visitors appear on the [**Leads**](https://app.spara.co/leads) page, where the Identification filter separates them from self-identified leads.

## FAQ

### How is Bombora different from Vector?

Vector attempts person-level identity resolution: names, emails, LinkedIn profiles. Bombora resolves the visitor's company and describes it with firmographic bands. Vector answers "who is this?"; Bombora answers "what kind of company is visiting, and what kind of role is this person in?"

### Can I use both Bombora and Vector?

Yes. An account deanonymizing all website visitors can run Vector, Bombora, or both; your Spara point of contact sets this under Settings → Signals. With both, Bombora resolves the visitor's company the moment they land, and if Vector later identifies the person, the lead takes Vector's company, name, title, and LinkedIn profile while Bombora's industry, company size, revenue, professional group, and seniority labels stay on the record. Accounts that deanonymize only engaged visitors run Vector alone.

### Do I need to change my website?

No code changes are needed beyond the standard Spara snippet, which loads Bombora's tag for enabled accounts. As with any third-party data partner, confirm your Privacy Policy and Consent Management Platform (CMP) disclosures with your Spara point of contact.


# Explorium (Lead Enrichment)

Enrich leads with verified contact and company data from Explorium the moment their work email is captured.

[Explorium](https://www.explorium.ai) is Spara's [Lead Enrichment](/pipeline/leads/lead-enrichment) provider. When a lead shares their work email address, whether typed in chat, submitted through a webform, or passed in via query parameters, Spara sends it to Explorium and enriches the lead record with verified contact and company data. Enrichment runs in the background and typically completes within seconds.

<figure><img src="https://4072969777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FreCGkFdsmuPJzGP9ZgGA%2Fuploads%2Fgit-blob-6bdca7c43d92a5fa5cd12f69ea2f9c82c5768e69%2FLead%20Enrichment.png?alt=media" alt=""><figcaption><p>Enriched company data in the Account section of the lead page.</p></figcaption></figure>

## Enabling Explorium

Enrichment shows as **On** under **Settings > Signals** in the Spara platform; like the rest of Signals it is managed by Spara, so there is nothing to configure on your side. Enrichment triggers automatically whenever a lead's work email is captured.

{% hint style="warning" %}
Enrichment requires a **work email address**. Personal email domains (Gmail, Yahoo, Outlook, Hotmail, etc.) are excluded because they can't be reliably matched to contact or company records.
{% endhint %}

## Fields captured

Explorium returns two layers of data: fields written directly to the lead record, and a richer enrichment profile shown on the lead page.

### Fields written to the lead

These fields are saved to the lead record, so they're available in workflow conditions, agent context, and CRM field mappings. A field is only written if it exists in your account's [Data Model](/build/data-model); if you've customized which fields your account collects, enrichment respects that configuration.

| Field                 | Description                                    |
| --------------------- | ---------------------------------------------- |
| First name            | From the contact's full name                   |
| Last name             | From the contact's full name                   |
| Job title             | Current role at their company                  |
| Seniority             | Level (e.g., Director, VP, C-Suite)            |
| Department            | Functional area (e.g., Engineering, Marketing) |
| Location              | City, region, and country                      |
| LinkedIn URL          | Contact's LinkedIn profile                     |
| Company name          | Matched from the email domain                  |
| Company website       | Company website URL                            |
| Company LinkedIn URL  | Company's LinkedIn page                        |
| Industry              | Primary industry classification                |
| Ticker                | Stock ticker, for public companies             |
| Address               | Company headquarters region and country        |
| Business email domain | The lead's company email domain                |

### Enrichment profile

Alongside the fields above, Spara stores a fuller profile that appears on the lead page and is available to your agents in conversation:

| Data                 | Description                                                      |
| -------------------- | ---------------------------------------------------------------- |
| Background           | Summary of current role, prior roles, and education              |
| Skills & interests   | Professional skills and interests from the contact's profile     |
| Revenue              | Estimated annual revenue range                                   |
| Headcount            | Approximate employee count range                                 |
| Business model       | Description of what the company does and how                     |
| Products             | Key products or value propositions                               |
| Corporate objectives | Strategic focus areas, drawn from public filings where available |
| Competitors          | Known competitors in their space                                 |

Not all fields are guaranteed on every match; availability depends on Explorium's coverage for each contact and company.

## Match rates

Explorium matches at two levels, and the rates differ:

* **Company-level matches** are domain-based, so most legitimate business email domains resolve. Expect coverage on the large majority of work emails.
* **Person-level matches** depend on the specific contact appearing in Explorium's dataset. Coverage is typically strongest for US-based contacts at established companies and lower for very small companies or newly created addresses.

When a person-level match fails, the lead keeps any company-level data that resolved, and enrichment can run again later if the lead's email changes.

## Using the data

* **Agent context**: agents reference enriched data in their responses, tailoring the pitch to the lead's company size, industry, or role.
* **Workflow conditions**: route leads in [Workflows](/build/workflows) based on enriched fields like seniority or industry.
* **CRM syncing**: enriched fields sync to your connected CRM through your [CRM Integrations](/integrations/crm-integrations) field mappings. See [Developer: Spara Objects & Fields](https://docs.spara.com/developers/data-model) for how fields map to CRM objects.

## FAQ

### How often does enrichment run?

Enrichment runs when a lead's work email is first captured, and again if their email address changes. Company data is refreshed periodically so information like revenue and headcount stays current.

### Will enrichment overwrite data the lead provided?

Enrichment fills in lead fields alongside conversation-gathered data. The lead's email address itself is never modified by enrichment.

### What's the difference between Explorium and Vector?

[Vector (Deanonymization)](/integrations/signals/vector) identifies anonymous visitors using IP and identity-resolution signals, with no email required. Explorium starts from a known work email and layers on verified contact and company data. Vector is the first guess at who someone is; Explorium fills in the full picture once you have a confirmed identity.


# Chat agent onboarding

Step-by-step guide to setting up and deploying Spara Chat agents on your website.

This page is a guide to getting started with Spara Chat agents.

### Step 1: Install AI Chat

Deploying AI Chat requires installing a Javascript snippet on your webpages. This should take a web engineer 5-15 minutes. After choosing which Chat interfaces you'd like to deploy, follow the installation guides listed above.

Spara Chat is designed to be deployed to your marketing website. Spara offers three different interfaces:

* [Installing Spara Navigator](/guides/installation-guides/readme/installing-spara-navigator)
* [Installing Smartbar](/guides/installation-guides/readme/installing-smartbar)
* [Installing Spara Fullscreen](/guides/installation-guides/readme/installing-spara-fullscreen)

These interfaces work together. For example, a lead may start a conversation on your Pricing page using [Spara Navigator](https://docs.spara.com/agents/channels/chat/spara-navigator). That same conversation might continue when the lead returns 48 hours later and engages with [Spara Navigator](https://docs.spara.com/agents/channels/chat/spara-navigator).

All interfaces rely on [Developer: Query Parameters](https://docs.spara.com/developers/spara-api/query-parameters) to ingest lead enrichment data. By supplying Spara with this information you ensure that Spara will a) not attempt to recapture this data, and b) may modify its behavior to better suit each conversation.

All interfaces also expose Spara events to your DOM via [Developer: Javascript API](https://docs.spara.com/developers/spara-api/javascript-api).

### Step 2: Configure a Chat agent

1. Navigate to [Chat](https://app.spara.co/settings/chat). This page lists all of your Chat agents.
2. Click "Create New." This will create a new Chat agent and load its Agent Editor page.
   1. Alternatively, you may duplicate an existing Chat agent by clicking on its "three dots" dropdown menu.

Let's pause. The Agent Editor page is split into two panes. The left hand side is the Agent Instructions, often called a "prompt." These are instructions, written in plain English, that tell the agent how to behave in any situation.

The right hand side is the Testing interface, which makes it easy to "pretend" to be your buyer so that you can verify your Chat agent is behaving as desired. It is side-by-side with the Agent Instructions on the left to make it easy to modify the agent's instructions as you test.

Ask Spara is a chat-like interface to assist you in configuring your agent, opening in its own panel beside the editor. You can ask it questions about your agent. Some actions in the Testing interface, such as clicking "thumbs down" for negative feedback, will open Ask Spara to provide more information.

Resuming our instructions...

3. Your new Chat agent comes prefilled with Agent Instructions. Read through them and update the text to fit the exact behavior you want from your agent.
4. Run your first test by clicking "New Test" in the Testing interface. Try to break the bot!


# Installing Spara Navigator

Step-by-step guide to installing the Spara Navigator chat interface on your website.

Spara Navigator is a bottom right corner chat interface built specifically to power MQL to SQL conversion on your marketing website.

{% hint style="info" %}
Do not add more than one Spara Javascript snippet to a page! If you have already installed a Spara product on this page skip to Step 2.
{% endhint %}

Copy your company's snippet from the [Chat > Configuration](https://app.spara.co/settings/chat/configuration) page. Paste your company's snippet inside the `<head>` tag for all pages of your marketing website.

Here is a full example of how to deploy Spara:

```html
<head>
<script type="text/javascript" src="https://app.spara.co/embed-<app_id>.js"></script>
</head>
```

#### Step 2: Remove any JavaScript-loaded elements <a href="#step-2-remove-any-javascript-loaded-elements" id="step-2-remove-any-javascript-loaded-elements"></a>

Pages with Spara Navigator should not contain any other JavaScript-loaded elements, such as chatbots like Intercom, Drift, or Qualified.

{% hint style="info" %}
Remove all chatbots! Spara will not be usable if they are present.
{% endhint %}

#### Step 3: (Optional) Tell Spara about your query parameters <a href="#step-3-optional-tell-spara-about-your-query-parameters" id="step-3-optional-tell-spara-about-your-query-parameters"></a>

You can tell Spara information you already have about the lead via query parameters. By supplying Spara with this information you ensure that Spara will not attempt to recapture this data, and will use this information to have a better conversation. See the [Developer: Query Parameters](https://docs.spara.com/developers/spara-api/query-parameters) documentation for more information.

#### Step 4: Turn on Spara Navigator <a href="#step-4-turn-on-spara-navigator" id="step-4-turn-on-spara-navigator"></a>

Toggle Navigator Deployment to "on" from the [Chat > Configuration](https://app.spara.co/settings/chat/configuration) page. Once turned on, Spara Navigator will start loading on your webpages.

You may also optionally blacklist Spara Navigator from loading on specific webpages by adding urls, including urls with wildcards, to the Navigator Blacklist.

You may also optionally specify an HTML element that sometimes "blocks" Spara Navigator from being seen by your website visitors. This is usually a cookie settings banner. Specifying this element will ensure that Spara Navigator is displayed immediately above the obstructing HTML element, and then moves back to its usual position once the obstructing HTML disappears (ex. your webpage visitor accept your cookie policy).

<figure><img src="https://3142139997-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGQgHUAQvtgVvwxqzOx4k%2Fuploads%2Fgit-blob-020a53d3b841c85430f417c99407373ae71d8851%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

## Go-live checklist

Before announcing Navigator to your team, run through this checklist to confirm Spara is loading correctly across your site.

* **Spara's JavaScript is embedded on every page where Navigator should appear.** Check that the embed script is present in the `<head>` of every relevant template, not just the homepage. If your site uses a tag manager, confirm the tag fires on all the right pages and is not scoped to a single route.
* **Whitelisting or blacklisting is configured.** If Navigator should load on most pages but skip a few (e.g., `/login`, `/checkout`), add those URLs to the Navigator Blacklist. If Navigator should only load on a specific section of the site (e.g., `/pricing/*`), use a whitelist pattern. Both lists support wildcards — see [Using Wildcard URL Patterns](/guides/platform-guides/using-wildcard-url-patterns).
* **Navigator Deployment toggle is turned on.** From [**Chat > Configuration**](https://app.spara.co/settings/chat/configuration), confirm the Navigator Deployment toggle is enabled. Navigator will not load on any page until this toggle is on, regardless of whether the embed script is present.
* **Visit a few live pages and confirm Navigator loads.** Open production pages in an incognito window and verify the Navigator avatar appears (or the configured Preview Mode renders). If you've configured cookie-banner offsets, accept and dismiss the cookie banner to confirm Navigator repositions correctly.

**FAQ for installing Spara AI Chat**

*Why is the Spara Javascript snippet inserted into the `<head>` tag?*

Spara's JS snippet can be inserted anywhere in your HTML. There's no hard requirement for it to be in the `<head>` tag. But `<head>` is common place for adding 3rd party scripts and it generally makes instructions simpler for our customers to follow.

*Why doesn't the Spara Javascript snippet come with `async`, `defer`, etc?*

Spara's Javascript snippet is actually just a bootloader script. It is extremely small (less than 1KB) and its main job is to append a larger script to the site after the page fully loads. Spara's embed system forces an `async` tag on the larger script, removing the possibility for the implementer to potentially make a mistake and hurt your site's performance. You can absolutely `async/defer` the embed script, but since Spara's subsequently loaded larger script already has `async`, you will see minimal performance impact.


# Installing Smartbar

Step-by-step guide to installing the Spara Smartbar on your marketing website.

Spara Smartbar is a customer-facing interface embedded directly on your marketing website. It lets customers ask questions - like having mini ChatGPT about your company easily accessible to your marketing leads.

### Step 1: Add Spara's script to your website

{% hint style="warning" %}
Do not add more than one Spara Javascript snippet to a page! If you have already installed a Spara product on this page skip to Step 2.
{% endhint %}

Copy your company's snippet from the [Chat > Configuration](https://app.spara.co/settings/chat/configuration) page. Paste your company's snippet inside the `<head>` tag for all pages of your marketing website.

Here is a full example of how to deploy Spara:

```html
<head>
  <script type="text/javascript" src="https://app.spara.co/embed-<app_id>.js"></script>
</head>
```

### Step 2: Identify where to load Smartbar

* Add an empty div element with `id="spara-smartbar-root"` to the html body. Spara Smartbar will load inside this div as a full section of your marketing website.
  * You may have multiple Spara Smartbar elements on the same page.
  * You may have both Spara Smartbar and Spara Navigator on the same page. Your website visitors will experience this as a single conversation.

Here is a full example of effective code to deploy Spara Smartbar:

```html
<head>
    <script type="text/javascript" src="https://app.spara.co/embed-<app_id>.js"></script>
</head>
<body>
    <div class="marketing-hero">...</div>
    <div id="spara-smartbar-root"></div>
    <div class="marketing-section">...</div>
</body>
```

#### Using Single Page Applications (SPAs)

If your site is a **Single Page Application**, the target div may not be present in the Document Object Model (DOM) when the Spara script auto-initializes. This can prevent the Smartbar from appearing, so here are two options to resolve this behavior:

**Option 1: Manually call `window.SparaActions.initSmartbar()`** ***after*****&#x20;the target div is rendered**

* Once your app has rendered the target div `<div id = "spara-smartbar-root">`, manually trigger Smartbar initialization by calling the **`window.SparaActions.initSmartbar()`** function

Example code in React:

```html
const onRootLoad = React.useCallback((el) => {
  if (el) {
    window.SparaActions.initSmartbar()
  }
}, [])

...

<div id="spara-smartbar-root" ref={onRootLoad} />
```

\
**Option 2: Ensure `spara-smartbar-root` target div is rendered&#x20;*****before*****&#x20;the script loads**

* If you can control when the Spara embed script is added to the page, make sure the target div `<div id = "spara-smartbar-root">` is already in the DOM before the script runs.
* This allows the script's automatic initialization to detect the div immediately, so the Smartbar appears without delay

#### FAQ for installing Spara AI Chat

*Why is the Spara Javascript snippet inserted into the `<head>` tag?*

Spara's JS snippet can be inserted anywhere in your HTML. There's no hard requirement for it to be in the `<head>` tag. But `<head>` is common place for adding 3rd party scripts and it generally makes instructions simpler for our customers to follow.

*Why doesn't the Spara Javscript snippet come with `async`, `defer`, etc?*

Spara's Javascript snippet is actually just a bootloader script. It is extremely small (less than 1KB) and its main job is to append a larger script to the site after the page fully loads. Spara's embed system forces an `async` tag on the larger script, removing the possibility for the implementer to potentially make a mistake and hurt your site's performance. You can absolutely `async/defer` the embed script, but since Spara's subsequently loaded larger script already has `async`, you will see minimal performance impact.


# Installing Spara Fullscreen

Step-by-step guide to installing the Spara Fullscreen chat interface on your website.

Spara's Fullscreen interface is exactly what it sounds like: a full screen chat interface powered by Spara's AI. This interface is deployed onto a single URL of your company's marketing website. It's most often used for post-web form submission flows.

{% hint style="info" %}
Do not add more than one Spara Javascript snippet to a page! If you have already installed a Spara product on this page skip to Step 2.
{% endhint %}

Copy your company's snippet from the [Chat > Configuration](https://app.spara.co/settings/chat/configuration) page. Paste your company's snippet inside the `<head>` tag for all pages of your marketing website.

Here is a full example of how to deploy Spara:

```html
<head>
<script type="text/javascript" src="https://app.spara.co/embed-<app_id>.js"></script>
</head>
```

### Step 2: Add Spara Fullscreen div

Add a `div` with `id="spara-iframe-root"`. This is the HTML element that Spara Fullscreen will load in. It should be the only HTML element in the webpage `body`.

Here is a full example:

```html
<head>
  <script type="text/javascript" src="https://app.spara.co/embed-<app_id>.js"></script>
</head>
<body>
  <div id="spara-iframe-root"></div>
</body>
```

### Step 3: Redirect to Spara Fullscreen with Query Parameters

When loading or redirecting the Spara Fullscreen interface page include any lead enrichment data as query parameters to the iframe URL. By supplying Spara with this information you ensure that Spara will a) not attempt to recapture this data, and b) may modify its behavior to better suit each conversation. See the [Developer: Query Parameters](https://docs.spara.com/developers/spara-api/query-parameters) documentation for more information.

The most common use case is to redirect to Spara Fullscreen from a marketing webform.

{% hint style="info" %}
Contact your Spara customer service representative if you need help with this step.
{% endhint %}

### Step 4: Remove any JavaScript-loaded elements

This page should not contain any other JavaScript -loaded elements, such as chatbots like Intercom, Drift, or Qualified. Most platforms provide an easy mechanism to "blacklist" specific URLs, meaning that the chatbot will not load for a specific URL.

{% hint style="warning" %}
Remove all chatbots! Spara will not be usable if they are present.
{% endhint %}

### Step 5 (Optional): Javascript Events

Should you wish to track Spara events using a third party analytics tools, refer to [Developer: Javascript API](https://docs.spara.com/developers/spara-api/javascript-api).

#### FAQ for installing Spara AI Chat

*Why is the Spara Javascript snippet inserted into the `<head>` tag?*

Spara's JS snippet can be inserted anywhere in your HTML. There's no hard requirement for it to be in the `<head>` tag. But `<head>` is common place for adding 3rd party scripts and it generally makes instructions simpler for our customers to follow.

*Why doesn't the Spara Javscript snippet come with `async`, `defer`, etc?*

Spara's Javascript snippet is actually just a bootloader script. It is extremely small (less than 1KB) and its main job is to append a larger script to the site after the page fully loads. Spara's embed system forces an `async` tag on the larger script, removing the possibility for the implementer to potentially make a mistake and hurt your site's performance. You can absolutely `async/defer` the embed script, but since Spara's subsequently loaded larger script already has `async`, you will see minimal performance impact.


# Email agent onboarding

Step-by-step guide to setting up and activating your Spara Email agent.

This page is a guide to getting started with Spara Email agents. For a refresher on how Chat agents work, please see [Agent Overview](https://docs.spara.com/build/agents) and [Email agents](https://docs.spara.com/build/channels/email).

### Step 1: Connect email address

Spara Email agents send emails from an authenticated email address.

* Navigate to the [Email Configuration](https://app.spara.co/settings/email) page
* Authenticate your email provider, either Gmail or Microsoft Outlook
* Set up the specific email address that Spara will manage
* To verify the connection can send, open the connected account's manage page and use **Send test email**. Spara sends a test message from the connected mailbox to an address you choose — check that inbox to confirm it arrived.

For example...

* ACME authenticates Gmail as their email provider...
* ...and configures Spara to send all emails from `spara@acme.com`

### Step 2: Configure an Email agent

Email agents are designed to *respond* to incoming emails. Define how you'd like Spara to respond to emails by writing out a prompt in the Reply Agent tab.

### Step 3: Build a workflow

Workflows are how Spara's AI knows when to send outgoing emails, among other things. See [Workflows](https://docs.spara.com/build/workflows) to learn more - use the "Send Email" step!


# Text agent onboarding

Step-by-step guide to registering your Twilio messaging campaign and setting up Spara Text agents.

This page walks you through the onboarding process for Spara Text agents. Spara uses **Twilio** to send and receive SMS messages on your behalf. Before your text agent can go live, Twilio requires that your brand and messaging campaign are registered and approved — this is an industry-wide compliance requirement to protect consumers from unwanted messages.

For a refresher on how Text agents work, see [Agents Overview](https://docs.spara.com/build/agents) and [SMS](https://docs.spara.com/build/channels/sms).

## Overview

Twilio's **A2P 10DLC** (Application-to-Person 10-Digit Long Code) registration process ensures that businesses sending text messages through standard US phone numbers are verified and compliant. The process has three parts:

1. **Brand registration** — Twilio verifies your business identity.
2. **Campaign registration** — Twilio reviews how you plan to use messaging.
3. **Phone number assignment** — Once approved, Spara provisions a phone number for your text agent.

Your Spara CSM handles the registration on your behalf, but you'll need to provide the information below.

{% hint style="info" %}
The registration and approval process typically takes **3–7 business days** depending on Twilio and carrier review times. Plan accordingly when scheduling your text agent launch.
{% endhint %}

## What you need to provide

Send the following information to your Spara CSM to begin the registration process.

### 1. Campaign description

A clear explanation of how your organization will use Spara to send text messages. This is reviewed by Twilio and mobile carriers to ensure compliance.

Your description should cover:

* **Who receives texts** — e.g., inbound leads who submit a form on your website, existing customers who opt in to text communication
* **What texts contain** — e.g., follow-up messages encouraging leads to schedule a meeting, answers to product questions, appointment confirmations
* **How contacts opt in** — e.g., by submitting a web form that includes SMS consent language, by texting your number first

**Example campaign description:**

> We use Spara's AI text agent to engage inbound sales leads who opt in through our website contact form. Texts include follow-up messages encouraging leads to schedule a meeting, responses to product questions, and appointment confirmations. Contacts opt in by submitting a form that includes explicit SMS consent.

### 2. Terms of Service and Privacy Policy

Provide public URLs to:

* **Terms of Service** — Must be publicly accessible on your website.
* **Privacy Policy** — Must be publicly accessible on your website.

Both documents must include:

* **Explicit SMS opt-in language** — A clear statement that users consent to receive text messages by taking a specific action (e.g., submitting a form, checking a box). The opt-in must not be buried in unrelated terms.
* **Message frequency disclosure** — e.g., "Message frequency varies" or "You may receive up to X messages per month."
* **Opt-out instructions** — e.g., "Reply STOP to unsubscribe from text messages at any time."
* **"Message and data rates may apply"** — This standard carrier disclosure is required.
* **Contact information** — A way for recipients to reach you with questions about your messaging program (email or phone number).

{% hint style="warning" %}
Your Terms of Service and Privacy Policy must **not** authorize the following use cases, which are prohibited by Twilio and mobile carriers:

* Third-party or affiliate marketing messages
* Messages on behalf of another company or brand
* High-risk financial services (payday loans, debt collection)
* Cannabis or CBD-related messaging
* Gambling-related messaging
* Messages containing links to age-gated content

If your documents include language that could be interpreted as authorizing these use cases, your campaign may be rejected.
{% endhint %}

**Example opt-in language for your website form:**

> By submitting this form, you consent to receive automated text messages from \[Your Company] at the phone number provided. Message frequency varies. Message and data rates may apply. Reply STOP to opt out at any time. View our \[Privacy Policy] and \[Terms of Service].

### 3. Sample text messages

Provide **3 example text messages** that represent the types of texts your agent will send. These help Twilio and carriers understand your messaging content.

**Examples:**

1. > Hi \[First Name], thanks for reaching out! I'd love to help you learn more about \[Product]. Do you have a few minutes to chat, or would you prefer to schedule a call? Reply STOP to opt out.
2. > Hey \[First Name], just following up on your inquiry about \[Product]. We have availability this week if you'd like to set up a quick demo. Here's a link to book a time: \[calendar link]. Reply STOP to opt out.
3. > Hi \[First Name], thanks for booking a demo with us! You're confirmed for \[Date] at \[Time]. We'll send a reminder before the call. Let me know if you have any questions. Reply STOP to opt out.

{% hint style="info" %}
Every text message must include opt-out language (e.g., "Reply STOP to opt out"). Spara automatically appends this to outgoing messages if it is not already present in the message body.
{% endhint %}

## After approval

Once your brand and campaign are approved by Twilio:

1. Your Spara CSM will provision a phone number and assign it to your organization.
2. Configure your text agent in the [Agent Editor](https://docs.spara.com/build/channels/configuring/ai-instructions) with instructions for how it should respond to incoming texts.
3. Build [Workflows](https://docs.spara.com/build/workflows) using the [Send Text Step](https://docs.spara.com/build/workflows/steps/send-text) to automate outgoing texts.

## FAQ

**How long does approval take?**\
Typically 3–7 business days, depending on Twilio and carrier review times.

**Can I use a toll-free number instead of a local number?**\
Yes — toll-free numbers have a separate verification process. Ask your Spara CSM about toll-free options if you prefer a toll-free number.

**What happens if my campaign is rejected?**\
Your Spara CSM will share the rejection reason and help you update your campaign description or policy documents to address the issue. Most rejections are resolved by updating opt-in language or clarifying the campaign use case.

**Do I need a separate campaign for each phone number?**\
Not typically. A single campaign registration can cover multiple phone numbers as long as they are used for the same messaging purpose.


# Voice agent onboarding

This page walks you through getting a Spara Voice agent live — from phone number registration to your first test call. The process is self-service and takes about 15–30 minutes.

For a refresher on how Voice agents work, see [Agents](https://docs.spara.com/build/agents) and [Phone](https://docs.spara.com/build/channels/phone).

## Overview

A live Voice agent needs three things:

1. **A phone number** — Registered in your organization's settings.
2. **Agent instructions and abilities** — What the agent says and what it can do (book meetings, transfer calls, etc.).
3. **A published version** — Draft changes don't affect live calls until you publish.

{% hint style="info" %}
Unlike Text agents, Voice agents do not require a Twilio A2P registration or carrier approval process. You can go live as soon as your phone number is registered and your agent is configured.
{% endhint %}

## Step 1: Register a phone number

Navigate to **Settings > Voice > Configuration**. This is where your organization manages all phone numbers used by Voice agents, Text agents, and Workflows.

Click **Add phone number** to register a new number. Once registered, the number is available across your account — you'll assign it to a specific agent in a later step.

{% hint style="info" %}
If you plan to run multiple Voice agents (e.g., one for sales and one for support), register a separate phone number for each. Each number can only be assigned to one published Voice agent at a time.
{% endhint %}

{% hint style="warning" %}
**Planning to use this agent for outgoing calls?** Ask your Spara representative to kick off **branded calling onboarding** as soon as you start setting up the agent. Branded calling registers your account with the telephony network so outgoing calls show your business — not "Spam Likely" — on the recipient's phone. It typically takes several days to complete, so start early. See [Branded caller ID for outgoing calls](https://docs.spara.com/build/channels/phone#branded-caller-id-for-outgoing-calls) for details.
{% endhint %}

## Step 2: Create a Voice agent

Navigate to **Voice** in the left sidebar and click **New voice agent**. Give it a name that reflects its purpose — e.g., "Inbound Sales Qualifier" or "Demo Follow-Up."

## Step 3: Write instructions

The **Instructions** tab defines how the agent behaves on calls. Write in natural language, the same way you'd brief a new sales rep.

A good starting prompt covers:

* **Greeting and identification** — How the agent introduces itself and confirms it's speaking with the right person.
* **Qualification questions** — What the agent asks to determine if the lead is a fit.
* **Handling common questions** — How to respond to pricing, product, and competitor questions.
* **Next steps** — What the agent does with qualified leads (book a meeting, transfer to a rep) vs. unqualified leads (thank them, end politely).
* **Boundaries** — What the agent should never do (make up pricing, promise features, etc.).

**Example:**

```
You are a sales assistant for Acme Corp. Your goal is to qualify inbound 
leads and schedule demos with Account Executives.

- Introduce yourself: "Hi, this is Alex from Acme Corp. Thanks for calling!"
- Confirm you're speaking with the right person.
- Ask what prompted their interest and what problem they're trying to solve.
- If they're a good fit (B2B company, 50+ employees, looking for a solution 
  in the next 3 months), offer to schedule a demo using the calendar tool.
- If they're not a fit, thank them politely and end the call.
- Never make up pricing or feature details. Say "I'll make sure our team 
  follows up with that information" if you don't know.
```

See [Writing Effective Agent Prompts](/guides/platform-guides/writing-effective-agent-prompts) for more best practices.

## Step 4: Add abilities

On the **Abilities** tab, add the tools your agent needs:

* **Calendar** — Let the agent check availability and book meetings by conversation. The agent reads open slots aloud and books when the lead confirms a time. A Calendly integration is automatically created for new voice agents — you can change the provider or customize it here.
* **Transfer** — Route calls to reps or teams. Configure named destinations (e.g., "Sales", "Support", a specific rep) using the dropdown in the transfer tool settings. The agent picks the right destination based on the conversation.
* **API Request** — Call an external API during the conversation — for example, to look up an order or check account status. Configure the URL and parameters ahead of time.

You can add multiple abilities. Most voice agents start with Calendar and Transfer.

## Step 5: Configure voice and call settings

On the **Configuration** tab:

1. **Choose a voice provider and voice.** Spara supports ElevenLabs and Deepgram. Each offers a range of voices — pick one that matches your brand. You can adjust speed, stability, and similarity to fine-tune how it sounds.
2. **Set up a privacy warning** (recommended). Configure a custom call recording disclosure that plays at the start of each call. You can customize the message text and select a specific voice for the disclosure, independent of the agent's main voice. This is important for compliance with call recording consent laws in your jurisdiction.
3. **Configure additional settings:**
   * **Voicemail** — Enable the agent to leave a scripted voicemail when a lead doesn't answer an outgoing call.
   * **Interruption handling** — Control whether the lead can interrupt the agent mid-sentence and how sensitive the detection is.
   * **Re-engagement** — The agent speaks again if the lead goes silent, keeping the conversation moving.
   * **Max call duration** — Set a time limit for calls (defaults to 10 minutes).

## Step 6: Assign a phone number

On the **Configuration** tab, assign one of your registered phone numbers to this agent. This is the number the agent answers incoming calls on and uses as the caller ID for outgoing calls.

All outgoing numbers automatically accept callbacks — if a lead misses your call and dials back, the same agent picks up with the lead's full context.

## Step 7: Test your agent

Spara offers two ways to test before going live:

**Browser test call.** Click **Test** in the agent editor to start a live conversation with your agent directly in the browser. This is the fastest way to iterate on your instructions.

**Outbound test call.** From the voice testing dashboard, send a real outbound call to a phone number you specify. This lets you hear the full experience as a lead would — including caller ID, privacy warning, voicemail, and callback behavior.

Both test modes use the **draft** version of your agent, so you can make changes and re-test without affecting anything live.

**What to listen for:**

* Does the greeting sound natural?
* Does the privacy warning play correctly?
* Does the agent ask the right questions in the right order?
* Can the agent handle pushback or unexpected answers?
* Do abilities work (calendar booking returns real slots, transfers connect)?
* Does the voice sound right at the configured speed and stability?

Test calls are recorded and appear in the agent's call history for review.

## Step 8: Publish

When you're satisfied with testing, click **Publish**. Only the published version handles real incoming and outgoing calls.

Each publish creates a new entry in the agent's **version history**, so you can track what changed and when. If something goes wrong, you can review prior versions to understand what shifted.

## After going live

Once your agent is published and a phone number is assigned, it's live. Here's what to do next:

* **Set up workflows for outgoing calls.** Use the [Call Phone](https://docs.spara.com/build/workflows/steps/call-phone) step in [Workflows](https://docs.spara.com/build/workflows) to have the agent proactively call leads — for example, immediately after a form submission or 30 minutes before a scheduled demo.
* **Monitor call outcomes.** Call results appear on each lead's timeline in [Leads](https://docs.spara.com/pipeline/leads) — including whether the call was answered, transferred, or resulted in a booked meeting.
* **Use Ask Spara to debug.** **Ask Spara** opens beside the agent editor and lets you chat with an AI about why your agent behaved a certain way on a specific call. This is the fastest way to diagnose issues.
* **Review recordings.** Listen to real calls to identify where the agent needs prompt improvements. All calls are recorded and transcribed.
* **Iterate on your prompt.** Edit the Instructions tab, re-test, and publish a new version. Version history tracks every change.

## FAQ

**How long does it take to go live?**\
15–30 minutes. There is no carrier registration or approval process for Voice agents — once your phone number is registered and your agent is published, it's live.

**Can I have multiple voice agents on different phone numbers?**\
Yes. Register a separate phone number for each agent in **Settings > Voice > Configuration**, then assign each number to its agent on the Configuration tab.

**What happens if a lead calls back an outgoing number?**\
The same Voice agent that placed the outgoing call automatically answers. The agent has the lead's full context from the original call attempt.

**Do I need to set up a calendar integration manually?**\
Not for Calendly — a Calendly integration is automatically created when you create a new voice agent. If you want to use Cal.com or another provider, you can change it on the Abilities tab.

**Are calls recorded?**\
Yes. All voice calls are recorded and transcribed. Recordings and transcripts are available on the lead's timeline in [Leads](https://docs.spara.com/pipeline/leads).

**How do I handle compliance for call recording?**\
Configure a privacy warning on the Configuration tab. This plays a custom disclosure at the start of each call. Consult your legal team for the specific language required in your jurisdiction.


# Building Your First Agent

A step-by-step walkthrough of assembling an Agent from capabilities and workflows.

An **Agent** in Spara solves a complete business problem by coordinating [capabilities](https://docs.spara.com/build/channels) (the channels it engages buyers through) and [workflows](https://docs.spara.com/build/workflows) (the automated sequences it runs). This guide walks through assembling one from the [**Agents**](https://app.spara.co/agents) page. For background on the model, see [Agents Overview](https://docs.spara.com/build/agents).

<figure><img src="https://3142139997-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGQgHUAQvtgVvwxqzOx4k%2Fuploads%2Fgit-blob-66b8cdbf8a240744253741b65e672d081a32edfd%2FBuilding%20an%20Agent.png?alt=media" alt=""><figcaption><p>An Agent's detail page: its Goal, capabilities grouped by trigger, and workflows.</p></figcaption></figure>

{% stepper %}
{% step %}

### Set the Goal

Open an Agent and give it a **Name** and a **Goal**. The Goal is a short, plain-language description of the business outcome the Agent is responsible for, for example "Qualify inbound leads from paid traffic and book them into a demo." Everything you add to the Agent should serve that Goal.
{% endstep %}

{% step %}

### Add capabilities

Click **Add capability** and choose a channel:

* **Chat**: a website chat experience ([Spara Navigator](https://docs.spara.com/build/channels/chat/spara-navigator), [Smartbar](https://docs.spara.com/build/channels/chat/spara-smartbar), or [Fullscreen](https://docs.spara.com/build/channels/chat/spara-fullscreen))
* **Email**: automated replies and outreach cadences
* **Phone**: incoming and outgoing AI phone calls
* **SMS**: text-message conversations
* **Product Demo**: a live, voice-narrated product walkthrough

Each capability opens in its own editor, where you configure its instructions, abilities, and trigger. See [Configuring Capabilities](https://docs.spara.com/build/channels/configuring).

Capabilities are listed by channel and grouped by their **trigger**, the condition that activates them. Chat capabilities are grouped by the page they appear on, Phone and SMS by their phone number, and Email by the address they reply from. Grouping by trigger is also how [A/B tests](https://docs.spara.com/build/channels/configuring/a-b-testing) are organized: variants that share a trigger split that trigger's traffic.
{% endstep %}

{% step %}

### Add workflows

Click **Add workflow** to build an automated sequence the Agent runs in the background, for example "After a lead submits the demo form, send an email, wait a day, then place a follow-up call." Workflows are made of [steps](https://docs.spara.com/build/workflows/steps) and appear in their own section of the Agent, separate from capabilities. See [Configuring Workflows](https://docs.spara.com/build/workflows/configuring) for the editor and settings.
{% endstep %}

{% step %}

### Publish

Capabilities and workflows each have a private draft and a published version. Leads only ever interact with the published version. Edit and [test](https://docs.spara.com/build/channels/configuring/testing) freely, then publish when you're ready. See [Saving & Publishing](https://docs.spara.com/build/channels/configuring/saving-and-publishing).
{% endstep %}
{% endstepper %}

## FAQ

### Does an Agent need both capabilities and workflows?

No. Many Agents start with a single capability (a Chat capability on your homepage, say) and add more over time. Workflows are optional and used when you need automated, time-based follow-up.

### How many capabilities can one Agent have?

There's no fixed limit. Add a capability for each channel and trigger the Agent needs to cover. Keep them aligned to the Agent's Goal; unrelated work belongs in a separate Agent.

### How do I move a capability or workflow to a different Agent?

Use the capability or workflow's menu and choose **Move to Agent**, then pick the destination Agent.


# How to Use Spara's Text Editor

How to personalize content with variables, AI instructions, and calendar links across the Spara platform.

Spara's text editor appears wherever you write content that gets sent to leads — email bodies, SMS messages, workflow steps, and agent instructions. It includes formatting tools and a powerful Insert Menu for personalizing content with lead data.

## The Insert Menu (⚡)

The **bolt icon** (⚡) in any text field opens the Insert Menu. This menu lets you insert dynamic content at your cursor position without typing variable names manually.

The Insert Menu has up to three tabs depending on context:

### Variables

The Variables tab lists all available lead data fields, organized by category. Click any field to insert it as a variable. For example, clicking "First name" inserts `{{ first_name }}`.

Available categories include Lead Info, Account Info, Website Activity, Email Activity, Phone Activity, Meeting Activity, and more. For a complete list of all fields and their API names, see [Developer: Spara Objects & Fields](https://docs.spara.com/developers/data-model).

In workflows, the Variables tab also shows **Workflow Outputs** — data extracted by upstream API or Prompt steps. These are only visible in steps that come after the step that produces them.

### AI

The AI tab lets you insert AI-powered instructions into your content. This is used in email sequences to tell Spara's AI how to compose or customize parts of the message dynamically. Options include pre-defined behaviors from your agent configuration and a free-text field for custom instructions.

### Schedule Call

The Schedule Call tab lists your configured calendar links (Cal.com, Calendly, Chili Piper, etc.). Click one to insert a scheduling link that Spara renders as a calendar widget for the lead.

## Variable Syntax

Variables use double curly braces:

```
{{ variable_name }}
```

For example:

```
Hi {{ first_name }}, thank you for checking out {{ last_page_visited }}.
```

...becomes `Hi Sarah, thank you for checking out /pricing` when sent.

If a variable has no value for a lead, it renders as an empty string.

## Formatting

The text editor supports basic formatting via a floating toolbar that appears when you select text:

* **Bold** and *Italic*
* Ordered and unordered lists
* Hyperlinks

## Writing AI Instructions

Several places in Spara use a text editor for writing AI instructions — natural language prompts that tell your agents how to behave. These include:

* **Agent Editor** — The main prompt that defines your Chat, Email, Voice, or Text agent's personality, goals, and rules. See [AI Instructions](https://docs.spara.com/agents/channels/configuring/ai-instructions).
* **Workflow Research steps** — Custom AI instructions that run against lead data to classify, research, or extract information. See [Research Step](https://docs.spara.com/agents/workflows/steps/research).
* **Email sequences** — AI instructions embedded in email templates tell the agent how to personalize or vary the content.
* **Workflow Send Email and Send Text steps** — AI instructions embedded in the body tell the agent how to personalize that part of the message. Keep them short on Send Text: the result has to fit in a text message.

When writing AI instructions, be specific and direct. For example, instead of "be helpful," write "Answer the lead's question using only information from the knowledge base. If you don't know the answer, offer to connect them with a sales rep."

## Where the Text Editor Appears

| Location              | What you're writing              | Insert Menu tabs available                  |
| --------------------- | -------------------------------- | ------------------------------------------- |
| Workflow — Send Email | Email subject and body           | Variables; AI and Schedule Call in the body |
| Workflow — Send Text  | SMS message body                 | Variables, AI, Schedule Call                |
| Workflow — Notify     | Slack/Teams notification message | Variables                                   |
| Workflow — API        | Request URL, headers, and body   | Variables                                   |
| Workflow — Prompt     | AI instructions                  | Variables                                   |
| Email sequences       | Email subject and body           | Variables, AI, Schedule Call                |
| Agent Editor          | Agent behavior instructions      | N/A (plain text)                            |


# Using Media in Chat Agents

How to upload media files and configure your chat agent to show them at the right moment in a conversation.

Spara chat agents (Navigator, Smartbar, and Fullscreen) can show videos, images, and PDFs mid-conversation. When a lead asks for a demo, a case study, or a pricing overview, the agent surfaces the file automatically in a side panel — no manual triggering needed.

This guide walks through uploading a file, writing trigger conditions, and verifying it works in a live test.

For background on how media works, see [Media](https://docs.spara.com/platform/media).

{% stepper %}
{% step %}

#### Upload your file

Go to [**Media**](https://app.spara.co/media) and click **Upload File**. Select the video, image, or PDF you want to add.

Supported formats: mp4, mov, png, jpg, gif, pdf.
{% endstep %}

{% step %}

#### Name the file

Give the file a clear, lead-facing name. This is what Spara displays to the lead when the file is shown.

Use something descriptive and professional:

* "Product Overview" (not "v3\_final\_USE THIS.mp4")
* "Enterprise Case Study — Acme Corp"
* "Pricing and Packages"
  {% endstep %}

{% step %}

#### Write your "When" conditions

The **When** field tells the AI when to show this file. Write a bulleted list of trigger conditions in plain language.

**Example for a product demo video:**

```
- Lead asks to see a product demo or walkthrough
- Lead asks "what does it look like" or "can you show me"
- Lead expresses interest in understanding how the platform works
```

**Example for a pricing PDF:**

```
- Lead asks about pricing, cost, or subscription plans
- Lead wants to compare tiers or understand what's included
- Lead is evaluating whether to move forward
```

Be specific. Broad conditions like "lead shows interest" will cause the file to appear too early or too often.
{% endstep %}

{% step %}

#### Set visibility to Visible

Toggle the file to **Visible** to make it active. Files set to **Hidden** won't be shown by any agent, even if the trigger conditions match.
{% endstep %}

{% step %}

#### Test in Navigator (or your preferred chat interface)

Go to [**Testing**](https://app.spara.co/testing) and open a chat test for your Navigator (or Smartbar, or Fullscreen) agent.

Start a conversation and steer it toward a trigger condition you defined. For example, if your condition is "lead asks for a product demo," send a message like:

> "Can you show me how the product works?"

If the media panel opens on the left side of the chat, your configuration is working. If it doesn't appear, try rephrasing or broadening your "When" description, then test again.
{% endstep %}
{% endstepper %}

## Tips

* **One file per use case.** A demo video, a pricing PDF, and a case study should each be separate files with focused "When" conditions.
* **Review real conversations.** If leads are seeing a file at the wrong moment, check the "When" description and tighten it.
* **Hidden = archived, not deleted.** If you stop using a file, set it to Hidden rather than deleting it. You can reactivate it later without re-uploading.


# Writing Effective Agent Prompts

Best practices for writing natural language instructions that make your Spara agents perform well.

Every Spara agent — Chat, Email, Voice, and Text — is powered by a natural language prompt that defines how it behaves. The prompt is the single most important factor in your agent's performance. This guide covers how to write prompts that convert.

## Prompt Structure

The Agent Editor organizes your prompt into collapsible sections using markdown headings. Common sections include:

* **Goal** — The agent's primary objective and success criteria
* **Brand Guidelines** — Voice, tone, and trust rules that stay consistent across agents
* **Agent Persona** — The identity, role, and demeanor the agent should adopt

You can create additional sections with `#` (primary) and `##` (subsection) headings.

The Agent Editor's **AI Instructions** tab is where you write your prompt. It displays your instructions with line numbers for easy reference, alongside testing tools on the right.

<figure><img src="https://3142139997-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGQgHUAQvtgVvwxqzOx4k%2Fuploads%2Fgit-blob-9b64dc690ae57a562b6362eceb0171359f31a7f1%2FAgent%20Editor%20-%20Prompt.png?alt=media" alt=""><figcaption><p>The AI Instructions tab in the Agent Editor showing a Chat agent prompt.</p></figcaption></figure>

## Writing Principles

{% stepper %}
{% step %}

#### Be specific about the goal

Bad: "Be helpful and answer questions."

Good: "Your goal is to qualify incoming leads by determining fit, urgency, and intent — then route qualified leads to a scheduled call and give non-fits a clear, respectful outcome."
{% endstep %}

{% step %}

#### Give concrete instructions, not vague guidance

Bad: "Ask good questions."

Good: "Ask about their current solution, timeline for making a change, and who else is involved in the decision. Never ask more than one question at a time."
{% endstep %}

{% step %}

#### Define what NOT to do

Agents follow positive instructions well, but explicit guardrails prevent common mistakes:

* "Never invent product capabilities or pricing that aren't in the knowledge base."
* "Never propose a meeting without confirmed interest."
* "If you don't know the answer, say so and offer to connect them with a sales rep."
  {% endstep %}

{% step %}

#### Keep it scannable

Use short sentences, bullet lists, and numbered steps. Avoid long paragraphs — agents interpret structured instructions more reliably than prose.
{% endstep %}

{% step %}

#### Test and iterate

Use the Testing interface in the Agent Editor to simulate conversations. Click the **?** icon to understand why the agent responded a certain way, or the thumbs-down icon to get specific improvement suggestions from Ask Spara.
{% endstep %}
{% endstepper %}

## Example: Chat Agent Goal Section

```
Your goal is to qualify incoming leads by determining fit, urgency, and intent — 
then route good fits to a booked call with sales and give non-fits a clear, 
respectful outcome.

- Identify whether the lead matches the ideal customer profile based on 
  company size, role, and use case.
- Assess buying intent by uncovering budget, timeline, and decision-making authority.
- Move qualified leads toward a scheduled call; never propose a meeting 
  without confirmed interest.
- Route nurture leads into a follow-up sequence with a clear reason for 
  future re-engagement.
- Disqualify gracefully: explain why it's not a fit and offer alternative 
  resources when possible.
```

## Where Prompts Are Used

| Feature                                                                               | What you're writing                                                            |
| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| [AI Instructions](https://docs.spara.com/agents/channels/configuring/ai-instructions) | The core behavior for Chat, Email, Voice, and Text agents                      |
| [Research Step](https://docs.spara.com/agents/workflows/steps/research)               | Custom AI instructions that classify leads, research accounts, or extract data |
| Email sequences                                                                       | AI instructions that personalize automated email content                       |

## Tips

* **Start simple.** Write a short prompt, test it, then add specificity where the agent underperforms.
* **Use the knowledge base.** Don't put product details in the prompt — upload them to [Knowledge](https://docs.spara.com/platform/knowledge) and let the agent reference them.
* **Separate shared from unique.** Brand Guidelines and Agent Persona can be shared across agents. Keep the Goal section unique to each agent's purpose.
* **Review real conversations.** The best prompt improvements come from reading actual lead conversations and identifying where the agent missed.


# Building Your First Workflow

A step-by-step walkthrough for creating your first Spara workflow.

This guide walks you through creating a simple workflow that emails a lead after they submit a webform, waits a day, and then has a Voice agent call them. By the end, you'll understand how triggers, steps, and settings work together.

For a full feature reference, see the [Workflows](https://docs.spara.com/agents/workflows) page.

## Before You Start

Make sure you have:

* At least one agent configured (Chat, Email, or Voice)
* An email template in mind for the first outreach
* A Voice agent set up if you want to include a Call Phone step

{% stepper %}
{% step %}

#### Create a new workflow

Navigate to **Workflows** in the left sidebar and click **New workflow**. Give it a descriptive name like "Webform Follow-up."
{% endstep %}

{% step %}

#### Configure the trigger

Click the **Triggers** step at the top of the canvas. This defines which leads enter the workflow.

Add a criteria row:

* Field: **Webform submitted**
* Operator: **is true**

This means any lead who submits a webform will enter the workflow. You can add more criteria with the **+ Add criteria** button — for example, requiring that the lead also has an email address.

Click **+ Add condition group** to create OR logic between groups of criteria.
{% endstep %}

{% step %}

#### Add a Send Email step

Click the **+** button below the trigger to add a step. Choose **Send Email**.

In the configuration panel:

* Set **To** to "Lead"
* Write a subject line using variables: `Following up on your interest, {{ first_name }}`
* Write the email body. Use the ⚡ button to insert variables like company name or the page they visited.

See the [How to Use Spara's Text Editor](/guides/platform-guides/how-to-use-sparas-text-editor) for details on inserting variables.
{% endstep %}

{% step %}

#### Add a Wait step

Click **+** below the Send Email step and choose **Wait**. Set the duration to **1 Day**. This gives the lead time to read the email before the next step.
{% endstep %}

{% step %}

#### Add a Call Phone step

Click **+** below the Wait step and choose **Call Phone**. Select your Voice agent and outgoing phone number. The agent will call the lead and follow its own instructions.

{% hint style="warning" %}
If a lead doesn't have a phone number, this step is skipped automatically.
{% endhint %}
{% endstep %}

{% step %}

#### Review workflow settings

Click the **Settings** tab at the top. By default, Spara exits leads from the workflow when they reply to an email, respond to a text, or answer a call. This is usually what you want — it prevents leads from receiving follow-ups after they've already engaged.
{% endstep %}

{% step %}

#### Save and publish

Click **Save draft** to save your work. When you're ready to go live, click **Publish**. Spara will flag any configuration errors that need fixing.

Leads matching your trigger criteria will start entering the workflow immediately after publishing.
{% endstep %}
{% endstepper %}

## What's Next

* Add a [Condition Step](https://docs.spara.com/agents/workflows/steps/condition) to branch logic based on lead data (e.g., different paths for enterprise vs. SMB)
* Use a [Research Step](https://docs.spara.com/agents/workflows/steps/research) to research the lead's company and personalize downstream emails
* Add a [Notify Step](https://docs.spara.com/agents/workflows/steps/notify) to alert your sales team in Slack when a lead progresses


# Setting Up Voice Agents

How to configure a Voice agent for incoming and outgoing phone calls.

This guide walks you through configuring a Spara Voice agent to handle phone calls with your leads. Voice agents can answer incoming calls and make outgoing calls through workflows.

For a full feature reference, see the [Voice Agents](https://docs.spara.com/agents/channels/phone) reference page.

{% stepper %}
{% step %}

#### Register phone numbers

Before creating a voice agent, make sure your organization has at least one phone number registered. Work with your Spara rep to have a number procured and/or added to your organization.

{% hint style="info" %}
Each phone number can only be assigned to one published voice agent at a time. If you plan to run multiple voice agents (e.g., one for sales and one for support), register a separate number for each.
{% endhint %}
{% endstep %}

{% step %}

#### Create a Voice agent

Navigate to **Voice** in the left sidebar and click **New voice agent**. Give it a descriptive name like "Sales Qualifier" or "Demo Scheduler."
{% endstep %}

{% step %}

#### Write instructions

The Instructions tab is where you define how the agent behaves on calls. Write in natural language — the same way you'd brief a new sales rep.

Example:

```
Your goal is to confirm the lead's interest, answer basic questions about
Spara, and schedule a demo with an Account Executive.

- Introduce yourself and confirm you're speaking with the right person.
- Ask what prompted their interest and what they're looking for.
- If they're qualified, offer to schedule a demo. Use the calendar tool.
- If they're not a good fit, thank them and end the call politely.
- Never make up product capabilities or pricing.
```

See the [Writing Effective Agent Prompts](/guides/platform-guides/writing-effective-agent-prompts) for best practices.
{% endstep %}

{% step %}

#### Add abilities

The **Abilities** tab is where you add capabilities like calendar booking, transfers, and API requests. Click **Add ability** and choose from:

* **Calendar** — Let the agent check availability and book meetings by conversation. The agent reads available slots aloud and books when the lead confirms. When you create a new voice agent, a Calendly integration is automatically set up. You can change the calendar provider or customize the integration here. Other supported providers include [Cal.com](https://docs.spara.com/integrations/calendar-integrations/cal.com) and additional options listed in [Calendar Integrations](https://docs.spara.com/integrations/calendar-integrations).
* **Transfer** — Route calls to reps or teams. Cold transfers forward the call directly; warm transfers connect the rep first while the lead stays on the line. You configure transfer destinations using a single transfer tool with a dropdown to select from multiple named destinations (e.g., "Sales", "Support", a specific rep). The agent routes to the right team based on the conversation. See [Voice Agents — Transfer](https://docs.spara.com/agents/channels/phone#transfer).
* **API Request** — Let the agent call external services during the conversation (e.g., look up order status, check inventory). Configure the URL and parameters ahead of time.
  {% endstep %}

{% step %}

#### Configure voice and call settings

On the **Configuration** tab, choose your voice provider and voice. Spara supports ElevenLabs and Deepgram for text-to-speech — each offers a range of voices with different characteristics. You can adjust speed, stability, and similarity to fine-tune how natural the agent sounds.

This tab also has settings for:

* **Privacy warning** — Configure a custom call recording disclosure that plays at the start of each call. You can customize the message text and select a specific voice for the warning, separate from the agent's main voice. This is important for compliance with call recording consent laws.
* **Voicemail** — Enable the agent to leave a scripted voicemail when a lead doesn't answer.
* **Interruption handling** — Control whether the lead can interrupt the agent mid-sentence.
* **Re-engagement** — The agent speaks again if the lead goes silent.
* **Max call duration** — Set a time limit for calls (defaults to 10 minutes).

See [Voice Agents — Voice and call settings](https://docs.spara.com/agents/channels/phone#voice-and-call-settings) for details.
{% endstep %}

{% step %}

#### Assign a phone number

On the **Configuration** tab, assign one of your registered phone numbers to this agent. This is the number the agent answers incoming calls on and uses as the caller ID for outgoing calls.

To handle incoming calls, select a number and any lead who calls it will be connected to this Voice agent.

For outgoing calls, the agent is triggered through a [Call Phone](https://docs.spara.com/agents/workflows/steps/call-phone) workflow step — you select the Voice agent and outgoing number when configuring the step. All outgoing numbers also automatically accept callbacks, so if a lead misses your call and dials back, the same agent picks up with full context.
{% endstep %}

{% step %}

#### Test and publish

Spara offers two ways to test your voice agent:

**Browser test call.** Click **Test** in the agent editor to start a test web call directly in your browser. This lets you have a live conversation with your agent to verify it sounds right.

**Outbound test call.** Use the voice testing dashboard to send a real outbound call to a phone number you specify. This lets you experience the full call flow exactly as a lead would — including caller ID, privacy warning, voicemail behavior, and callback.

Both test modes use the **draft** version of your agent — any unpublished changes will be reflected. This means you can iterate on your prompt and abilities without affecting live calls.

Things to listen for during testing:

* Does the agent introduce itself correctly?
* Does the privacy warning play as expected?
* Does it ask the right qualifying questions?
* Does it handle common objections from your prompt?
* Do abilities work as expected (calendar booking, transfers)?
* Does the voice sound natural at the configured speed and stability?

Test calls are recorded — you can play them back from the agent's call history to review.

When you're satisfied, click **Publish** to make the agent live. Only the published version handles real incoming and outgoing calls. Each publish creates a new entry in the agent's version history, so you can track changes over time and see who published what.
{% endstep %}
{% endstepper %}

## Tips

* **Start with a narrow scope.** A voice agent that does one thing well (e.g., schedule demos) outperforms one that tries to handle everything.
* **Enable Document Search.** This lets the agent answer product questions accurately using your knowledge base instead of guessing.
* **Use Ask Spara to debug.** Ask Spara opens beside the agent editor and lets you chat with an AI about why your agent behaved a certain way. Use it as your first stop when something sounds off.
* **Pair with workflows.** Use [Call Phone](https://docs.spara.com/agents/workflows/steps/call-phone) steps in workflows to have the agent proactively call leads — for example, 30 minutes before a scheduled demo as a reminder.
* **Run multiple agents on separate numbers.** If you need different behavior for sales vs. support calls, create separate voice agents and assign each to its own phone number.
* **Review call recordings.** Listen to real calls to identify where the agent needs prompt improvements.

## Handling off-hours calls

There is no platform-level business hours toggle for voice. The agent always answers when a lead calls. To handle off-hours calls differently, include time-of-day logic in your agent's instructions — for example:

```
If it is after 6pm Eastern or before 8am Eastern, tell the lead our team
is offline and offer to book a callback for the next business day. Use
the calendar tool to schedule. Do not transfer to the sales queue.
```

The agent has access to the current time and timezone and can branch on it.

## SMS compliance

Outgoing SMS requires registering an A2P 10DLC campaign with the carriers. If you plan to use [Send Text](https://docs.spara.com/agents/workflows/steps/send-text) steps as voice follow-ups, your Spara account team will guide you through the registration process — including the opt-in language, terms of service, and privacy policy that the carriers require. Allow several days for approval before you launch.


# Using Wildcard URL Patterns

How to use wildcard URL patterns to target groups of pages on your website.

When configuring Spara features that target specific pages on your website (like preview messages), you don't need to add every URL individually. Wildcard patterns let you target entire sections of your site with a single entry.

## How wildcards work

Add `/*` to the end of a URL path to match that path and all pages beneath it. Spara uses simple path prefix matching, not regular expressions.

| Pattern       | What it matches                                                  |
| ------------- | ---------------------------------------------------------------- |
| `/blog/*`     | `/blog`, `/blog/my-post`, `/blog/2026/april/update`              |
| `/products/*` | `/products`, `/products/enterprise`, `/products/pricing/details` |
| `/docs/*`     | `/docs`, `/docs/getting-started`, `/docs/api/reference`          |
| `/*`          | Every page on your site                                          |
| `/pricing`    | Only `/pricing` (exact match, no wildcard)                       |

You can also include the full domain to restrict matching to a specific subdomain:

| Pattern                          | What it matches                      |
| -------------------------------- | ------------------------------------ |
| `https://www.example.com/blog/*` | Only blog pages on `www.example.com` |
| `https://docs.example.com/*`     | All pages on `docs.example.com`      |

{% hint style="info" %}
Trailing slashes are ignored when matching. `/blog` and `/blog/` are treated as the same path.
{% endhint %}

## Where wildcards are used

### Preview messages

Preview messages (the pop-up message that appears when a lead visits a page) can be targeted to specific URLs using the **criteria** field. Set the criteria variable to `current_url` and the value to a wildcard pattern like `/blog/*` to show a customized preview message on all blog pages.

For more on preview messages, see [Chat agents](https://docs.spara.com/agents/channels/chat).

## Example: Different previews for different sections

You might configure three previews for your Navigator chat agent:

1. **Product pages** (`/products/*`) — "Want to see how this works for your team? Let's chat."
2. **Blog pages** (`/blog/*`) — "Have questions about this topic? I can help."
3. **Default** (no criteria) — "Hi there! How can I help you today?"

Spara evaluates previews in order. The first preview whose criteria matches the lead's current URL is shown. The default preview (with no criteria) acts as a catch-all for pages that don't match any other pattern.


# Downloading Chat Transcripts

How to download full chat transcripts using Spara's API.

You can download full chat transcripts for all leads in two ways:

1. **From the Spara platform** — use the **Export CSV** button on the Leads or Analytics page. This is the easiest option and does not require any technical setup.
2. **Via the Web API** — run a `curl` command against Spara's API. Use this when you need to script exports or pull data on a recurring basis.

## Option 1: Export from the platform

The Export CSV flow is available anywhere you can see a filtered list of leads — including the [**Leads**](https://app.spara.co/leads) page and the [**Analytics**](https://app.spara.co/analytics) page. Filters applied on the page (date range, agent, lead stage, etc.) carry through into the export.

{% stepper %}
{% step %}

#### Open the export modal

Apply any filters you want (date range, agent, lead stage, etc.), then click the **Export** button in the top-right of the page.
{% endstep %}

{% step %}

#### Choose what to include and your timeframe

Pick **Full transcript** to include the complete conversation history for each lead, or **Overview only** for a lighter export with conversation summary, stage, and key lead details. Then choose a timeframe preset (Last 7 / 14 / 30 days, All time) or set a custom date range. The modal shows how many leads will be included so you can verify before exporting.

<figure><img src="https://3142139997-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGQgHUAQvtgVvwxqzOx4k%2Fuploads%2Fgit-blob-64d99b689a8072b139a21c1c2dd90175a9ddf596%2FAnalytics%20Export%20Modal.png?alt=media" alt=""><figcaption><p>The Export modal lets you choose between Full transcript and Overview only, and pick a timeframe before downloading.</p></figcaption></figure>
{% endstep %}

{% step %}

#### Download the CSV

Click **Download CSV**. The file contains one row per lead with their fields, conversation transcript (if Full transcript is selected), and activity history.
{% endstep %}
{% endstepper %}

## Option 2: Export via the Web API

Use the Web API when you want to script exports, schedule recurring pulls, or integrate transcript data into your own systems.

{% stepper %}
{% step %}

#### Create an API key

Navigate to [**Settings > API & Webhooks**](https://app.spara.co/settings/api-webhooks) in the Spara platform and click **Create API key**. Copy the key - you will paste this key into the curl command shown below.
{% endstep %}

{% step %}

#### Choose your date range

Decide the time range you want to export. You'll need the start and end times as [Unix timestamps](https://www.unixtimestamp.com/) (seconds since January 1, 1970).

For example:

* April 1, 2026 at midnight UTC = `1743465600`
* April 7, 2026 at midnight UTC = `1743984000`

**Note:** Responses are limited to a maximum of **1,000 leads per request**. In order to get more than 1,000 leads, you will need to make multiple requests and split up the start and end times.
{% endstep %}

{% step %}

#### Run the export command

Open your terminal and run the following command. Replace `YOUR_API_KEY` with the key you created, and update the `start` and `end` values with your Unix timestamps:

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.spara.co/v1/leads/search?start=1743465600&end=1743984000" \
  -o ~/Desktop/leads-export.json
```

This saves a JSON file to your Desktop containing all leads and their conversation history within the specified date range.
{% endstep %}

{% step %}

#### Review the output

Open `leads-export.json` in any text editor or JSON viewer to browse the exported data. Each lead includes their fields, conversation messages, and activity history.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Keep your API key secure. Anyone with the key can access your organization's lead data. If a key is compromised, delete it in Settings and create a new one.
{% endhint %}

For more details on the Web API, see [Developer: Web API](https://docs.spara.com/developers/spara-api/web-api).


# Product Demo Use Cases

Common deployment patterns for Spara's Product Demo capability — from website CTAs to outbound campaigns and in-app onboarding.

The [Product Demo](https://docs.spara.com/agents/channels/product-demo) capability delivers interactive, voice-narrated demos to your prospects. This guide covers the most common ways to deploy it — each pattern solves a different go-to-market challenge and takes only a few minutes to set up.

For technical details on the JavaScript methods used below, see [Developer: Javascript API](https://docs.spara.com/developers/spara-api/javascript-api).

## Convert Website Visitors into Pipeline

**The problem:** Buyers arrive mid-evaluation with strong purchase intent, yet leave without converting. Static forms and generic landing pages fail to surface the product experience needed to drive pipeline.

**The solution:** Embed a CTA button (e.g., "Start AI Demo") directly on your website. When a visitor clicks it, the Product Demo launches in a fullscreen overlay — no navigation away from your site, no form fill, no scheduling friction.

### How to set it up

{% stepper %}
{% step %}
**Add a button to your page with a unique ID**

Place the button wherever you want the CTA to appear (hero section, pricing page, product page, etc.):

```html
<button id="demo-cta">Start AI Demo</button>
```

{% endstep %}

{% step %}
**Add a click handler after your Spara embed script**

Your Spara embed script can be found in [**Settings > Chat > Configuration**](https://app.spara.co/settings/chat/configuration). Add the following JavaScript after it:

```javascript
document.getElementById('demo-cta')?.addEventListener('click', () => {
  SparaActions.openProductDemo();
});
```

When a visitor clicks the button, `SparaActions.openProductDemo()` launches the Product Demo in a fullscreen overlay. With no argument it uses your account's default selection.

To open one specific demo instead, pass your agent ID:

```javascript
SparaActions.openProductDemo("xyz123");
```

Find the agent ID by opening the Product Demo agent in the Spara platform and clicking the folder icon in the header. See [Developer: Javascript API](https://docs.spara.com/developers/spara-api/javascript-api) for the full reference, including pinning one specific variant when the agent runs an A/B test.
{% endstep %}
{% endstepper %}

## Turn Outgoing Sequences into Interactive Experiences

**The problem:** Outgoing sequences generate opens but not responses. Reps default to generic homepage links that lack relevance, causing prospect engagement to drop off.

**The solution:** Drop a direct link to the Product Demo in your cold emails, LinkedIn messages, or SMS campaigns. Recipients click and immediately experience an interactive, personalized product demo — no form fill, no scheduling friction. The demo acts as a self-serve first touchpoint that warms the prospect before your reps follow up.

### How to set it up

Add `?spara_demo_open` to any page on your site that already loads the Spara script:

```
https://yoursite.com/?spara_demo_open
```

Link to it in your outgoing emails, LinkedIn messages, or SMS campaigns. When a recipient clicks, your landing page loads and the Product Demo opens automatically. No code to add — the Spara script handles it.

To open one specific demo instead of your account's default selection, give the parameter your agent ID (`?spara_demo_open=xyz123`). Find it by opening the Product Demo agent in the Spara platform and clicking the folder icon in the header.

See [Developer: Javascript API](https://docs.spara.com/developers/spara-api/javascript-api) for the full reference, including pinning a specific demo variant.

## Convert Chat Conversations into Product Demos

**The problem:** Conversational interfaces excel at top-of-funnel qualification, but fall short when buyers are ready to evaluate the product. The inability to transition from chat to a live product experience results in drop-off at peak purchase intent.

**The solution:** Enable the Product Demo as a suggested action inside your Spara Navigator chat widget. Visitors can click "Start product demo" directly from the chat interface to launch the demo — zero code changes required on your end. Buyers who are already engaged get a natural next step to see the product live.

### How to set it up

Ask your Spara CSM to enable the Product Demo as a suggested action in the Navigator chat widget. Once enabled, it appears automatically — no changes are required on your end.

## Accelerate Sales Cycles with a Pre-Sales Demo Link

**The problem:** Sales cycles lose momentum between calls when prospects have no way to explore the product independently. Scheduling friction extends deal timelines and creates openings for competitive displacement.

**The solution:** Host the Product Demo on a private, non-indexed page that only exists for those with the direct link. Reps share this URL in follow-up emails or deal sequences, and prospects can explore the product on their own time before the next call — no public exposure and no sales engineering required.

### How to set it up

{% stepper %}
{% step %}
**Create a non-indexed page on your website**

In your CMS or website builder (Webflow, WordPress, HubSpot, etc.), create a new blank page with a simple, non-descriptive URL (e.g., `yourcompany.com/demo-preview`).
{% endstep %}

{% step %}
**Exclude the page from search engines**

Add a `noindex` meta tag to the page's `<head>`, or use the built-in "hide from search engines" toggle in your CMS. Do not link to the page from your navigation or anywhere else on your site.
{% endstep %}

{% step %}
**Add the Product Demo to the page**

Follow the steps in [#convert-website-visitors-into-pipeline](#convert-website-visitors-into-pipeline "mention") to embed the Spara script and a CTA button on this page. Alternatively, use the `?spara_demo_open` query parameter approach from [#turn-outgoing-sequences-into-interactive-experiences](#turn-outgoing-sequences-into-interactive-experiences "mention") to open the demo automatically when the page loads.
{% endstep %}

{% step %}
**Share the link**

Share the page URL (optionally with `?spara_demo_open` appended) in follow-up emails or deal sequences. Only people with the direct link can access it.
{% endstep %}
{% endstepper %}

## Accelerate Customer Onboarding In-App

**The problem:** New customers often struggle to understand product capabilities during onboarding, resulting in slower time-to-value, more support requests, and increased reliance on CSMs. Traditional onboarding approaches like documentation and live training sessions are difficult to scale.

**The solution:** Embed the Product Demo directly inside your product or customer portal as an in-app widget. New users can launch it at any time to get an interactive walkthrough of features, ask questions in natural language, and get instant answers — without leaving your platform.

### How to set it up

Implementation varies depending on your product's architecture. Work with your Spara CSM to determine the best approach for your use case.

## FAQ

### Can I use more than one of these patterns at the same time?

Yes. Each pattern is independent. You can embed a CTA on your marketing site, use the `?spara_demo_open` link in outbound emails, enable the chat suggested action, and host a private demo page — all simultaneously, all pointing to the same Product Demo capability.

### Do I need to create separate Product Demo capabilities for each use case?

No. A single Product Demo capability works across all deployment patterns. The demo content, features, and visuals are shared regardless of how the prospect reaches it.

### How do I track which channel is driving demo sessions?

Use different query parameters for each channel (e.g., `?spara_demo_open&utm_source=email`, `?spara_demo_open&utm_source=linkedin`) so your analytics platform can attribute sessions to the right source.


# Connect Spara to Claude or ChatGPT

Connect Claude or ChatGPT to your Spara workspace to inspect, analyze, and safely draft changes to your agents.

Connect Spara to Claude or ChatGPT to explore your Agents and channels, analyze performance, and prepare configuration changes for review. You can also ask product questions using Spara's public documentation.

## Before you connect

You need:

* A Spara account and membership in the workspace you want to use
* A supported client: the Claude app or Cowork, or ChatGPT on the web or in the desktop app
* A Contributor, Editor or Manager role in Spara if you want to create Agents or channels, or draft configuration changes. Members and Integrators can use the read and analytics tools. See [User Management](https://docs.spara.com/platform/settings/user-management) for role details.

ChatGPT web and desktop use different setup paths. On the web, connect directly to Spara's MCP server. In the desktop app, install Spara from its plugin marketplace. Availability depends on your ChatGPT plan, workspace permissions, and selected interface.

For managed AI workspaces, an administrator may need to enable Spara before members can connect:

* **ChatGPT managed workspaces**: An administrator may need to allow developer mode and custom MCP connections for web setup, or import the Spara marketplace and make the desktop plugin available to your role.
* **Claude Team and Enterprise**: A Claude Owner or Primary Owner must first add Spara for the Claude organization.

## Install and connect Spara

Spara's public plugin repository is [spara-ai/spara-plugins](https://github.com/spara-ai/spara-plugins). Use `spara-ai/spara-plugins` for marketplace installation, not `spara-ai/spara-app`.

{% tabs %}
{% tab title="ChatGPT web" %}
Connect directly to Spara's MCP server using ChatGPT developer mode. This gives ChatGPT access to Spara's tools without installing the desktop plugin bundle.

{% stepper %}
{% step %}

### Enable developer mode

Open [ChatGPT](https://chatgpt.com), then **Settings > Security and login**, and turn on **Developer mode**. If this option is unavailable, ask your ChatGPT workspace administrator about access to custom MCP connections.
{% endstep %}

{% step %}

### Create the Spara connection

Open [ChatGPT Plugins](https://chatgpt.com/plugins) and select the **+** button to add an MCP server. Name it **Spara**, add a short description, and enter this server URL:

```
https://app.spara.co/mcp/customer/stream
```

Use **OAuth** authentication and complete the connection details. Select **Create** and follow the prompts to sign in to Spara, select your Spara workspace, and authorize access.
{% endstep %}

{% step %}

### Install and test the connection

Open [Personal plugins](https://chatgpt.com/plugins?view=personal), find the Spara connection you created, and select **+** to install it. Complete Spara sign-in if prompted.

Return to ChatGPT, switch to **Work**, and start a new chat. Type `@`, select **Spara**, and ask: "What agents and channels do we have set up in Spara?" Check that the results match the workspace you selected.
{% endstep %}
{% endstepper %}

These steps follow OpenAI's [MCP plugin quickstart](https://developers.openai.com/plugins/quickstart). The GitHub marketplace plugin described in the desktop tab is **Desktop only**, even though it connects to a remote server.
{% endtab %}

{% tab title="ChatGPT desktop" %}
Install the Spara marketplace plugin in the ChatGPT desktop app. It includes Spara's MCP connection and reusable instructions for working with Spara.

{% stepper %}
{% step %}

### Add the Spara marketplace

For a managed ChatGPT workspace, ask an administrator to open **Admin > Plugins > Add > Import marketplace** and enter this repository URL as **Source**:

```
https://github.com/spara-ai/spara-plugins
```

Leave **Path** and **Branch, tag, or commit** empty to use the repository root and default branch. Select **Import marketplace**, authorize GitHub access if prompted, and make Spara **Available** or **Installed** for the intended roles. Importing the marketplace does not connect each member's Spara account.

If you manage plugins locally with Codex CLI instead, add the same marketplace with:

```sh
codex plugin marketplace add spara-ai/spara-plugins
```

Then reopen the desktop app's **Plugins** tab to find the Spara marketplace. See OpenAI's [local marketplace setup](https://developers.openai.com/plugins/build/plugins#add-a-marketplace-from-the-cli) for that alternative.
{% endstep %}

{% step %}

### Install and authorize Spara

In the ChatGPT desktop app, open **Plugins**, find **Spara** in the workspace or configured marketplace, and select **+** to install it.

Connect the Spara MCP server when prompted. Sign in to Spara, select the workspace you want to use, and approve access. The plugin supplies the server URL; you do not need to enter it manually.
{% endstep %}

{% step %}

### Start a new conversation

Start a new Work chat and ask Spara: "What agents and channels do we have set up in Spara?" Complete the connection if authentication is requested on first use, and check that the results match your selected workspace.
{% endstep %}
{% endstepper %}

OpenAI documents this flow in [Plugins](https://learn.chatgpt.com/docs/plugins) and [Plugin management](https://learn.chatgpt.com/docs/enterprise/plugin-management). Imported plugins with an MCP server are **Desktop only**. Importing Spara into your workspace does not make that plugin usable on the web; use the separate web setup above.
{% endtab %}

{% tab title="Claude" %}
{% stepper %}
{% step %}

### Add the Spara marketplace

Open **Customize > Plugins > Add > Add Marketplace**. Copy and paste this URL into the dialog:

```
https://github.com/spara-ai/spara-plugins
```

{% endstep %}

{% step %}

### Install Spara

Find the Spara plugin card and select the **+** button in its top-right corner.
{% endstep %}

{% step %}

### Connect your Spara account

Select **Settings > Connectors > Connect** next to the Spara connector. Sign in to Spara and select the workspace you want Claude to use.
{% endstep %}
{% endstepper %}
{% endtab %}
{% endtabs %}

## What you can do

All access is limited to the Spara workspace selected during OAuth. Spara checks your current workspace membership and permissions for every tool call.

### Read and analyze

Any member of the selected workspace can ask Claude or ChatGPT to:

* List Agents and their Chat, Email, Phone, SMS, Product Demo, and Workflow channels
* Read channel configuration and active AI Instructions
* List Spara Data Model fields and available fields from a connected CRM
* Find individual Leads and read their Spara Data Model values
* Find conversations by Lead, topic, channel, or recency, and read transcripts from Chat, Email, SMS, Phone, and Product Demo conversations
* List voices and Product Demo features used when configuring channels
* Analyze trends, comparisons, and performance questions over the workspace's Spara data
* Search and read Spara's public documentation

Analytics returns a written answer. It does not expose raw SQL or raw result rows.

### Create and draft changes

Editors and Managers can ask Claude or ChatGPT to:

* Create an Agent container
* Create an unpublished channel
* Update a channel's configuration
* Edit an Agent's AI Instructions

These configuration tools are hidden and unavailable when your current Spara role does not include full Agent access. ChatGPT workspace controls can also disable actions or require you to approve them.

Any workspace member can submit product feedback through the connector. Feedback is recorded for Spara's product team and does not change the workspace.

## Changes never publish automatically

The connector has no tool that can publish a channel or configuration change.

Changes to channel configuration and AI Instructions are saved as **unpublished drafts**. New channels also start unpublished. Your AI assistant returns a link to the relevant editor in Spara, where a person must review and publish the draft. Until that happens, the published configuration remains unchanged.

Creating an Agent container or submitting product feedback does not publish a live channel change.

## Data handling and telemetry

Your AI assistant can request only the data exposed by the capabilities above. Depending on the request, this can include Agent and channel configuration, Data Model and CRM field definitions, individual Lead details, conversation transcripts, and analytics derived from Lead and conversation data. Analytics may process underlying Lead and conversation data, but it returns only a written analysis.

The analytics tool receives both the question and a short natural-language description of why the question is being asked. Spara uses that context for observability and product improvement; it does not change the analysis.

Spara records connector tool calls for security, reliability, evaluation, and product usage monitoring:

* Spara stores a redacted and size-limited copy of tool inputs and a redacted result preview of up to 20,000 characters.
* Product telemetry includes the selected workspace, tool name, outcome, duration, OAuth client identifier, and error type when applicable.
* Diagnostic monitoring includes the Spara server and tool involved in an error.

See Spara's [Privacy Statement](https://www.spara.com/privacy) and [Developer: Security & Compliance](https://docs.spara.com/developers/installation/security-and-compliance) for Spara's broader data protection, storage, encryption, and AI subprocessor commitments. For ChatGPT-specific controls and data handling, see OpenAI's [Apps in ChatGPT](https://help.openai.com/en/articles/11487775).

## Disconnect, reconnect, or reset access

{% tabs %}
{% tab title="ChatGPT" %}

1. Open **Settings**, then select **Plugins** or **Apps**, depending on the option shown for your account.
2. Open Spara. Under **Connected accounts** or **Connection**, open the more options menu and select **Disconnect**.

To reconnect or reset an expired token, return to Spara's plugin listing and select **Reconnect** or **Connect**. Sign in again and select the intended Spara workspace.

See OpenAI's [Connecting and managing app accounts in ChatGPT](https://help.openai.com/en/articles/20001494-connecting-and-managing-app-accounts-in-chatgpt) for account-management details.
{% endtab %}

{% tab title="Claude" %}

1. Open **Customize > Plugins**.
2. Find **Spara**, open its more options menu, and select **Remove**.

To reconnect or reset an expired token, install Spara again and complete the connection flow.
{% endtab %}
{% endtabs %}

Disconnecting prevents future Spara access through that connection.

## Troubleshooting

### Spara does not appear

* **ChatGPT web**: Create and install the direct MCP connection from the web tab above. A GitHub-imported plugin marked **Desktop only** cannot run on the web. If developer mode is missing, ask your workspace administrator about custom MCP access.
* **ChatGPT desktop**: Confirm that the Spara marketplace was added from `https://github.com/spara-ai/spara-plugins`. In a managed workspace, ask an administrator to check the import result and installation policy for your role. Start a new chat after installation.
* **Claude**: Confirm that the Spara marketplace and plugin were added in **Customize > Plugins**. On Team and Enterprise plans, ask a Claude Owner to confirm that Spara is enabled for the organization.

### Authentication succeeds, but tool calls are denied

Disconnect and reconnect, then select a Spara workspace where you are still a member. Spara checks live membership on every call, so removed or revoked access takes effect immediately.

### Configuration tools are missing

Your Spara role does not have Agent editing access. Ask a Manager to assign you the Contributor, Editor or Manager role in [**Settings > Team**](https://app.spara.co/settings/team), then reconnect so the assistant refreshes the visible tools.

### The assistant is using the wrong Spara workspace

Disconnect and reconnect, then select the correct workspace during OAuth. One connection is scoped to one workspace at a time.

### You still cannot connect

Email <support@spara.com> with the client and mode you are using, the approximate time of the failure, and the error message. Do not send access tokens or passwords.

## Current limitations

* The connector cannot run raw SQL or return raw analytics rows.
* The connector cannot publish or delete Agents or channels, edit Lead records, or manage CRM field mappings.
* One OAuth connection is scoped to one Spara workspace. Reconnect to select another workspace.
* The GitHub-imported Spara plugin is desktop-only. ChatGPT web requires a separately created MCP connection. Workspace policies still apply to both setup paths.
* The Spara plugin is not yet listed in Anthropic's official plugin marketplace. Claude installation depends on the public Spara plugin repository.


# Connecting Salesforce

How to connect Spara to Salesforce and configure lead syncing.

This guide walks you through connecting Spara to Salesforce so that lead conversations and field data sync automatically to your CRM.

For a full feature reference, see [Salesforce](https://docs.spara.com/integrations/crm-integrations/salesforce).

## What Syncs

Once connected, Spara can:

* Write conversation data and field values to matching Salesforce Leads and Contacts (Push)
* Create new Salesforce records when no match is found
* Import existing Salesforce records into Spara as Leads (Import)
* Read Account and Owner data to personalize agent behavior

{% stepper %}
{% step %}

#### Navigate to Integrations

Go to [**Settings > Integrations**](https://app.spara.co/settings/integrations) and find the Salesforce card. Click **Authorize**.

{% hint style="info" %}
You need Manager or Integrator permissions to connect integrations. See [User Management](https://docs.spara.com/platform/settings/user-management) for role details.
{% endhint %}
{% endstep %}

{% step %}

#### Enter your Salesforce URL and authorize

Enter your Salesforce instance URL (e.g., `https://yourcompany.salesforce.com`). Use your main Salesforce domain, not a `.force.com` URL.

Click **Authorize** and complete the Salesforce authentication flow.
{% endstep %}

{% step %}

#### Turn on sync

On the Manage page, use the **Contacts** and **Leads** tabs to configure each object type independently:

* **Sync Leads** / **Sync Contacts** (top of the tab): turn on to sync linked records both ways according to your write rules; turn off to stop all sync for that record type
* **Create & update**, **Update only**, or **Create only** (under **Writing to Salesforce Leads** / **Contacts**): choose whether Spara creates Salesforce records when no existing one matches, only updates existing records, or always creates new records without matching

Spara matches records by Salesforce ID, email address, or phone number automatically.
{% endstep %}

{% step %}

#### Map fields

Field mappings are set on each field in the [**Data Model**](https://app.spara.co/data-model), not on the Salesforce settings page.

1. Open a Lead field (e.g., First name, Company, or any custom field) in the Data Model
2. In its **Salesforce sync** section, choose the **Salesforce field** in the **Contact** and **Lead** slots. Contacts and Leads are mapped independently
3. Set the write rule for each direction, **Salesforce → Spara** and **Spara → Salesforce**: **Overwrite**, **Set if empty**, or **Read-only** (never write in that direction)
4. Click **Save changes**

To map several fields at once, click **Suggest fields** on the Data Model's **Lead** tab and pick from the AI-suggested Salesforce mappings. Picks save immediately, creating Spara fields where needed.

To sync the full conversation history across every channel, map the **Conversation transcript (all channels)** Spara field to any Salesforce long-text field.

A record type the connected Salesforce user can't see stays off, and its tab is read-only until that user is granted access to it.

The Salesforce settings page lists the fields synced with each object, with any mapping problems first. See [Data Model](https://docs.spara.com/platform/data-model#crm-field-mappings) for details.
{% endstep %}

{% step %}

#### Save and verify

Click **Save** to activate the connection. New lead activity will begin syncing to Salesforce immediately.

To verify, have a test lead interact with your Spara agent and confirm that a corresponding Lead or Contact record appears or is updated in Salesforce.
{% endstep %}
{% endstepper %}

## Troubleshooting

### OAuth Error

If you see an OAuth Error, have your Salesforce admin connect directly from Spara, or create an external connected app with API read/create/edit access on Leads and Contacts.

### Reconnection required

Go to [**Settings > Integrations > Salesforce**](https://app.spara.co/settings/integrations/salesforce/manage), click **Deauthorize**, then authorize again.

### Disconnecting

Click **Deauthorize** on the Salesforce manage page. Your sync configuration and field mappings are preserved for when you reconnect.


# Connecting HubSpot

How to connect Spara to HubSpot and configure lead syncing.

This guide walks you through connecting Spara to HubSpot so that lead conversations and field data sync automatically to your CRM.

For a full feature reference, see [HubSpot (CRM)](https://docs.spara.com/integrations/crm-integrations/hubspot-crm).

## What Syncs

Once connected, Spara can:

* Write conversation data and field values to matching HubSpot Contacts (Push)
* Create new HubSpot Contacts when no match is found
* Import existing HubSpot Contacts into Spara as Leads (Import)

{% stepper %}
{% step %}

#### Navigate to Integrations

Go to [**Settings > Integrations**](https://app.spara.co/settings/integrations) and find the HubSpot card. Click **Authorize**.

{% hint style="info" %}
You need Manager or Integrator permissions to connect integrations. See [User Management](https://docs.spara.com/platform/settings/user-management) for role details.
{% endhint %}
{% endstep %}

{% step %}

#### Authorize with HubSpot

You'll be redirected to HubSpot to grant Spara access. Log in with an account that has admin or integration permissions. The connection is established automatically; no additional configuration is required in HubSpot.
{% endstep %}

{% step %}

#### Turn on sync

On the **Contacts** tab:

* **Sync Contacts** (top of the tab): turn on to sync linked HubSpot Contacts both ways according to your write rules; turn off to stop all Contact sync
* **Create & update** or **Update only** (under **Writing to HubSpot Contacts**): choose whether Spara creates a Contact when no existing one matches by email address, or only updates existing Contacts
  {% endstep %}

{% step %}

#### Map fields

Field mappings are set on each field in the [**Data Model**](https://app.spara.co/data-model), not on the HubSpot settings page.

1. Open a Lead field (e.g., First name, Company, or any custom field) in the Data Model
2. In its **HubSpot sync** section, choose the **HubSpot field** in the **Contact** slot
3. Set the write rule for each direction, **HubSpot → Spara** and **Spara → HubSpot**: **Overwrite**, **Set if empty**, or **Read-only** (never write in that direction)
4. Click **Save changes**

To map several fields at once, click **Suggest fields** on the Data Model's **Lead** tab and pick from the AI-suggested HubSpot Contact mappings. Picks save immediately, creating Spara fields where needed.

The HubSpot settings page lists the fields synced with each object, with any mapping problems first. See [Data Model](https://docs.spara.com/platform/data-model#crm-field-mappings) for details.
{% endstep %}

{% step %}

#### Save and verify

Click **Save** to activate the connection. New lead activity will begin syncing to HubSpot immediately.

To verify, have a test lead interact with your Spara agent and check that a corresponding Contact appears or is updated in HubSpot.
{% endstep %}
{% endstepper %}

## Troubleshooting

### Reconnection required

If the HubSpot card shows "Reconnection required," Spara's access token has expired. Go to [**Settings > Integrations > HubSpot**](https://app.spara.co/settings/integrations/hubspot/manage), click **Deauthorize**, then authorize again.

### Disconnecting

To disconnect HubSpot, go to [**Settings > Integrations > HubSpot**](https://app.spara.co/settings/integrations/hubspot/manage) and click **Deauthorize**. Your field mappings are preserved if you reconnect later.


# Working Around CRM Sync Limitations

Practical patterns for working around the limits of Spara's native CRM integration.

Spara's native CRM integration is intentionally opinionated: it syncs Lead and Contact records automatically, reads Account, Owner, and Deal data, and pushes every update as it happens. That covers most teams out of the box, but some CRM setups need more. This guide covers the most common gaps and the recommended workaround for each.

{% hint style="info" %}
Several workarounds below involve custom configuration by Spara's engineering team, available for Enterprise customers. Contact your Spara customer success representative to scope them.
{% endhint %}

## Spara's data model in brief

Spara organizes buyer data into a small set of objects, and the sync's boundaries follow the object model:

* **Lead**: a single person. The only object Spara writes to your CRM.
* **Account**: a company. Read from your CRM, never written.
* **Owner**: the rep responsible for a record. Read from your CRM, never written.
* **Deal**: a sales opportunity. Read nightly for analytics, never written.
* **Event**: a lead interaction (chat, call, email, meeting). Stored in Spara; not yet available for CRM sync.

For the full picture of each object and how they relate, see [Developer: Spara Objects & Fields](https://docs.spara.com/developers/data-model). For what each integration reads and writes, see [Salesforce](https://docs.spara.com/integrations/crm-integrations/salesforce) and [HubSpot (CRM)](https://docs.spara.com/integrations/crm-integrations/hubspot-crm).

## Use data from CRM objects Spara doesn't support

**The gap:** Spara models Leads, Accounts, Owners, and read-only Deals. If the data you need lives on another CRM object, such as a custom object or an Opportunity field you want in workflow logic, the native integration won't sync it directly.

**The workaround:** Spara's engineering team can map fields from unsupported CRM objects onto Spara's core objects. Rather than extending Spara's data model to mirror your CRM, the relevant fields are flattened onto the Lead, Account, or Owner where your workflows and agents can use them.

For example, suppose you want workflows to run only for leads attached to an active deal:

1. Your Salesforce `Opportunity.StageName` field is mapped to a custom Spara Lead field, e.g. `deal_stage`.
2. Spara keeps `deal_stage` up to date as your CRM changes.
3. Your workflows trigger and branch on `deal_stage` like any other field. See [Building Your First Workflow](/guides/platform-guides/building-your-first-workflow).

The design work is defining the mapping: which object, which fields, and how they roll up to a single lead. Your Spara team will work through that with you. This is available for Enterprise customers.

## Require fields before a CRM record is created

**The gap:** By default, Spara creates a CRM record as soon as it captures an email address, before a name or company may be known. Salesforce requires a last name (and company, for Leads) on every record, so Spara fills missing required fields with the placeholder `UNKNOWN` and updates them as real values arrive. Some teams don't want partial records in their CRM at all.

**The fix:** Add a **Create condition** in your integration settings, under **Writing to Salesforce Leads** / **Contacts** or **Writing to HubSpot Contacts**. Spara then creates a record only once the lead matches the condition, for example "only create a Salesforce Lead once last name and company are known", and retries as soon as the missing information is captured. Only admins can edit the condition. For Salesforce, turn on **Use Salesforce required fields** to add the fields Salesforce needs. See [Salesforce](https://docs.spara.com/integrations/crm-integrations/salesforce#create-condition) and [HubSpot CRM](https://docs.spara.com/integrations/crm-integrations/hubspot-crm#writing-to-hubspot-contacts).

If you want to avoid Spara-created records entirely, choose **Update only** in your integration settings. Spara will enrich records your team creates, but never create its own.

## Keep Spara from overwriting CRM data

**The gap:** Spara pushes every field update by default, and new field mappings default to **Overwrite**, which can clobber values your reps maintain by hand.

**The workaround:** Use the write rules on each field's CRM sync section in the [**Data Model**](https://app.spara.co/data-model), and the record settings in your integration settings:

* Set a mapping's **Spara → CRM** write rule to **Set if empty**. Spara fills gaps but never replaces an existing value.
* Set a mapping's **Spara → CRM** write rule to **Read-only** to pull the field into Spara without Spara ever writing it back.
* Choose **Update only** to stop Spara from creating records.
* Turn off **Sync Leads** / **Sync Contacts** for a record type you don't want Spara touching at all. Nothing syncs for that record type in either direction.

## Write to Accounts, Opportunities, or other objects

**The gap:** Spara only writes to Lead and Contact records. It cannot update a CRM Account when it learns firmographics, or write deal context back to an Opportunity.

**The workaround:** Route the data through your own automation instead of the native sync:

* **Webhooks**: Spara fires a webhook whenever lead fields change, with the full field payload. Point it at your middleware (Zapier, Workato, a serverless function) and write to any CRM object your automation can reach. See [Developer: Webhooks](https://docs.spara.com/developers/spara-api/webhooks).
* **API workflow step**: a Spara workflow can call any external endpoint at a specific moment (e.g., after a meeting is booked), sending lead fields in the request. See [API Step](https://docs.spara.com/agents/workflows/steps/api).
* **Web API**: pull lead data from Spara on your own schedule and reconcile it into your CRM however you like. See [Developer: Web API](https://docs.spara.com/developers/spara-api/web-api).

## Log Spara activity in your CRM

**The gap:** Spara records every interaction (messages, calls, emails, meetings) as Events in the Spara platform, but Events don't yet sync to the CRM as structured activity records like Salesforce Tasks or HubSpot activities.

**The workaround:** Get conversation activity into your CRM through the supported channels:

* **Map the Conversation transcript field.** Open the **Conversation transcript (all channels)** field in the [**Data Model**](https://app.spara.co/data-model) and, in its CRM sync section, map it to a long-text field on your Lead or Contact. Spara keeps the full transcript, across every channel, up to date there.
* **Salesforce Task logging.** Spara can log each conversation as a Salesforce Task attached to the Lead or Contact and assigned to its owner. Ask your Spara team to enable this.
* **Email activity.** Emails Spara exchanges with a lead are logged automatically, as native email records in Salesforce and email engagements in HubSpot.
* **Event-level records.** If you need individual events (meeting booked, call completed) as CRM activities today, use [Developer: Webhooks](https://docs.spara.com/developers/spara-api/webhooks) to receive them in real time and create the activity records with your own automation.

## Control which CRM records enter Spara

**The gap:** Import Rules, which decide which CRM records are imported into Spara as new Leads, are not self-serve.

**The workaround:** Your Spara customer success representative configures Import Rules with you. They can filter on any Lead or Contact field in your CRM (lead source, region, lifecycle stage, and so on), so give your Spara team the segment definition and they'll set it up.




---

[Next Page](https://docs.spara.com/llms-full.txt/1)

