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

### 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), [Time of Day Step](/build/workflows/steps/time-of-day), [Condition Step](/build/workflows/steps/condition), [API Step](/build/workflows/steps/api), [Research Step](/build/workflows/steps/research)

<figure><img src="/files/OEspvNjTjtblBfnTq2yG" 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="/files/3X5zLdTqpHhDxdIYDFxI" 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="/files/2Mn47fpclpiIpHgfnjTE" 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/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="/files/BCpFUKHiE67IayWLJCiV" alt=""><figcaption><p>Start a new Agent from a proven template, or build one from scratch.</p></figcaption></figure>

## 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="/files/P2NLv4cjBGpFCyhE5nAw" 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.

**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 [Using Media in Chat Agents](/guides/platform-guides/using-media-in-chat-agents) for a step-by-step walkthrough.

<figure><img src="/files/tFQH1lqizc6EukjOhDEd" 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.

<figure><img src="/files/k3Ffg1yWKICZ9O8o4hFj" 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 [iFrame & Cookies](/developers/spara-api/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: [https://docs.spara.com/guides/onboarding-guides/chat-agent-onboarding/installing-spara-navigator](https://docs.spara.com/guides/onboarding-guides/chat-agent-onboarding/installing-spara-navigator "mention").

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

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

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\...
  * Is entirely configurable for Desktop vs. Mobile visitors.
  * Starting criteria determines which website visitors see it. The "default" Preview is a catch-all for any website visitors that don't fit the starting criteria of other Previews.
  * Starting delay sets how many seconds to delay before showing Navigator website visitors.
  * Preview mode is what Navigator looks like. Different Preview modes require different inputs.
* 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="/files/k3Ffg1yWKICZ9O8o4hFj" 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`).
{% endhint %}

### 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="/files/iM71tkcONSsIbigAzjmy" 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

<figure><img src="/files/UOUtXpDH4YnRcGPzAcT5" alt=""><figcaption><p>Traditional: Message mode can show with a preview message and/or suggested responses.</p></figcaption></figure>

<figure><img src="/files/nmwApGtNZd5SQ1f8zT1D" 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, and a **Start product demo** button. Two additional buttons — book a meeting and request support — can be enabled per preview.

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: [https://docs.spara.com/guides/onboarding-guides/chat-agent-onboarding/installing-smartbar](https://docs.spara.com/guides/onboarding-guides/chat-agent-onboarding/installing-smartbar "mention").

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="/files/f8iFL9okorZlkjSswbFL" 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 [https://docs.spara.com/developers/spara-api/query-parameters](https://docs.spara.com/developers/spara-api/query-parameters "mention") 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: [https://docs.spara.com/guides/onboarding-guides/chat-agent-onboarding/installing-spara-fullscreen](https://docs.spara.com/guides/onboarding-guides/chat-agent-onboarding/installing-spara-fullscreen "mention").

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="/files/JZQvD7d35Dy3N7LobLDd" 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.
* **Chat Channel Avatar:** Change the avatar or name. The avatar must be a 200x200 px image.

#### Smartbar Settings

<figure><img src="/files/cJUoDHINoe3XXO6koCYg" 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="/files/EPbYwhYLsENbE4ifquYi" alt=""><figcaption><p>Spara Navigator with a media panel open alongside the chat window.</p></figcaption></figure>

## Setting up your media library

Navigate to [**Media**](https://app.spara.co/ai-training/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 the [Using Media in Chat Agents](/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 [Using Media in Chat Agents](/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="/files/y6ucqXZVUsud9hGU5jEr" 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 the [How to Use Spara's Text Editor](/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.

**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

### 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.
* **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 a one-click unsubscribe link in the footer, in compliance with CAN-SPAM and the major mailbox providers' bulk-sender requirements (Gmail, Yahoo). When a lead clicks unsubscribe, Spara:

* Records the opt-out on the lead (`unsubscribed_at`) so it shows on the lead's record and in exports.
* Immediately stops all future emails to that lead, across cadences, workflow Send Email steps, and Reply Agent responses.
* Stops Spara from generating any further outbound email content for them, even if a workflow would have triggered one.

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.

### 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="/files/kwRFkYkX8UEvSGwObDeI" 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 [https://docs.spara.com/guides/setting-up-voice-agents](https://docs.spara.com/guides/setting-up-voice-agents "mention").

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

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 [https://docs.spara.com/developers/spara-api/webhooks](https://docs.spara.com/developers/spara-api/webhooks "mention") 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. 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="/files/g1bBh2ECxi9bWQrr44Br" 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 the [https://docs.spara.com/guides/onboarding-guides/text-agent-onboarding](https://docs.spara.com/guides/onboarding-guides/text-agent-onboarding "mention") for full details.
{% endhint %}

{% hint style="info" %}
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 %}


# 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="/files/rtZRuethjaLJ1V6fhf6G" 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.

### 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 Points
## Proof    <!-- optional -->
## Key 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.

{% 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.

## Opening visual

The opening visual is the first image 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 **Configuration** 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.

## 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. You can trigger a Product Demo session by calling `SparaActions.openProductDemo()` on your website. For email campaigns, add a query parameter to your landing page URL (e.g., `?demo`) and include JavaScript on your site that checks for the parameter and opens the demo automatically.

See [https://docs.spara.com/guides/product-demo-use-cases](https://docs.spara.com/guides/product-demo-use-cases "mention") for step-by-step setup for website CTAs, outgoing email campaigns, chat-to-demo transitions, and more. For the full JavaScript reference, see [https://docs.spara.com/developers/spara-api/javascript-api](https://docs.spara.com/developers/spara-api/javascript-api "mention").


# 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/organization/product-demo-configuration/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="/files/TvcmJ7olkziAD4EStMAr" 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 [Writing Effective Agent Prompts](/guides/platform-guides/writing-effective-agent-prompts).

<figure><img src="/files/d54UQHkWulKNAJHmZilF" alt=""><figcaption><p>The AI Instructions panel in the editor.</p></figcaption></figure>

## 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="/files/oYE5ats1eGj8167s6xCU" 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; 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="/files/IRWP0IbMusds0Cl1wXBO" 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 Navigator or Smartbar    |
| Phone   | Simulated phone call (browser-based)                    |
| 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.** Messages sent during testing do not appear in lead history, trigger workflows, or generate analytics events.

**View fields panel.** During a chat test, open the View fields panel to see what data the agent has about the lead. This includes IP-based location fields — `ip_country`, `ip_region`, and `ip_city` — so you can verify what geographic context the agent will have in a real conversation.

### 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 lead context: no prior messages, no previously captured fields.

***

## 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="/files/MfF6YBXzth0KS59OoUHg" 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. They don't create lead records, trigger workflows, or appear in analytics.

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

Not directly from the editor. You can manually set fields at the top of the test panel (e.g., `first_name`, `company_name`) to simulate a personalized experience. For more advanced testing with realistic lead data, 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="/files/99xgYjkhSGZVR3D1YRno" 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.

{% 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="/files/CWhoZbXbjgO3IEXxFfAR" 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.

### 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 [Web API](/developers/spara-api/web-api) or [Javascript API](/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="/files/2uJIiRtB82n39o7nUPDs" 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.

## 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. Leads are held at that step and retried automatically when the window reopens — so the step will still fire, just later than immediately scheduled.

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** and **Time of Day** steps to control timing, and **Condition** steps to branch the logic.

<figure><img src="/files/2uJIiRtB82n39o7nUPDs" 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).                                           |
| [Time of Day Step](/build/workflows/steps/time-of-day) | Holds leads until a specific clock time is reached.                                            |
| [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.                              |
| [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="/files/V1dTtZDWYF6oMIoFgXhF" alt=""><figcaption><p>The Send Email step configuration panel.</p></figcaption></figure>

## Configuration

### 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.                                                       |
| **BCC**                  | Additional email addresses to BCC.                                                      |

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

### Subject and Body

Both the subject line and body support variables. 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. Leads that reach this step outside the window are held — not dropped — and the step retries automatically once the window reopens.
{% 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="/files/gL4TW0W6d32FOaZjGJUF" alt=""><figcaption><p>The Send Text step configuration panel.</p></figcaption></figure>

## Configuration

### Message Body

Write the SMS content in the message body field. The body supports variables: use the **Insert menu** (⚡) to browse available lead data fields.

Keep messages concise. SMS best practices recommend staying under 160 characters to avoid message splitting.

### 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.** If your organization has a text outgoing window configured (Settings > Phone Numbers > Outgoing Times), this step only fires during that window. Leads that reach this step outside the window are held — not dropped — and the step retries automatically once the window reopens.
{% 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="/files/aWJa5sY4dYcP9cB7pH89" alt=""><figcaption><p>The Call Phone step configuration panel.</p></figcaption></figure>

## Configuration

### Voice Agent

Select which Voice agent places the call. If your account has a default Voice agent configured, it will be pre-selected.

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

### Outgoing Number

Select which of your provisioned phone numbers to call from. This is the number the lead will see on their caller ID.

## 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.** If your organization has an outgoing call window configured (Settings > Phone Numbers > Outgoing Times), this step only fires during that window. Leads that reach this step outside the window are held — not dropped — and the step retries automatically once the window reopens.
{% 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="/files/zH4qLbvng8cy4MtwWh9N" 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/organization/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 [How to Use Spara's Text Editor](/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 or Teams, or an additional recipient on email. Webex supports room notifications only, not direct messages. The assigned rep comes from your connected CRM (Salesforce or HubSpot); for direct messages, the rep must have a matching account in your workspace. You can combine this with a channel or other recipients — the notification is sent to all of them.

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

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

<figure><img src="/files/f3Do7vFTnmbHN39DUOMY" 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 actions at a specific clock time rather than a relative delay, use the [Time of Day Step](/build/workflows/steps/time-of-day) instead.
{% 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

Hold workflow execution until a specific time of day is reached.

The **Time of Day** step holds a lead at a specific point in the workflow until a configured clock time is reached in your account's timezone. Once that time arrives, the lead automatically advances to the next step.

Use this step to schedule workflow actions for specific hours, for example restricting outgoing calls to business hours, or ensuring emails go out at a predictable time each day.

<figure><img src="/files/P3PvpaWRxbbQecQmbsYx" alt=""><figcaption><p>Configuring a Time of Day step.</p></figcaption></figure>

## Configuration

Set the **time** (HH:MM, 24-hour clock) you want leads to advance at. The step's configuration panel shows your account's IANA timezone for reference.

* If the target time **has not yet passed today** when a lead reaches this step, the lead waits for it.
* If the target time **has already passed today**, the lead waits until that time the following day.

{% hint style="info" %}
The Time of Day step uses your account's timezone. If no timezone has been configured, Spara defaults to `America/New_York`.
{% endhint %}

### Behavior during unpublish/republish

If a workflow is unpublished while a lead is waiting at a Time of Day step, the lead's timer pauses. When the workflow is republished, evaluation resumes from where it left off.

## Common Patterns

**Restrict outgoing calls to business hours**

Place a Time of Day step before a [Call Phone Step](/build/workflows/steps/call-phone) and set the time to the start of your calling window (e.g., `12:00` for noon). Leads who arrive outside that window wait automatically before the call fires.

**Send emails at a consistent hour**

Pair a Time of Day step with a [Send Email Step](/build/workflows/steps/send-email) to ensure outreach goes out at the same time each day, regardless of when a lead entered the workflow.

## FAQ

### Can I build a calling window (e.g., only call between noon and 5pm)?

The Time of Day step controls when a lead *enters* a downstream step, not a range. To restrict calls to a window, use a [Condition Step](/build/workflows/steps/condition) that checks the lead's timezone or current time alongside a second Time of Day step capping the end of your window.

### What happens if a lead reaches this step after the target time?

The lead waits until the same time the next day. Leads always advance at the next occurrence of the target time, never retroactively.

### Does this step respect each lead's local timezone?

Not currently. The Time of Day step uses your account-level timezone, not the individual lead's timezone. Per-lead timezone scheduling is planned for a future release.


# 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="/files/Hst47DcgySNIBx0OOcRZ" 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                                                                   |
| **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" %}
**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 %}

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

<figure><img src="/files/K8xkOh6YIFKgiw0dxZDt" 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 dynamically construct URLs using lead data. For example:

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

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


# 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="/files/zAFrok4R0flTfBcY2H2d" 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="/files/8kcSfQWnQFfQZHsPjoHo" 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.

## 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** and **Time of Day** 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.

### Send real messages during a test

By default, test runs simulate all outbound messages — emails, texts, and calls are not actually sent. Admins can enable **Send real messages** in the Test panel to verify that messages truly land: 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. 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 an admin-only option. Each test run is capped at 10 real sends; additional steps beyond the cap fall back to simulation automatically. Notification steps (Slack, Teams) always send to your configured channels — confirm the channel list shown in the UI before running.
{% endhint %}

{% hint style="info" %}
For a step-by-step walkthrough of building a workflow, see the [Building Your First Workflow](/guides/platform-guides/building-your-first-workflow) guide.
{% 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 or Teams.


# 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="/files/qP6UwL1BWsiVrYAhMyjL" 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
* **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 [https://docs.spara.com/developers/optimizing-your-webpages-for-spara-scraping](https://docs.spara.com/developers/optimizing-your-webpages-for-spara-scraping "mention").

### 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 — built-in fields, custom fields, and where they come from.

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.

## 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, Voice, 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.
* **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.
* **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.

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

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

### Integration Field Mappings

For fields synced from an integration (Salesforce, HubSpot, or Marketo), the field detail panel shows which external field it maps to and the sync direction. Open any field and expand the **Integration Sync** section to see the mapping.

## Field Reference

### Lead Info

| Field                           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| First name `String`             | Lead's first name                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Last name `String`              | Lead's last name                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Full name `String`              | First and last name combined                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Email `String`                  | Lead's email address                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Phone number `String`           | Lead's phone number                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Job title `String`              | Lead's job title or role                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Lead source `Picklist`          | <p>How this lead was created in Spara.<br><strong>Spara</strong> — created via Chat or Voice agents<br><strong>Salesforce</strong> — synced from Salesforce CRM<br><strong>HubSpot</strong> — synced from HubSpot CRM<br><strong>Marketo</strong> — synced from Marketo CRM<br><strong>Leads API</strong> — created via the Leads API<br><strong>Deanonymized</strong> — identified via IP/behavioral matching</p>                                                                                                                                                                                                                                                                                                                            |
| Lead stage `Picklist`           | <p>Current stage in the sales funnel, calculated from lead activity.<br><strong>Browsing</strong> — visiting pages but hasn't engaged<br><strong>Engaged</strong> — has sent at least one message or made a call<br><strong>Email Captured</strong> — email address has been collected<br><strong>Webform Submitted</strong> — submitted a webform<br><strong>Calendar Shown</strong> — was shown a scheduling calendar<br><strong>Meeting Scheduled</strong> — has a meeting scheduled<br><strong>Synced from CRM</strong> — imported from CRM with no local activity</p><p>Note: CRM field mappings continue to receive the value <code>Call scheduled</code> for this stage, so existing CRM picklists and automations are unaffected.</p> |
| Lead created at `Timestamp`     | Timestamp when the lead was first created                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Conversation summary `String`   | AI-generated summary of the lead's conversation history                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Conversation interests `List`   | Lead's interests identified from conversations                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Conversation pain points `List` | Pain points identified from conversations                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

### Account Info

| Field                    | Description                               |
| ------------------------ | ----------------------------------------- |
| Company name `String`    | Name of the lead's company                |
| Employee count `Integer` | Number of employees at the lead's company |

### Website Activity

| Field                          | Description                                      |
| ------------------------------ | ------------------------------------------------ |
| Current URL `String`           | Page the lead is currently viewing               |
| Initial URL `String`           | First page visited by the lead                   |
| Last page visited `String`     | Most recently visited page URL                   |
| Pages visited `List`           | List of unique URLs visited, most recent first   |
| Website visited at `Timestamp` | Timestamp of the lead's most recent page visit   |
| Referrer `String`              | External site or page the lead came from         |
| IP country `String`            | 2-letter country code from the lead's IP address |
| IP country name `String`       | Full country name from the lead's IP address     |
| IP region `String`             | State or region from the lead's IP address       |
| IP city `String`               | Approximate city from the lead's IP address      |

### Chat Activity

| Field                               | Description                                       |
| ----------------------------------- | ------------------------------------------------- |
| Conversation started at `Timestamp` | Timestamp when the lead first started a chat      |
| Opened chat `Boolean`               | Whether the lead has opened the chat widget       |
| Sent chat message `Boolean`         | Whether the lead has sent at least one message    |
| Chat dropoff at `Timestamp`         | Timestamp when the lead last engaged in chat      |
| Prospect message count `Integer`    | Total messages sent by the lead                   |
| Engaged channels `List`             | Which Spara channels the lead has interacted with |

### Email Activity

| Field                              | Description                                                                                                                                                                                            |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Email opened at `Timestamp`        | Timestamp when the lead opened an email                                                                                                                                                                |
| Email link clicked at `Timestamp`  | Timestamp when the lead clicked a link in an email                                                                                                                                                     |
| Last email sent at `Timestamp`     | Timestamp of the most recent email sent to the lead                                                                                                                                                    |
| Email validation status `Picklist` | <p>Result of email address validation.<br><strong>Valid</strong> — address is deliverable<br><strong>Invalid</strong> — address is not deliverable<br><strong>Unknown</strong> — not yet validated</p> |
| Unsubscribed at `Timestamp`        | Timestamp when the lead unsubscribed from emails                                                                                                                                                       |

**Email opened at** and **Email link clicked at** stay empty if your organization has turned off **Email Tracking** under **Settings → Email Configuration**.

### Phone Activity

| Field                                                  | Description                                    |
| ------------------------------------------------------ | ---------------------------------------------- |
| Most recent outgoing call — cold transferred `Boolean` | Whether the call was cold transferred to a rep |
| Most recent outgoing call — warm transferred `Boolean` | Whether the call was warm transferred to a rep |
| Most recent outgoing call — booked call `Boolean`      | Whether the call resulted in a booked meeting  |
| Most recent outgoing call — left message `Boolean`     | Whether a voicemail was left                   |
| Most recent outgoing call — do not call `Boolean`      | Whether the lead requested not to be called    |
| Most recent outgoing call — no answer `Boolean`        | Whether the call went unanswered               |
| Call pick up `Boolean`                                 | Whether the lead answered the most recent call |
| Incoming call ended at `Timestamp`                     | Timestamp when the last incoming call ended    |
| Outgoing call ended at `Timestamp`                     | Timestamp when the last outgoing call ended    |

### Meeting Activity

| Field                            | Description                                   |
| -------------------------------- | --------------------------------------------- |
| Meeting scheduled `Boolean`      | Whether a meeting has been scheduled          |
| Meeting scheduled at `Timestamp` | Timestamp of the upcoming scheduled meeting   |
| Calendar shown `Boolean`         | Whether a calendar has been shown to the lead |

### Sign Up Info

| Field                       | Description                              |
| --------------------------- | ---------------------------------------- |
| Webform submitted `Boolean` | Whether the lead has submitted a webform |

### Spara Questions

| Field                      | Description                                                                                                                                                                                                                                                                                                                                                  |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Call interest `Picklist`   | <p>Type of conversation the lead expressed interest in.<br><strong>Talk to sales</strong> — wants to speak with a sales rep<br><strong>Talk to support</strong> — has a support or technical issue<br><strong>Product demo</strong> — interested in seeing a product demo<br><strong>Unspecified</strong> — expressed intent to talk but type is unclear</p> |
| Support interest `Boolean` | Whether the lead has a support issue                                                                                                                                                                                                                                                                                                                         |

These are default fields. Any question your agent asks can create additional custom fields in this category.

### Advertising & Tracking

| Field                 | Description                                        |
| --------------------- | -------------------------------------------------- |
| UTM campaign `String` | UTM campaign parameter from the lead's URL         |
| GCLID `String`        | Google Click Identifier for Google Ads attribution |

### Time & Date

| Field                               | Description                    |
| ----------------------------------- | ------------------------------ |
| Current time (UTC hour) `Integer`   | Current hour in UTC            |
| Current time (UTC minute) `Integer` | Current minute in UTC          |
| Current time (UTC weekday) `String` | Current day of the week in UTC |
| Current timestamp (UTC) `Timestamp` | Full current timestamp in UTC  |

### CRM Fields

Any field synced from Salesforce, HubSpot, or Marketo appears alongside Spara-native fields. These are available in all the same places — workflow triggers, conditions, personalization, and analytics.

See [CRM Integrations](/integrations/crm-integrations) for setup instructions.

## 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 the [How to Use Spara's Text Editor](/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 **Settings > Data Model**, create a new field, and set the source to **Fixed value**.

Custom fields created either way are immediately available across the platform — in workflows, personalization, analytics, and CRM syncs.

### 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 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="/files/8MdFgM2PQvvWyxDrqNFU" 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="/files/AiXE6NtDC1JyXQbZwgMj" 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, 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 days, Last 30 days, Last 90 days, All time, or custom range                          |
| **Agent**          | Filter by a specific Chat, Email, Voice, or Copilot agent                                   |
| **Channel**        | Chat, Email, Voice, Text                                                                    |
| **Meeting Source** | Which channel the lead's meeting was scheduled through: Chat, Email, Voice, 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.

## Lead Details

Click any lead to open their detail view, which has two tabs:

### Timeline

The Timeline shows the full conversation history between the lead and your agents across all channels — chat messages, voice calls, and emails in a single chronological view.

<figure><img src="/files/EDNtY0b7PhS4Lt7Dxk0R" alt=""><figcaption><p>The Timeline tab 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.
* **View next steps** — The right sidebar shows upcoming workflow touchpoints and past actions.

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.

{% 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 %}

### Lead Details

The Lead Details tab shows everything Spara knows about a lead — personal information, a conversation summary, and company data pulled from enrichment and CRM syncs.

<figure><img src="/files/M5HmJDKhJ3dk9cTz9MJR" alt=""><figcaption><p>The Lead Details tab showing personal information, conversation summary, and company data.</p></figcaption></figure>

Information is organized into sections:

* **Personal Information** — Name, email (with validation status), phone, job title, seniority, department, LinkedIn profile, location, skills, and interests.
* **Conversation Summary** — AI-generated summary including questions asked, sales stage, pain points, and interests identified.
* **Company Details** — Company name, website, industry, revenue, headcount, business model, and products.
* **Company Insights** — Corporate objectives, competitors, recent news, and small talk opportunities.

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 right-hand panel of the **Timeline** tab (not the Lead Details tab).

* **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 enabled** toggle in the same panel is the outgoing counterpart: while **AI Responses enabled** covers incoming engagement, turn off **Workflows enabled** to stop email and voice outreach from [Workflows](/build/workflows) to the lead.

## 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="/files/uNLDHuK9kbeTYAVtEjNh" 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 can be configured at the account level by a Spara admin:

| 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 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. Once a lead is deanonymized, you can reference deanonymized fields in workflow conditions — for example, enrolling a visitor from a target account in an email workflow when they're identified, even if they never chatted.

**What vendor powers deanonymization?**

Spara currently uses Vector.

**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. 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 Details tab of the [Leads](/pipeline/leads) detail page and is available to capabilities in subsequent messages.

<figure><img src="/files/sgirDd8uiXQHHXJFoDK1" alt=""><figcaption><p>Enriched personal and company data on the Lead Details tab.</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 [https://docs.spara.com/developers/spara-api/query-parameters](https://docs.spara.com/developers/spara-api/query-parameters "mention").

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. 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 as the lead continues to interact with your capabilities.

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


# Owners

How Spara tracks the people responsible for your leads and accounts.

{% hint style="info" %}
Spara will be launching Owners soon.
{% endhint %}


# Accounts

How Spara manages accounts & opportunities.

{% hint style="info" %}
Spara will be launching Accounts in 2026 Q2.
{% endhint %}


# 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="/files/vmOJhUtjl3QhNqlc6hSn" 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 scheduled** — Leads from the selected time range who scheduled a meeting through chat
* **Emails collected** — Email addresses captured
* **Calendar shown** — Leads who were shown a scheduling widget

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
* **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

### Voice

* **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 voice 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 voice calls, searchable and categorized. Click any question to view the call transcript.
* **Comparison mode** — When a voice A/B test is active, toggle to comparison view to see per-variant metrics side by side

### Copilot

* **Call metrics** — Total duration, average call length, questions asked and answered
* **Activity breakdown** — Active calls vs. silent calls
* **Recent questions** — Questions from Copilot sessions

## 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 Voice 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 [https://docs.spara.com/developers/iframe-and-cookies](https://docs.spara.com/developers/iframe-and-cookies "mention").

## 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, Voice, and Copilot 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 voice 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 voice comparison mode work?

When a Voice A/B test is running, a **Comparison** toggle appears in the Voice section header. Switch it on to split every voice 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 voice 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="/files/4H7aop7BKprmp6UKUb6M" 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.

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="/files/vIO9WH7YSOIciD5BrlXM" 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, 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.

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

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

### 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, opens a todo when it detects an issue, and closes it on its own once the issue is resolved.

## Priority tiers

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.

## Where you'll find them

### Top bar

A **Todos** button sits in the top navigation bar on every page. It carries a count bubble showing how many todos are currently open. Click it to open the **Todos tray** on the right side of the screen, where active todos are grouped by product area:

* **Agents** — channels and workflows
* **Integrations** — CRM, calendar, and communications connections
* **Knowledge** — websites and documents Spara learns from
* **Leads**
* **Settings** — team members, notifications, and account configuration

Completed and dismissed todos are tucked into collapsed sections at the bottom of the tray, so your history stays out of the way but recoverable.

### Dashboard

Your Dashboard shows a **Todos** panel with the most important open items at a glance. Click **View all** to open the full tray.

## Example todos

Spara detects a wide range of setup gaps and issues. These are a few examples — not the full list:

| Todo                     | Area         | Priority    |
| ------------------------ | ------------ | ----------- |
| **CRM disconnected**     | Integrations | Urgent      |
| **Publish a channel**    | Agents       | Required    |
| **Connect a CRM**        | Integrations | Required    |
| **Add websites**         | Knowledge    | Required    |
| **Connect a calendar**   | Integrations | Recommended |
| **Set up notifications** | Settings     | Recommended |

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.

## Actions

Open any todo to see its details and take action.

### Mark as done

Click the circle icon next to the todo's title to mark it **Done**. Click the checkmark again to reopen it. Marking a todo done tells Spara you've handled it — the hourly check will not reopen a todo you've completed.

### 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 — some carry a short note explaining why.

### 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 or connecting an integration.

### Share a todo

Click **Copy link** 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.

## How todos close

Todos created by Spara's hourly check close automatically once the underlying issue is resolved. For example, if your CRM disconnects (opening an **Urgent** "CRM disconnected" todo) and you reconnect it, the todo closes on its own the next time Spara checks — 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.

## 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 you resolve the underlying issue or mark them done. Recommended todos can be left open or dismissed — they won't escalate.

### Will a todo reopen after I mark it done?

No. Marking a todo done is respected by the hourly check. A new todo for the same issue only appears if the issue is resolved and then happens again.

### 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.
* **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 [https://github.com/spara-ai/spara-app/tree/main/gitbook/documentation/platform/agents/channels/email.md](https://github.com/spara-ai/spara-app/tree/main/gitbook/documentation/platform/agents/channels/email.md "mention") 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/organization/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>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>

**Workflows.** Roles with Full access to Workflows can create, edit, publish, and delete workflows. View-only roles can open a 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.

### Inviting team members

New users may be invited in [Settings > Team](https://app.spara.co/organization/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/organization/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/organization/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="/files/XkevlbAJcvbYeda0T3un" alt=""><figcaption><p>The Notifications tab in Settings, showing configurable events.</p></figcaption></figure>

### Notification events

Notification events are grouped into two categories:

**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                           |

**Email agent events** fire when emails are sent to or from leads:

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

**Chat agent events** fire during live conversations with a lead:

| Event                        | What triggers it                                          |
| ---------------------------- | --------------------------------------------------------- |
| **New conversation started** | A lead starts a new conversation                          |
| **Email captured**           | A lead provides their email address                       |
| **Call scheduled**           | A lead schedules a call                                   |
| **Agent condition met**      | A lead meets a condition configured in an agent's trigger |

{% hint style="info" %}
Chat agent notifications were previously configured inside each Slack, Microsoft Teams, or Webex integration. They now live here alongside every other notification event. For **Agent condition met**, the message content is defined by your agent's trigger configuration — here you only choose where to send it.
{% 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/organization/integrations) before they appear as notification options. See [Communications Integrations](/integrations/communications-integrations) for setup instructions.

<figure><img src="/files/cIGpSEabOpk0jtpJjkep" 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="/files/SO8ZOv2NPgd1moJk1cfj" 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/organization/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/configuration).

## Pronunciations

On the [**Settings > Voice**](https://app.spara.co/settings/voice/configuration) 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="/files/tKfEf2ajYUzJ8uxyFvkJ" 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="/pages/eq4NBnYi5xJAW1KO5prS">/pages/eq4NBnYi5xJAW1KO5prS</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="/pages/ACKd6pnPbAPc0tJeaw4L">/pages/ACKd6pnPbAPc0tJeaw4L</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="/pages/vKjxWK1Ng3kKdgGv4Ara">/pages/vKjxWK1Ng3kKdgGv4Ara</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="/pages/EZmAEuhb64OtsqXcZQNX">/pages/EZmAEuhb64OtsqXcZQNX</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="/pages/1VGi5WdDpJOQzg6wmPBX">/pages/1VGi5WdDpJOQzg6wmPBX</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="/pages/SdcdMiveTtVQ73gpOpL4">/pages/SdcdMiveTtVQ73gpOpL4</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="/pages/rpmTjekoWTY06BaYm0cX">/pages/rpmTjekoWTY06BaYm0cX</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="/pages/xlPP1XLFn59HUVqkg6xW">/pages/xlPP1XLFn59HUVqkg6xW</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="/pages/ytJPv97wDcmZyGMXkAUj">/pages/ytJPv97wDcmZyGMXkAUj</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="/pages/eq4NBnYi5xJAW1KO5prS">/pages/eq4NBnYi5xJAW1KO5prS</a></td><td>Available</td><td>OAuth</td></tr><tr><td><a data-mention href="/pages/ACKd6pnPbAPc0tJeaw4L">/pages/ACKd6pnPbAPc0tJeaw4L</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="/pages/SdcdMiveTtVQ73gpOpL4">/pages/SdcdMiveTtVQ73gpOpL4</a></td><td>Available</td><td>OAuth — uses your existing HubSpot CRM connection</td></tr><tr><td><a data-mention href="/pages/vKjxWK1Ng3kKdgGv4Ara">/pages/vKjxWK1Ng3kKdgGv4Ara</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="/pages/EZmAEuhb64OtsqXcZQNX">/pages/EZmAEuhb64OtsqXcZQNX</a></td><td>Not supported</td><td><em>—</em></td></tr><tr><td><a data-mention href="/pages/rpmTjekoWTY06BaYm0cX">/pages/rpmTjekoWTY06BaYm0cX</a></td><td>Not supported</td><td><em>—</em></td></tr><tr><td><a data-mention href="/pages/xlPP1XLFn59HUVqkg6xW">/pages/xlPP1XLFn59HUVqkg6xW</a></td><td>Not supported</td><td><em>—</em></td></tr><tr><td><a data-mention href="/pages/1VGi5WdDpJOQzg6wmPBX">/pages/1VGi5WdDpJOQzg6wmPBX</a></td><td>Coming soon</td><td><em>—</em></td></tr><tr><td><a data-mention href="/pages/ytJPv97wDcmZyGMXkAUj">/pages/ytJPv97wDcmZyGMXkAUj</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
```


# 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="/files/Erk2QS06AnT52u0joyQc" 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 for full instructions: <https://help.chilipiper.com/hc/en-us/articles/32588330506643-Concierge-Snippet-and-JS-API-in-Demand-Conversion-Platform#01J5TW336Q1V1ZR5T6YD4DBB9B>

### 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 our [https://docs.spara.com/developers/spara-api/query-parameters](https://docs.spara.com/developers/spara-api/query-parameters "mention") guide for more information.

<figure><img src="/files/j67DFi0MpNo6bZmlMS7I" 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="/files/Erk2QS06AnT52u0joyQc" 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 for full instructions: <https://help.chilipiper.com/hc/en-us/articles/32588330506643-Concierge-Snippet-and-JS-API-in-Demand-Conversion-Platform#01J5TW336Q1V1ZR5T6YD4DBB9B>

### 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 our [https://docs.spara.com/developers/spara-api/query-parameters](https://docs.spara.com/developers/spara-api/query-parameters "mention") guide for more information.

<figure><img src="/files/j67DFi0MpNo6bZmlMS7I" 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

When your Hubspot integration is connected, Spara books meetings directly through Hubspot's scheduling API and presents a native, Spara-styled booking experience to your leads. Spara pre-fills every field it already knows about the lead — including any custom required questions on your meeting link — and the lead confirms the rest.

<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>Custom required fields (e.g. company name), when Spara knows the answer</li></ul></td><td><ul><li>Email</li><li>First name</li><li>Last name</li><li>Meeting time and duration</li></ul></td><td>Spara reads the booking details after a meeting has been scheduled and records them on the lead's conversation.</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 %}

Spara requires a Hubspot calendar URL, for example:

```yaml
https://meetings-na2.hubspot.com/<name>
```

When a lead is offered a meeting, Spara matches the calendar URL against the meeting links in your connected Hubspot portal and renders its native booking UI — available times, meeting length options, and the link's required questions — styled to match your brand.

#### iFrame fallback

The lead sees Hubspot's standard embedded scheduler (an iFrame) instead of the native experience when:

* Your Hubspot integration is not connected, or was connected without the meeting scheduler permission
* The calendar URL doesn't match a meeting link in your connected Hubspot portal
* The meeting link requires a legal-consent checkbox
* Hubspot can't be reached at the moment the calendar is shown

All Hubspot UX can be used by your lead in the iFrame format, so booking always works either way.


# 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/organization/integrations), then configure which events trigger notifications in [**Settings > Notifications**](https://app.spara.co/organization/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

How Spara integrates with Slack.

Spara can update your team about live conversations with prospective customers in Slack.

{% 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="/files/qDZTIEHiRTZRncU0pQS2" 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).

## 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; Spara's integration exists only to post notifications into the channel you choose.

<table data-full-width="true"><thead><tr><th>Scope</th><th>What it grants</th><th>Why Spara needs it</th></tr></thead><tbody><tr><td><code>chat:write</code></td><td>Post messages</td><td>Send notifications into the channel you configure.</td></tr><tr><td><code>channels:read</code>, <code>groups:read</code></td><td>View basic info about public and private channels</td><td>List your channels so you can pick one during setup.</td></tr><tr><td><code>channels:join</code></td><td>Join public channels</td><td>Add the Spara bot to the channel you select so it can post there.</td></tr><tr><td><code>channels:manage</code></td><td>Create and manage public channels</td><td>Create the notification channel for you if it doesn't already exist.</td></tr><tr><td><code>users:read</code>, <code>users:read.email</code></td><td>View people in the workspace and their email addresses</td><td>Match notifications to the right sales rep.</td></tr></tbody></table>

### What Spara will and will not do

**Spara will:**

* Post automated notifications into the channel you explicitly configure.
* List your channels and workspace members so you can complete setup.
* Maintain an authenticated connection to deliver those notifications.

**Spara will not:**

* Read, store, analyze, or export your Slack messages. Spara requests no message-history scope, so it cannot read channel or direct-message history.
* Access channels outside of what you configure.
* Monitor, surveil, or index any Slack conversations.


# Microsoft Teams

How Spara integrates with Microsoft Teams.

Spara can send notifications to Microsoft Teams channels.

{% 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="/files/qDZTIEHiRTZRncU0pQS2" 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.

{% 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="/files/qDZTIEHiRTZRncU0pQS2" 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).


# 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/organization/integrations).

| CRM                                                         | Reads from CRM                                   | Writes to CRM                                    | Notes                                                        |
| ----------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------ | ------------------------------------------------------------ |
| [Salesforce](/integrations/crm-integrations/salesforce)     | Any field on Lead, Contact, Account, Opportunity | Any field on Lead, Contact, Account, Opportunity | Supports owner-based routing to specific sales rep calendars |
| [Hubspot (CRM)](/integrations/crm-integrations/hubspot-crm) | Any Contact property                             | Conversation histories, structured field data    | Flexible and easy to integrate with                          |
| [Marketo](/integrations/crm-integrations/marketo)           | Any Lead field                                   | Conversation histories, structured field data    |                                                              |

In addition, Spara provides [Webhooks](/developers/spara-api/webhooks) and [Web API](/developers/spara-api/web-api) for completely customizable workflows and data flows into and out of your CRM.


# Hubspot (CRM)

How Spara syncs lead data with HubSpot CRM using Push and Pull 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 (Pull).

For step-by-step setup instructions, see [Connecting HubSpot](/guides/integration-guides/connecting-hubspot).

<figure><img src="/files/qicBuPgcuQ6gdicsNk8D" alt=""><figcaption><p>The HubSpot integration settings page, showing Push Rules, Pull Rules, and Data Model Sync.</p></figcaption></figure>

## Push Rules

Push Rules control how Spara writes data to HubSpot when a Spara Lead interacts with your agents. This is the primary sync direction — Spara pushes conversation insights and field values into matching HubSpot Contact objects.

Two options control what happens during a push:

* **Update matching, pre-existing HubSpot Contact** — When a Spara Lead matches an existing HubSpot Contact by email address or HubSpot ID, Spara writes data to that Contact.
* **Create HubSpot Contact when no match is found** — If no matching Contact exists, Spara creates a new one. This option is only available when the update option is enabled.

Spara matches Contacts by email address or HubSpot ID. Matching happens as soon as an email is captured in the Spara conversation, and data continues to sync throughout the interaction.

## Pull Rules

Pull Rules control which existing HubSpot Contacts are imported into Spara as Leads. This is useful for leads that exist in HubSpot but have not yet interacted with a Spara agent — Spara can pull them in so your agents and workflows can proactively reach out.

{% hint style="info" %}
Pull Rules are configured by your Spara customer success representative.
{% endhint %}

## Data Model Sync

The Data Model Sync section maps individual Spara Lead fields to HubSpot Contact fields. Each row in the mapping table defines:

* **Spara Lead Field** — the field Spara gathers during conversations (e.g., First name, Company size, or any custom field)
* **HubSpot Contact Field** — the corresponding HubSpot Contact property to write to
* **Write rule** — whether Spara should overwrite any existing value, or only write when the HubSpot field is empty

The Email field is always mapped automatically and cannot be removed. You can add as many additional field mappings as needed.

Field mappings apply to both Push and Pull syncs. For a full list of available Spara fields, visit your [**Data Model**](https://app.spara.co/data-model) or click **View your Data Model** within the HubSpot settings page.

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

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.

## FAQ

### How does Spara match a Lead to a HubSpot Contact?

Spara matches by email address first, then by HubSpot Contact ID. 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 — Spara uses the "Overwrite existing value" write rule for new field mappings. You can change individual mappings to "Update if field is empty" to protect existing HubSpot data.

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

### 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 [https://docs.spara.com/developers/spara-api/query-parameters](https://docs.spara.com/developers/spara-api/query-parameters "mention"). 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.

Additional fields may be synced to Marketo by updating the Field Mapping section of the Marketo integration.


# Salesforce

How Spara syncs lead data with Salesforce using Push and Pull 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 (Pull).

For step-by-step setup instructions, see [Connecting Salesforce](/guides/integration-guides/connecting-salesforce).

| Salesforce Object | Spara writes to Salesforce | Spara reads from Salesforce              |
| ----------------- | -------------------------- | ---------------------------------------- |
| Lead              | Any field                  | Any field                                |
| Contact           | Any field                  | Any field                                |
| Account           | n/a                        | Specific fields — see Account Data below |
| Owner             | n/a                        | Specific fields — see Owner Data below   |

## Push Rules

Push Rules control how Spara writes data to Salesforce when a Spara Lead interacts with your agents. Spara supports independent Push Rules for both Lead and Contact objects — you configure them separately under the Contacts and Leads tabs in [**Settings > Integrations > Salesforce**](https://app.spara.co/organization/integrations/salesforce/manage).

For each record type, two options control push behavior:

* **Update existing Salesforce Contacts/Leads** — When a Spara Lead matches an existing Salesforce record by email address or Salesforce ID, Spara writes data to that record.
* **Create contacts/leads when no match is found** — If no matching record exists, Spara creates a new one. This option is only available when the update option is enabled.

Spara matches records by email address, Salesforce Lead ID (`salesforce_lead_id`), or Salesforce Contact ID (`salesforce_contact_id`). Matching is automatic — you do not need to set up explicit ID syncing.

## Pull Rules

Pull Rules control which existing Salesforce records are imported into Spara as Leads. This is useful for leads that exist in Salesforce but have not yet interacted with a Spara agent — Spara can pull them in so your agents and workflows can proactively reach out.

{% hint style="info" %}
Pull Rules are configured by your Spara customer success representative.
{% endhint %}

## Data Model Sync

The Data Model Sync section maps individual Spara Lead fields to Salesforce fields. Mappings are configured independently for Contacts and Leads using the tabs in the Salesforce settings page.

Each row in the mapping table defines:

* **Spara fields** — the field Spara gathers during conversations (e.g., First name, Company, or any custom field)
* **Salesforce fields** — the corresponding Salesforce field to write to
* **Write rule** — whether Spara should overwrite any existing value, or only write when the Salesforce field is empty

The Email field is always mapped automatically. You can add as many additional field mappings as needed, including the full conversation history via the **Conversation** Spara field.

For a full list of available Spara fields, visit your [**Data Model**](https://app.spara.co/data-model).

## 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 matches an Account name

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

## FAQ

### How does Spara match a Lead to a Salesforce record?

Spara matches by Salesforce Lead ID, Salesforce Contact ID, or email address — in that order. Matching is automatic; you do not need to configure ID syncing in the field mapping table.

### Can I sync to both Lead and Contact objects?

Yes. Push Rules are configured independently for each object type. You can enable create/update for Contacts, Leads, or both.

### Can Spara sync the full conversation history to Salesforce?

Yes. Select the **Conversation** Spara field in the Data Model Sync table and map it to any text field in Salesforce. The full conversation thread for that lead will be written to that field.

### Will Spara overwrite existing data in Salesforce?

By default, yes. New field mappings use "Overwrite existing value." Change individual mappings to "Update if field is empty" to protect existing Salesforce data.

## Troubleshooting

### 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/organization/integrations/salesforce/manage), click **Deauthorize**, then authorize again.

### Disconnecting

To disconnect Salesforce, go to [**Settings > Integrations > Salesforce**](https://app.spara.co/organization/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/organization/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

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/organization/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="/files/X9PHOaUNUXIabJVVXGgX" 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/organization/integrations) and click **Connect** next to SharePoint. Complete the Microsoft OAuth flow to authorize Spara to access your SharePoint tenant.
{% 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 %}

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

Spara emits five events:

| Event name (in GA4 / GTM)  | 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                         |

Use these exact names in your GTM tags, GA4 conversion mappings, and ad platform configurations.

## Choosing how to fire events

There are two ways to send Spara events to GA4. Most customers should pick one based on whether they need the events outside of GA4.

* **Spara native integration** — Spara sends events directly to your GA4 property. Quick to set up, but events only land in GA4. Best when GA4 is your only destination.
* **JavaScript events via Google Tag Manager** — Spara pushes events into the page's `dataLayer`, and you wire them up in GTM. 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 — for example, `demo_scheduled_via_spara` is commonly used as the primary conversion event across Google Ads, Meta, LinkedIn, and Microsoft Ads.

The rest of this page covers both setup paths, then how to actually 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/organization/integrations) and click **Authorize** on the Google Analytics card to start the Google OAuth flow.

<figure><img src="/files/6jgeNSpe8QLgwsbYX6hZ" 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="/files/sgdVoGGH3SASnvfEUxSv" 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="/files/i8Zp6cmEBQnooSsbdDEP" 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 — Google Ads, Meta Pixel, LinkedIn Insight Tag, and so on.

### Step 1: 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 2: 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 3: 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 exact Spara event you want to track — `spara_loaded_via_spara`, `lead_engaged_via_spara`, `email_captured_via_spara`, `calendar_shown_via_spara`, or `demo_scheduled_via_spara`. The name must match the dataLayer exactly.
5. **Save** the trigger.

To track multiple Spara events, repeat with a separate tag and trigger for each event name.

### Step 4: Publish

Save the tag, submit your container, and publish a new workspace version.

### Step 5: 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.

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 `demo_scheduled_via_spara` (and any other Spara events you care about) 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.
* Fires the five events into GA4 (via the native integration) or into the `dataLayer` for GTM to consume.
* 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` — it's the direct equivalent of a demo-request form submit and should be treated the same way in GA4 and downstream ad platforms.


# 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](/build/channels/chat/spara-navigator). That same conversation might continue when the lead returns 48 hours later and engages with [Spara Navigator](/build/channels/chat/spara-navigator).

All interfaces rely on [Query Parameters](/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 [Javascript API](/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 [https://docs.spara.com/developers/spara-api/query-parameters](https://docs.spara.com/developers/spara-api/query-parameters "mention") 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="/files/4sgw2jiPDQKHdC1a0XOK" 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 [https://docs.spara.com/guides/using-wildcard-url-patterns](https://docs.spara.com/guides/using-wildcard-url-patterns "mention").
* **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.

{% 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

*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 [https://docs.spara.com/developers/spara-api/query-parameters](https://docs.spara.com/developers/spara-api/query-parameters "mention")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 [https://docs.spara.com/developers/spara-api/javascript-api](https://docs.spara.com/developers/spara-api/javascript-api "mention").

*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 [https://docs.spara.com/agents](https://docs.spara.com/agents "mention") and [https://docs.spara.com/agents/channels/email](https://docs.spara.com/agents/channels/email "mention").

### Step 1: Connect email address

Spara Email agents send emails from an authenticated email address.

* Navigate to the [Email Configuration](https://app.spara.co/organization/email-configuration) 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 [https://docs.spara.com/agents/workflows](https://docs.spara.com/agents/workflows "mention") 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 [Broken mention](broken://spaces/reCGkFdsmuPJzGP9ZgGA/pages/IaZshnYyIZPgpEyToR3d) and [Broken mention](broken://spaces/reCGkFdsmuPJzGP9ZgGA/pages/W5Y15CPFYBYF4jd7uts9).

## 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://app.gitbook.com/s/reCGkFdsmuPJzGP9ZgGA/agents/agent-overview/ai-instructions) with instructions for how it should respond to incoming texts.
3. Build [Workflows](/build/workflows) using the [Send Text Step](/build/workflows/steps/send-text) step 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.


# 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 [https://docs.spara.com/agents/channels](https://docs.spara.com/agents/channels "mention") (the channels it engages buyers through) and [https://docs.spara.com/agents/workflows](https://docs.spara.com/agents/workflows "mention") (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 [https://docs.spara.com/agents](https://docs.spara.com/agents "mention").

<figure><img src="/files/lW0n0TePXl2oBycegdjX" 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 ([https://docs.spara.com/agents/channels/chat/spara-navigator](https://docs.spara.com/agents/channels/chat/spara-navigator "mention"), [https://docs.spara.com/agents/channels/chat/spara-smartbar](https://docs.spara.com/agents/channels/chat/spara-smartbar "mention"), or [https://docs.spara.com/agents/channels/chat/spara-fullscreen](https://docs.spara.com/agents/channels/chat/spara-fullscreen "mention"))
* **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 [https://docs.spara.com/agents/channels/configuring](https://docs.spara.com/agents/channels/configuring "mention").

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 [https://docs.spara.com/agents/channels/configuring/a-b-testing](https://docs.spara.com/agents/channels/configuring/a-b-testing "mention") 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 [https://docs.spara.com/agents/workflows/steps](https://docs.spara.com/agents/workflows/steps "mention") and appear in their own section of the Agent, separate from capabilities. See [https://docs.spara.com/agents/workflows/configuring](https://docs.spara.com/agents/workflows/configuring "mention") 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 [https://docs.spara.com/agents/channels/configuring/testing](https://docs.spara.com/agents/channels/configuring/testing "mention") freely, then publish when you're ready. See [https://docs.spara.com/agents/channels/configuring/saving-and-publishing](https://docs.spara.com/agents/channels/configuring/saving-and-publishing "mention").
{% 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, see the [Data Model](/build/data-model) documentation.

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 [https://app.gitbook.com/s/reCGkFdsmuPJzGP9ZgGA/agents/agent-overview/ai-instructions](https://app.gitbook.com/s/reCGkFdsmuPJzGP9ZgGA/agents/agent-overview/ai-instructions "mention").
* **Workflow Prompt steps** — Custom AI instructions that run against lead data to classify, research, or extract information. See [Broken mention](broken://spaces/reCGkFdsmuPJzGP9ZgGA/pages/NvEphcCeLC6PKYIX7rqH).
* **Email sequences** — AI instructions embedded in email templates tell the agent how to personalize or vary the content.

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                    |
| Workflow — Send Text  | SMS message body                 | Variables                    |
| 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 [https://docs.spara.com/platform/media](https://docs.spara.com/platform/media "mention").

{% 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="/files/o4q2XUpy7GThtW2SOeEy" 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                                                            |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| [https://app.gitbook.com/s/reCGkFdsmuPJzGP9ZgGA/agents/agent-overview/ai-instructions](https://app.gitbook.com/s/reCGkFdsmuPJzGP9ZgGA/agents/agent-overview/ai-instructions "mention") | The core behavior for Chat, Email, Voice, and Text agents                      |
| [https://app.gitbook.com/s/reCGkFdsmuPJzGP9ZgGA/agents/workflows/prompt](https://app.gitbook.com/s/reCGkFdsmuPJzGP9ZgGA/agents/workflows/prompt "mention")                             | 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](/build/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](/build/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](/build/workflows/steps/condition) step to branch logic based on lead data (e.g., different paths for enterprise vs. SMB)
* Use a [Broken mention](broken://spaces/reCGkFdsmuPJzGP9ZgGA/pages/NvEphcCeLC6PKYIX7rqH) step to research the lead's company and personalize downstream emails
* Add a [Notify Step](/build/workflows/steps/notify) step 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 [https://docs.spara.com/agents/channels/chat](https://docs.spara.com/agents/channels/chat "mention").

## 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="/files/isOvV0MVyHTuIMWCzug2" 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/organization/api) 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 [https://docs.spara.com/developers/spara-api/web-api](https://docs.spara.com/developers/spara-api/web-api "mention").


# Product Demo Use Cases

Common deployment patterns for Spara's Product Demo capability — from website CTAs to outbound campaigns and in-app onboarding.

The [https://docs.spara.com/agents/channels/product-demo](https://docs.spara.com/agents/channels/product-demo "mention") 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 [https://docs.spara.com/developers/spara-api/javascript-api](https://docs.spara.com/developers/spara-api/javascript-api "mention").

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

Use `SparaActions.openProductDemo()` to launch a Product Demo session programmatically. Add a query parameter to your landing page URL (e.g., `?demo`) and include JavaScript on your site that checks for the parameter and opens the demo automatically:

```javascript
if (window.location.search.includes('demo')) {
  SparaActions.openProductDemo();
}
```

Then link to `https://yoursite.com/?demo` in your outgoing emails, LinkedIn messages, or SMS campaigns. When a recipient clicks the link, your landing page loads and the Product Demo opens automatically.

See [https://docs.spara.com/developers/spara-api/javascript-api](https://docs.spara.com/developers/spara-api/javascript-api "mention") for additional setup instructions and code examples.

## 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 `?demo` 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 `?demo` 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 `?demo` 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., `?demo&utm_source=email`, `?demo&utm_source=linkedin`) so your analytics platform can attribute sessions to the right source.


# 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](/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 (Pull)
* Read Account and Owner data to personalize agent behavior

{% stepper %}
{% step %}

#### Navigate to Integrations

Go to [**Settings > Integrations**](https://app.spara.co/organization/integrations) and find the Salesforce card. Click **Authorize**.

{% hint style="info" %}
You need Manager or Integrator permissions to connect integrations. See [https://docs.spara.com/platform/settings/user-management](https://docs.spara.com/platform/settings/user-management "mention") 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 %}

#### Configure Push Rules

On the Manage page, use the **Contacts** and **Leads** tabs to configure Push Rules independently for each object type:

* **Update existing records** — Spara writes data to matching Salesforce Contacts or Leads
* **Create records when no match is found** — Spara creates a new record if no match exists (requires the update option to be enabled)

Spara matches records by email address or Salesforce object ID automatically.
{% endstep %}

{% step %}

#### Map fields

Under **Data Model Sync**, set up field mappings between Spara Lead fields and Salesforce fields. Configure mappings separately for Contacts and Leads using the tabs.

For each mapping:

1. Choose a **Spara field** (e.g., First name, Company, or any custom field)
2. Choose the corresponding **Salesforce field**
3. Set the **Write rule** — overwrite existing values, or only write when the field is empty

To sync the full conversation history, map the **Conversation** Spara field to any Salesforce text field.

For a full list of available Spara fields, go to [**Data Model**](https://app.spara.co/data-model).
{% 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/organization/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)](/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 (Pull)

{% stepper %}
{% step %}

#### Navigate to Integrations

Go to [**Settings > Integrations**](https://app.spara.co/organization/integrations) and find the HubSpot card. Click **Authorize**.

{% hint style="info" %}
You need Manager or Integrator permissions to connect integrations. See [User Management](/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 %}

#### Configure Push Rules

Under **Push Rules**, enable the sync behaviors you want:

* **Update matching, pre-existing HubSpot Contact** — Spara writes data to a Contact when a Lead matches by email or HubSpot ID
* **Create HubSpot Contact when no match is found** — Spara creates a new Contact if no match exists (requires the update option to be enabled)
  {% endstep %}

{% step %}

#### Map fields

Under **Data Model Sync**, set up field mappings between Spara Lead fields and HubSpot Contact properties. For each mapping:

1. Choose a **Spara Lead Field** (e.g., First name, Company, or any custom field)
2. Choose the corresponding **HubSpot Contact Field**
3. Set the **Write rule** — overwrite existing values, or only write when the field is empty

For a full list of available Spara fields, click **View your Data Model** within the HubSpot settings page, or go to [**Data Model**](https://app.spara.co/data-model).
{% 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/organization/integrations/hubspot/manage), click **Deauthorize**, then authorize again.

### Disconnecting

To disconnect HubSpot, go to [**Settings > Integrations > HubSpot**](https://app.spara.co/organization/integrations/hubspot/manage) and click **Deauthorize**. Your field mappings are preserved if you reconnect later.


# Setting Up HubSpotUTK Cookie Tracking

How to set up Hubspot attribution to link contacts captured in Spara to hubspotutk cookie tracking data.

The `hubspotutk` cookie is set by HubSpot's tracking script and stores a unique visitor token used for contact attribution. By calling HubSpot's `identify` method from Spara's JavaScript API `onUserMessageSent()` event, you can associate a visitor's session with their HubSpot contact record.

### Prerequisites

* The **HubSpot tracking script** is installed on your site. [Hubspot's guide to install the tracking code.](https://knowledge.hubspot.com/reports/install-the-hubspot-tracking-code)
* The [**Spara embed script**](/guides/installation-guides/readme/installing-spara-navigator) is installed on your site.

### Add the identify call

Use Spara's `onUserMessageSent()` event (see [Javascript API](https://docs.spara.com/developers/spara-api/javascript-api)) to extract the visitor's email. Then, call `identify` to merge the visitor to the hubspot cookie data and `trackPageView` to push the identity to HubSpot.

<pre class="language-html"><code class="lang-html"><strong>&#x3C;script type="text/javascript" src="https://app.spara.co/embed-&#x3C;app_id>.js">&#x3C;/script>
</strong>&#x3C;script>
  Spara = {
    onUserMessageSent: function (text) {
      // extract email from user message
      function extractEmail(text) {  
        const match = text.match(/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/);
        return match ? match[0] : null;
      }

      const email = extractEmail(text);

      if (window._hsq &#x26;&#x26; email) {
        window._hsq.push(["identify", { email }]);
        window._hsq.push(["trackPageView"]);
      }
    },
  }
&#x3C;/script>
</code></pre>

**Note:** `identify` sets the identity in HubSpot's tracker memory only. A separate `trackPageView` or `trackEvent` call is required to actually send the data to HubSpot.

### Single-page application (SPA) setup

If your site uses Next.js or React, page navigations don't trigger full reloads, so HubSpot won't automatically track route changes or send identity data.

1. Follow the identify call instructions above.
2. Create a `HubSpotPageView.tsx` component to call `trackPageView` on every route change:

```tsx
'use client';
import { usePathname } from 'next/navigation';
import { useEffect } from 'react';

export default function HubSpotPageView() {
  const pathname = usePathname();

  useEffect(() => {
    if (window._hsq) {
      window._hsq.push(["trackPageView"]);
    }
  }, [pathname]);

  return null;
}
```

3. Add it to your root layout (`app/layout.tsx`):

```tsx
import HubSpotPageView from './HubSpotPageView';

<body>
  <HubSpotPageView />
  {children}
</body>
```


# Technical documentation

Use Spara's API and data model to create tailored GTM solutions within your existing stack.

Welcome to Spara's technical documentation! The Spara platform is designed for your GTM colleagues to effortlessly build, manage, and iterate on agentic processes. This section is for developers looking to install and integrate Spara into your company's existing stack.

### Jump right in

Learn about:

* [Web API](/developers/spara-api/web-api) and [Webhooks](/developers/spara-api/webhooks)
* [Javascript API](/developers/spara-api/javascript-api)
* [Query Parameters](/developers/spara-api/query-parameters)


# Web API

Spara's Web API supports completely customizable configurations.

The Spara platform offers powerful integration capabilities through a suite of web API endpoints. Webhooks provide real-time notifications of lead events via `POST` requests to a customer-defined endpoint, enabling automated workflows, external system synchronization, and timely responses to key updates. APIs allow customers to update and enrich lead data, manage user information, and influence the behavior of our AI engine - supporting deep, flexible integrations. All API interactions must be conducted over `HTTPS` to ensure secure communication.

Both webhooks and API support basic data types via JSON. These types are not explicitly identified in request values.

* `string`, ex. `"John Doe"`
* `integer`, ex. `100`
* `boolean`, i.e. `true` or `false`

Malformed values will be rejected, ex. `John Doe`. Take care to not cast integer or boolean values as strings, ex. `"100"`.

{% hint style="danger" %}
Important: Spara does not support using this API AND a native CRM integration together, as this may result in data conflicts or unexpected behavior.

For example, Spara does not support using both the API and native Salesforce integration together.
{% endhint %}

### Schema

Spara models leads as a single object with any number of arbitrary fields. For example, if you configure Spara to ask your leads the question "What industry is your company in?" you may decide to name that field `industry`.

The following fields are standard for all leads:

```
# Info about the lead.
email(string)
company_name (string)
first_name (string)
last_name (string)
phone_number (string)
job_title (string)
num_employees (integer)
```

In addition, some leads may have an assigned sales rep in Salesforce:

```
# Info about Salesforce objects connected to the lead. All fields are strings.
sales_rep_name
salesforce_account_id- The unique identifier of the Salesforce account
salesforce_account_name - The name of the Salesforce account which usually represents the company name
salesforce_account_owner_email - The email address of the Salesforce account owner (account's default sales rep)
salesforce_account_owner_id - The unique identifier of the Salesforce account owner
salesforce_account_owner_name - The first & last names of the Salesforce account owner
salesforce_account_website - The website URL associated with the Salesforce account
salesforce_assigned_sales_rep_email - The email address of the lead's assigned sales rep
salesforce_assigned_sales_rep_id - The unique identifier of the lead's assigned sales rep
salesforce_assigned_sales_rep_name
```

### Authentication

The base URL for all API requests is: `https://api.spara.co/v1/`

All requests to the API must be authenticated using a Bearer Token in the Authorization header. Each customer can generate one or more API Keys via the user dashboard.

Header Example:

`Authorization: Bearer YOUR_API_KEY`

### Error Responses

* `400 Bad Request`: The request body is malformed JSON or contains invalid data for the metadata fields (e.g., wrong data type). The response body will provide details on the specific error.
* `401 Unauthorized`: Missing or invalid API key.
* `403 Forbidden`: API key does not have access to the specified lead.
* `404 Not Found`: Lead with the provided id does not exist.
* `422 Unprocessable Entity`: The request was well-formed, but semantic validation failed (e.g., attempting to set a field to a value that is logically impossible or not allowed, attempting to update read-only fields (e.g., ip\_address)).
* `429 Too Many Requests`: The number of requests has exceeded the [rate limits](#rate-limiting).

## Resource: Leads

The primary resource for this API is leads.

#### Search Leads (GET)

This endpoint allows you to search for leads by their email address. The response will include a unique identifier (id) for each lead, and all known fields about the lead. Zero (no lead found), one (only one lead found), or multiple leads (if there are multiple leads with the same email address) could be returned from this endpoint.

Endpoint: `/leads/search`

Method: `GET`

Description: Retrieves the full details of the leads that match the search criteria, including their current fields. If no query parameters are provided, then all leads will be returned.

Query Parameters:

* `email` (string, optional): Email for the lead you wish to retrieve (case insensitive)
* `start` (epoch timestamp integer, optional): Filter by lead `created_at >= start` — a static window over when the lead was first created.
* `end` (epoch timestamp integer, optional): Filter by lead `created_at <= end` — same static window as `start`.
* `last_activity_from` (epoch timestamp integer, optional): Filter by lead `last_activity_at >= last_activity_from` — a rolling window over the lead's most recent activity. A lead created months ago that engaged today will match a "today" filter; a lead with no activity since its creation will not.
* `last_activity_to` (epoch timestamp integer, optional): Filter by lead `last_activity_at <= last_activity_to` — same rolling semantics as `last_activity_from`.
* `start_after_id` (string, optional): Pagination cursor. The `id` of the last lead from the previous page; results begin after it.

All four time-based parameters accept Unix epoch seconds and are inclusive (`>=` / `<=`).

Pagination: Results are returned in pages of up to 1000 leads, ordered oldest-first. The response includes `has_more` (whether another page exists) and `last_id` (the `id` of the last lead in the page, or `null` if empty). To fetch the next page, repeat the request with `start_after_id` set to `last_id`, and keep going until `has_more` is `false`. All other query parameters must stay the same across pages.

Example Request & Success Response:

```json
GET https://api.spara.co/v1/leads/search?email=jane.doe@test.com&start=1749470400&end=1749492000
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json


Example Success Response (HTTP 200 OK):

{
  "object": "list",
  "data": [
    {
      "object": "lead",
      "id": "ABC12345",
      "created_at": "2025-06-09T12:00:00Z",
      "updated_at": "2025-06-09T15:15:00Z",
      "last_activity_at": "2025-06-09T15:15:00Z",
      "url": "https://app.spara.co/conversations/ABC12345",
      "data": {
        "email": "jane.doe@test.com",
        "first_name": "Jane",
        "last_name": "Doe",
        "employee_count": "50",
        "is_customer": "false",
        "is_interested": "true"
      },
      "conversation": {
        "created_at": "2025-06-09T12:00:00Z",
        "initial_url": "https://www.my-site.co/chat/jJyVt7TQ5",
        "messages": []
      },
      "calls": [
        {
          "started_at": "2025-12-12T16:56:47Z",
          "ended_at": "2025-12-12T16:59:30Z",
          "summary": "The lead called interested in purchasing...",
          "events": [],
          "data": {
            "is_interested": true
          }
        }
      ]
    }
  ],
  "has_more": false,
  "last_id": "ABC12345"
}
```

#### Get Lead (GET)

This endpoint allows you to retrieve the current state of the lead's fields. This is useful for understanding the existing data before performing an update.

Endpoint: `/leads/{id}`

Method: `GET`

Description: Retrieves the full details of a specific lead, including their current fields.

Path Parameters:

* `id` (string, required): The unique identifier for the lead you wish to retrieve.

Example Request & Success Response:

```json
GET https://api.spara.co/v1/leads/ABC12345
Authorization: Bearer YOUR_API_KEY


Example Success Response (HTTP 200 OK):

{
  "object": "lead",
  "id": "ABC12345",
  "created_at": "2025-06-09T12:00:00Z",
  "updated_at": "2025-06-09T15:15:00Z",
  "url": "https://app.spara.co/conversations/ABC12345", // link to conversation
  "data": {
    "email": "jane.doe@test.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "employee_count": 50,
    "is_customer": false
  },
    "conversation": {
    "created_at": "2025-06-09T12:00:00Z",
    "initial_url": "https://www.my-site.co/chat/jJyVt7TQ5",
    "messages": []
  },      
  "calls": [
    {
      "started_at": "2025-12-12T16:56:47Z",
      "ended_at": "2025-12-12T16:59:30Z",
      "summary": "The lead called interested in purchasing...",
      "events": []
    }
  ]
}
```

#### Create Lead (POST)

This endpoint allows you to create a new lead with or without pre-existing fields that you may have collected externally (e.g., from your CRM).

Endpoint: `/leads`

Method: `POST`

Description: Create a new lead

Content-Type: `application/json`

Body: A JSON object containing the fields you wish to create for the lead

Example Request & Success Response:

```json
POST https://api.spara.co/v1/leads
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "first_name": "Jane",
  "last_name": "Doe",
  "num_employees": 53
}


Example Success Response (HTTP 200 OK):
{
  "object": "lead",
  "id": "ABC12345",
  "created_at": "2025-06-09T12:00:00Z",
  "updated_at": "2025-06-09T15:15:00Z",
  "url": "https://app.spara.co/conversations/ABC12345", // link to conversation
  "data": {
    "email": "jane.doe@test.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "employee_count": 50,
    "is_customer": false
  },
    "conversation": {
    "created_at": "2025-06-09T12:00:00Z",
    "initial_url": "https://www.my-site.co/chat/jJyVt7TQ5",
    "messages": []
  },      
  "calls": [
    {
      "started_at": "2025-12-12T16:56:47Z",
      "ended_at": "2025-12-12T16:59:30Z",
      "summary": "The lead called interested in purchasing...",
      "events": []
    }
  ]
}
```

#### Update Lead (PATCH)

This endpoint allows you to enrich the lead by providing pre-existing fields that you may have collected externally (e.g., from your CRM).

Endpoint: `/leads/{id}`

Method: `PATCH`

Description: Update information on the lead

Path Parameters:

* `id` (string, required): The unique identifier for the lead you wish to update.

Content-Type: `application/json`

Body: A JSON object containing the fields you wish to update.

Example Request:

```json
PATCH https://api.spara.co/v1/leads/ABC12345
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json


{
  "first_name": "Jane",
  "last_name": "Doe",
  "num_employees": 53
}
```

A success response will return `200` without any additional data.

#### Call Lead (POST)

This endpoint triggers an outbound voice call to an existing lead using your Voice agent.

Endpoint: `/leads/{id}/call`

Method: `POST`

Description: Initiates an outbound call to the lead's phone number. The lead must have a phone number on record, and the Voice agent must be published with a phone number configured.

Path Parameters:

* `id` (string, required): The unique identifier for the lead to call.

Content-Type: `application/json`

Body:

* `voice_agent_id` (string, required): The UUID of the Voice agent that should place the call. The agent must be published and must have a phone number assigned on its Configuration tab — that phone number is used as the caller ID.
* `call_mode` (string, optional): Either `"live"` (default) for a real call to the lead's phone, or `"qa"` for a test call. Use `"qa"` to dry-run the integration without dialing the lead's phone number.

Example Request:

```json
POST https://api.spara.co/v1/leads/ABC12345/call
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "voice_agent_id": "AGENT_UUID"
}
```

A success response returns `200`. The response is returned as soon as the call is queued — the actual call is placed asynchronously. To receive the call result (transcript, summary, recording, outcome), subscribe to the `Voice Call Ended` event on your webhook endpoint. See [Webhooks](/developers/spara-api/webhooks) for the event schema.

Error responses specific to this endpoint:

* `400 Bad Request`: Lead has no phone number, no Voice agent found, or the agent has no phone number configured.
* `404 Not Found`: Lead or specified Voice agent not found in your organization.

{% hint style="info" %}
**Concurrency limit.** Outbound calls are subject to a cap of **5 calls per second**. A dedicated per-account version of this cap ships by June 2026. For most use cases this is well above your actual call rate. If you anticipate bursty or high-volume dialing (large batch sends, telemarketing-style campaigns), contact your Spara representative ahead of time so we can confirm headroom.
{% endhint %}

{% hint style="warning" %}
Do not orchestrate the same Voice agent through both this API and a Spara Workflow simultaneously. Pick one system to own the call cadence — splitting workflow logic across both creates coordination overhead and makes call behavior hard to reason about. If your external workflow tool drives the cadence, use this API and disable any equivalent [Call Phone](https://docs.spara.com/agents/workflows/steps/call-phone) step in Spara Workflows.
{% endhint %}

### Rate Limiting

To ensure fair usage and system stability, API requests are subject to rate limits. If you exceed the allocated rate limits, your requests will be temporarily blocked, and you will receive an `HTTP 429 Too Many Requests` status code.

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.

Outbound calls placed via [#call-lead-post](#call-lead-post "mention") are subject to a separate concurrency cap of **5 calls per second**. A dedicated per-account version of this cap ships by June 2026.


# Webhooks

Spara's Webhook support completely customizable configurations.

The Spara platform offers powerful integration capabilities through both outbound webhooks and a [Web API](/developers/spara-api/web-api).

Webhooks provide real-time notifications of lead events via `POST` requests to a customer-defined endpoint, enabling automated workflows, external system synchronization, and timely responses to key updates. APIs allow customers to update and enrich lead data, manage user information, and influence the behavior of our AI engine - supporting deep, flexible integrations. All API interactions must be conducted over `HTTPS` to ensure secure communication.

Both webhooks and API support basic data types via JSON. These types are not explicitly identified in request values.

* `string`, ex. `"John Doe"`
* `integer`, ex. `100`
* `boolean`, i.e. `true` or `false`

Malformed values will be rejected, ex. `John Doe`. Take care to not cast integer or boolean values as strings, ex. `"100"`.

{% hint style="warning" %}
Important: Spara does not recommend using webhooks to update information also being updated by a native integration, as this may result in data conflicts or unexpected behavior.

For example, using information from webhooks to update Salesforce records in conjunction with Spara's native Salesforce integration.
{% endhint %}

### Schema

Spara models leads as a single object with any number of arbitrary fields. For example, if you configure Spara to ask your leads the question "What industry is your company in?" you may decide to name that field `industry`.

The following fields are standard for all leads:

```
# Info about the lead.
email(string)
company_name (string)
first_name (string)
last_name (string)
phone_number (string)
job_title (string)
num_employees (integer)
```

In addition, some leads may have an assigned sales rep in Salesforce:

```
# Info about Salesforce objects connected to the lead. All fields are strings.
sales_rep_name
salesforce_account_id- The unique identifier of the Salesforce account
salesforce_account_name - The name of the Salesforce account which usually represents the company name
salesforce_account_owner_email - The email address of the Salesforce account owner (account's default sales rep)
salesforce_account_owner_id - The unique identifier of the Salesforce account owner
salesforce_account_owner_name - The first & last names of the Salesforce account owner
salesforce_account_website - The website URL associated with the Salesforce account
salesforce_assigned_sales_rep_email - The email address of the lead's assigned sales rep
salesforce_assigned_sales_rep_id - The unique identifier of the lead's assigned sales rep
salesforce_assigned_sales_rep_name
```

### Webhook Registration & Events

Each customer can register one or more webhook endpoints in the Settings > [Webhooks](https://app.spara.co/organization/api-webhooks) page. Use "Add Webhook" to register additional endpoints, and the trash icon to remove one. Each endpoint has its own URL and its own set of subscribed events, so you can route different events to different destinations.

The following information is required to register a webhook:<br>

* **Webhook URL**: A valid `HTTPS` endpoint where webhook payloads will be sent. Test payloads may be triggered by clicking the "Test" button.
* **API Key(s)**: Customers must create at least one API Key to enable outbound webhooks. API Keys are shared across all of an organization's webhook endpoints.
* **Events:** Select which events trigger webhook notifications for that endpoint.
  * See table below for all event types.
  * NB: If multiple events are triggered at the same time, they are grouped into a single webhook call.
  * Each endpoint only receives the events it is subscribed to; an event is delivered to every endpoint subscribed to it.

<table data-full-width="true"><thead><tr><th>Event Name</th><th>When the webhook event is triggered</th><th>Example</th></tr></thead><tbody><tr><td><code>Lead Created</code></td><td>A new lead is created.</td><td></td></tr><tr><td><code>Spara Fact Updated</code></td><td>Spara learns a new fact from conversing with the lead.</td><td>A lead sends the message "My email is joe@test.com."</td></tr><tr><td><code>External Fact Updated</code></td><td>Spara learns of a new fact via query parameters or API.<br><br>NB: Will not trigger when a new lead is created if <code>Lead created</code> is not selected.</td><td></td></tr><tr><td><code>Lead Enrichment Fact Updated</code></td><td>Spara learns of a new fact via lead enrichment.</td><td></td></tr><tr><td><code>Lead Message Sent</code></td><td>The lead sends a message.</td><td></td></tr><tr><td><code>AI Message Sent</code></td><td>Spara Chat AI sends a message.</td><td></td></tr><tr><td><code>Human Message Sent</code></td><td>Human uses "Manual Mode" to send a message to the lead.</td><td></td></tr><tr><td><code>Voice Call Ended</code></td><td>A voice call with the lead ends. The payload includes call timestamps, the Voice agent that handled the call, a short summary, and the transcript.</td><td></td></tr></tbody></table>

<figure><img src="/files/DDU5IfN999gPXmdTzHzH" alt=""><figcaption></figcaption></figure>

### Differentiating voice, chat, and email events

Every webhook payload includes a `source` field describing which channel produced the event. Filter on this field to route events in your handler:

| Source  | Channel            |
| ------- | ------------------ |
| `voice` | Voice call         |
| `chat`  | Chat conversation  |
| `email` | Email conversation |

### Delivery Format

Each webhook is sent as a JSON payload in the body of an HTTP POST request. All known fields about a lead will be returned in each webhook event. The standard format is as follows:

```json
POST /your-endpoint
Content-Type: application/json
X-API-Key: <API Key>

// lead.created
{
  "event": "lead.created",
  "timestamp": "2025-09-18T18:48:08Z",
  "object": "lead",
  "id": "GTvcBRZd",
  "url": "https://app.spara.co/conversations/GTvcBRZd",
  "created_at": "2025-09-18T18:48:08Z",
  "updated_at": "2025-09-18T18:48:08Z",
  "data": {
    "ip_country": "US",
    "ip_region": "New York",
    "ip_city": "New York",
    "current_url": "https://www.my-site.co/chat/jJyVt7TQ5",
    "conversation_url": "https://app.spara.co/conversations/GTvcBRZd"
  },
  "conversation": {
    "created_at": "2025-09-18T18:48:08Z",
    "initial_url": "https://www.my-site.co/chat/jJyVt7TQ5",
    "device": "DESKTOP",  // most recent device used
    "initial_device": "DESKTOP",  // first device used
    "messages": []
  }
}

// lead.updated
{
  "event": "lead.updated",
  "timestamp": "2025-09-18T18:48:38Z",
  "object": "lead",
  "id": "GTvcBRZd",
  "url": "https://app.spara.co/conversations/GTvcBRZd",
  "created_at": "2025-09-18T18:48:08Z",
  "updated_at": "2025-09-18T18:48:38Z",
  "data": {
    "ip_country": "US",
    "ip_region": "New York",
    "ip_city": "New York",
    "current_url": "https://www.my-site.co/chat/jJyVt7TQ5",
    "conversation_url": "https://app.spara.co/conversations/GTvcBRZd",
    "first_name": "Jane"
  },
  "conversation": {
    "created_at": "2025-09-18T18:48:08Z",
    "initial_url": "http://localhost:5001/chat/jJyVt7TQ5",
    "device": "DESKTOP",  // most recent device used
    "initial_device": "DESKTOP",  // first device used
    "messages": [
      {
        "sent_by": "AI",
        "created_at": "2025-09-18T18:48:08Z",
        "text": "Hi, any questions I can help with?",
        "asset": "ACME Overview.mp4"
      },
      {
        "sent_by": "LEAD",
        "created_at": "2025-09-18T18:48:13Z",
        "text": "hi my name is Jane"
      },
      {
        "sent_by": "AI",
        "created_at": "2025-09-18T18:48:16Z",
        "text": "Hello! How can I assist you with Acme-Eng's services today?"
      },
      {
        "sent_by": "MANUAL",
        "created_at": "2025-09-18T18:48:38Z",
        "text": "Hi this is your sales rep. I am taking over the conversation."
      }
    ]
  }
}
```

### Security

To ensure secure transmission, all webhook payloads include the customer's oldest active API Keys in the `X-API-Key` header. Customers should verify the API Key before trusting the contents of the webhook.

Webhook URLs must use `HTTPS`. Plain `HTTP` endpoints will be rejected during registration.

### Retry Policy

If a webhook delivery fails (i.e., a non-2xx HTTP response or a timeout), our system will automatically retry the request using exponential backoff. Up to 2 retries (in addition to the original attempt) will be made. Customers are encouraged to design their endpoints to respond quickly and handle retries idempotently.

### Best Practices

* Validate the API Key of incoming webhook requests before processing.
* Respond to webhooks with a `200 OK` status as quickly as possible.
* Offload heavy processing to background jobs or message queues.
* Log and monitor webhook delivery attempts to aid in troubleshooting.


# Javascript API

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

## Subscribing to Spara conversion events

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

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

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

{% hint style="info" %}
If a visitor closes the browser tab mid-demo, no `onDemoEnded` event fires, so started/ended counts won't reconcile exactly.
{% endhint %}

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

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

## Reading Javascript events from Spara

{% hint style="info" %}
The `window.Spara` callbacks below still work, but they support only one handler each and don't identify which widget an event came from. Prefer the [`SparaActions.on*` subscriptions](#subscribing-to-spara-conversion-events) for new integrations.
{% endhint %}

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

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

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

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

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

## Writing information to Spara using Javascript

Spara's Javascript API exposes methods to write information to Spara Lead objects. For more information on how leads are represented in our database see our documentation on Lead [Webhooks](/developers/spara-api/webhooks#schema).

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

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

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

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

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

#### Note on Query Parameters

A reminder that Spara automatically ingests all query parameters from your webpages, as long as they are mapped in the Spara platform. See [Query Parameters](/developers/spara-api/query-parameters) for more information.

## Opening Spara using Javascript

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

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

`openChat` and `openSmartbarChat` accept the same optional arguments:

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

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

#### How to open Product Demo from a link or email CTA

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

To set this up:

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

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

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

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

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

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

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

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

#### Supported Identifiers

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

* gclid (Google Click ID)
* wbraid / gbraid (Google iOS Privacy-compliant IDs)
* li\_fat\_id (LinkedIn First-Party Tracking)
* fbclid (Facebook Click ID)

***

#### Step 1: The "Universal" Tracking Script

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

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

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


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


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


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


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

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

***

#### Step 2: Create "Reader" Variables

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

1. Go to Variables.
2. Under User-Defined Variables, click New.
3. Variable Type: 1st Party Cookie.
4. Cookie Name: li\_fat\_id (Must match the name in the script map above).
5. URI Decode Cookie: ☑️Check this box.
6. Name: Cookie - li\_fat\_id.
7. Save.

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

| Variable Name        | Cookie Name |
| -------------------- | ----------- |
| Cookie - gclid       | gclid       |
| Cookie - wbraid      | wbraid      |
| Cookie - li\_fat\_id | li\_fat\_id |

***

#### Step 3: Verification (QA)

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

1. Visit your site with a fake ID:
2. <https://www.yourdomain.com/?li\\_fat\\_id=TEST\\_123\\&gclid=TEST\\_456>
3. Inspect the Cookies:
4. Right-click the page > Inspect.
5. Go to the Application tab (Chrome) or Storage tab (Firefox).
6. Expand Cookies on the left and select your domain.
7. Confirm the Data:
8. You should see li\_fat\_id with value TEST\_123.
9. You should see gclid with value TEST\_456.
10. Domain: Ensure it shows .yourdomain.com (this confirms it will work across subdomains).
11. Expires: Ensure the date is roughly 90 days in the future.

***

#### Step 4: Passing IDs to Spara

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

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

```javascript
// Example Spara Identification Call
Spara.identify({
  email: 'user@example.com',
  // Pass the GTM Variables we created in Step 2
  gclid: '{{Cookie - gclid}}', 
  li_fat_id: '{{Cookie - li_fat_id}}',
  wbraid: '{{Cookie - wbraid}}'
});
```

## FAQ

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

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

For example, on a pricing page:

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

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

To make this work, Navigator should be loaded in [Spara Navigator](/build/channels/chat/spara-navigator#preview-mode-hidden) so the chat only appears when the CTA is clicked.


# Query Parameters

How to pass information into Spara via query parameters.

Spara can ingest any query parameter on any webpage that loads a Spara [Chat Agent](broken://spaces/reCGkFdsmuPJzGP9ZgGA/pages/H5UVYnRegjhilOQl29i3). This is true at any point that Spara is loaded; the query parameters can be added even after Spara is instantiated.

## Why use query parameters?

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

* **Identify the lead before the conversation starts.** When a lead arrives with parameters like `email` or `first_name`, Spara recognizes them immediately rather than asking for the same information again.
* **Personalize the chat experience.** Lead context is available to your chat agent from the very first message, so the conversation can be tailored to who the lead is, what page they came from, or what campaign brought them there.
* **Sync marketing data into your CRM.** UTM parameters (`utm_source`, `utm_campaign`, etc.) and any custom lead fields you pass via query parameters flow into Spara fields, which can be mapped to CRM properties via [https://docs.spara.com/integrations/crm-integrations/hubspot-crm](https://docs.spara.com/integrations/crm-integrations/hubspot-crm "mention") or [https://docs.spara.com/integrations/crm-integrations/salesforce](https://docs.spara.com/integrations/crm-integrations/salesforce "mention").
* **Power attribution, routing, and downstream workflows.** Once a lead's source and identity are known, Spara can route them to the right calendar, trigger the right workflow, and attribute the conversion back to the campaign that drove the visit.

## Step 1: Add query parameters to URLs

Add query parameters to the URL of any webpage that loads Spara [Chat Agents](broken://spaces/reCGkFdsmuPJzGP9ZgGA/pages/H5UVYnRegjhilOQl29i3).

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

* Leads submit a webform at acme.com/form. This form includes fields for first name and email address.
* Upon form submission, the lead is redirected to acme.com/chat, which loads the Spara Fullscreen interface.

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

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

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

## Step 2: Map query parameters

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

* `utm_campaign`
* `utm_source`
* `utm_medium`
* `utm_campaign`
* `utm_term`
* `utm_content`
* `email`
* `first_name`
* `last_name`
* `company_name`

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

* Navigate to [Chat > Configuration](https://app.spara.co/settings/chat/configuration)
* Click "Add Field +" to add a new mapping
* In "Your field," type in the exact query parameter key
* In "Spara field," select or add the field

<figure><img src="/files/HiTUqgcIrMstnqkRxuYL" alt=""><figcaption></figcaption></figure>

## How do Spara fields work?

Some notes on how Spara fields work:

* Fields are persisted across all user sessions.
* Each field may only have a single value.
* Any field may be overwritten at any time. Fields are never deleted or overwritten by `null` or `none`.

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

* Anonymous Lead 123 visits `acme.com?utm_campaign=twitter` and talks to Spara. Throughout the conversation, Lead 123 navigates to multiple `acme.com` webpages.
* 24 hours later….Anonymous Lead 123 visits `acme.com/pricing?utm_source=google`. They do not talk to Spara.
* 6 days later…Anonymous Lead 123 visits `acme.com?utm_campaign=linkedin`. They talk to Spara.

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

* `utm_campaign=linkedin`
* `utm_source=google`

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


# Security & Compliance

Spara's security posture, compliance frameworks, and data handling practices.

Spara is built to be enterprise-grade, so security and compliance are paramount to us.<br>

#### What compliance frameworks does Spara conform to and audit?

Spara is SOC 2 Type II and GDPR compliant. Please visit our [Trust Center](https://app.vanta.com/spara/trust/4kaeqmrw0tvtd35pbucd5) for:

* Latest reports
* Company policies
* Subprocessor information and notification subscription

#### What is Spara's privacy policy?

Spara's privacy policy is available on our website at [spara.com/privacy](https://www.spara.com/privacy)*.*

#### Where is Spara hosted? <a href="#where-is-gitbook-hosted" id="where-is-gitbook-hosted"></a>

We are hosted on [**Google Cloud**](https://cloud.google.com/security/overview/), which is backed by the same infrastructure and security that Google uses for its own services.

Customer data is stored in U.S. data centers. Some data (HTML pages & assets) may be cached in other geographies by our CDN. Access to private content through our CDN is always validated through our application servers using a complex permissions system.

Google follows or even leads most of the industry's best-practices and is compliant with most major security [standards and certifications](https://cloud.google.com/security/compliance/).

#### Is customer data encrypted? <a href="#is-customer-data-encrypted" id="is-customer-data-encrypted"></a>

Yes, all customer data is encrypted at rest and in-transit via Cloudflare. At rest on Google Cloud Platform, using [multiple layers of AES256-AES128](https://cloud.google.com/security/encryption-at-rest/default-encryption/resources/encryption-whitepaper.pdf).

#### How does Spara handle PII?

PII is only stored on our production database with strict RBAC. All data is anonymized before porting to lower environments.

{% hint style="info" %}
Contact your customer support representative for details on PII retention and deletion.
{% endhint %}

#### How are users authenticated? <a href="#how-are-users-authenticated" id="how-are-users-authenticated"></a>

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

#### Are inactive users automatically logged out of Spara Platform?

Yes. By default, inactive users are logged out after 24 hours of inactivity. You can update this setting to any length of time in order to comply with your company's compliance mandate.

#### Does Spara support Okta single sign-on?

Yes. Spara supports Okta for enterprise SSO via SAML, OAuth 2.0, and OpenID Connect, alongside Microsoft Active Directory and Google Workspace. Contact your customer success representative to enable SSO for your account. See [User Management](https://docs.spara.com/platform/settings/user-management) for details.

#### Does Spara have endpoint protection (EDR) in place?

Yes. Endpoint anti-malware and threat-detection software is deployed on all company-issued endpoints, with central management and continuous monitoring. Definition and engine updates install automatically, files are scanned on introduction and on access, modification, or download, and disabling protections is a policy violation. Email threat detection is also in place.

#### Does Spara perform SAST and DAST scanning of its systems?

Yes. Application code is scanned prior to deployment. Dependencies are continuously scanned in CI/CD via GitHub Dependabot. Vulnerability scans are performed at least quarterly against public-facing production systems, and penetration tests are performed at least annually. Findings are remediated on the following timeline:

* Critical and High — within 30 days
* Medium — within 60 days
* Low — within 90 days

#### Does Spara use a cloud security posture management (CSPM) tool?

Yes. Spara's Google Cloud environment is continuously evaluated against the SOC 2 Type II cloud-hardening control set — IAM least-privilege, MFA-enforced production access, encryption at rest and in transit, VPC and subnet isolation, firewall and DDoS controls, tamper-resistant logging, and real-time alerting — supplemented by Google Cloud-native security tooling. Spara's SOC 2 report and underlying control tests are available at the [Trust Center](https://trust.spara.com).

#### Will customer data be used to train AI models — by Spara or its subprocessors?

No. Spara does not train AI models on customer data. Spara's contracts with all LLM subprocessors (including OpenAI and Anthropic) include no-training clauses that prohibit the use of customer inputs or outputs for model training. The same commitment is reflected in Spara's customer DPA. The current subprocessor list is available at [trust.spara.com/subprocessors](https://trust.spara.com/subprocessors).

#### Does Spara have zero-data-retention agreements with LLM subprocessors?

Yes. Spara has zero data retention (ZDR) agreements in place with all LLM subprocessors. ZDR settings may be turned on by request for enterprise-level customers.

Even when ZDR is not turned on, default subprocessor retention applies — for example, OpenAI's standard 30-day retention for abuse-monitoring purposes, after which data is deleted. All LLM subprocessors are contractually bound by the no-training clauses described above, so customer data is not used to train models during that retention window. The current key subprocessor list is available at [trust.spara.com/subprocessors](https://trust.spara.com/subprocessors).


# iFrame & Cookies

How the Spara chat widget loads on your site, what data it stores, and how it interacts with cookie consent policies.

This page explains how the Spara chat widget works from a technical perspective, what data it stores in the browser, and how it relates to your website's cookie consent policies.

## How the Spara widget loads

When you add the Spara JavaScript snippet to your website, it creates an **iframe** (inline frame) that loads the [chat agent](broken://spaces/reCGkFdsmuPJzGP9ZgGA/pages/H5UVYnRegjhilOQl29i3) interface. An iframe is a standard web technology that embeds one webpage inside another — similar to how a YouTube video embed works.

The iframe approach means:

* **Spara's code runs in isolation** from your website's code. It cannot access your page's JavaScript variables, DOM, or other data unless explicitly passed through the embed snippet.
* **Your website's code runs in isolation** from Spara. Your scripts cannot access the contents of the Spara iframe.
* **Styling is independent.** Spara's styles do not conflict with your website's CSS, and vice versa.

## What Spara stores in the browser

Spara uses **localStorage** (not cookies) to persist a small amount of data in the visitor's browser. localStorage is a browser storage mechanism that keeps data on the user's device, similar to cookies but with key differences:

* localStorage data is **not sent to servers** with every HTTP request (unlike cookies)
* localStorage is **scoped to your website's domain** — it cannot be read by other websites
* localStorage persists until explicitly cleared by the user or your code

### Data stored

| Key                     | Purpose                                                                                                                                                                                                                                 |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Prelead UUID**        | A randomly generated identifier that associates a visitor with their conversation across page loads and return visits. This is how Spara remembers that a visitor on your pricing page is the same person who chatted on your homepage. |
| **Page visit tracking** | A per-day, per-URL hash that prevents duplicate page visit recording. This ensures each unique page view is counted once per day.                                                                                                       |

Spara does **not** store:

* Names, email addresses, or other personally identifiable information in localStorage
* Third-party tracking data
* Cross-site identifiers

### Cookies

Spara does **not** set any cookies on your website. The embed snippet reads (but does not write) certain existing cookies on your site for analytics integration purposes:

* **Google Analytics cookies** (`_ga`, `_ga_*`) — If present, Spara reads the GA4 client ID and session ID so that Spara lead activity can be correlated with your Google Analytics data
* **Google Click ID cookies** (`_gcl_aw`, `_gcl_au`) — If present, Spara captures these for ad attribution

These cookies are set by Google Analytics, not by Spara. Spara will ingest the GA4 client ID and session ID automatically and can read the `gcl_au` and `gcl_aw` cookies if they are mapped as query parameters. See [Query Parameters](/developers/spara-api/query-parameters) for more information.

## Cookie consent and Spara

A common question is whether Spara needs to be behind your cookie consent banner. The answer depends on your organization's specific compliance requirements, but here are the technical facts:

* **Spara does not set cookies** — it uses localStorage only
* **Spara does generate a pseudonymous identifier** (the prelead UUID) stored in localStorage, which some privacy regulations may classify similarly to cookies
* **Spara does read existing Google Analytics cookies** if present, for attribution purposes

### Common approaches

* **Show Spara before consent** — Since Spara does not set cookies, some organizations display the chat widget immediately, even before cookie consent is granted. The prelead UUID is pseudonymous and not linked to personal data unless the visitor voluntarily provides it during conversation.
* **Show Spara after consent** — Organizations with stricter consent requirements load the Spara embed snippet only after the visitor accepts cookies. This can be done by conditionally inserting the script tag based on your consent management platform's API.

{% hint style="warning" %}
Spara does not provide legal advice. Consult your legal or compliance team to determine the correct approach for your organization's privacy policy and applicable regulations (GDPR, CCPA, etc.).
{% endhint %}

## Z-index and stacking

The Spara chat widget uses a high `z-index` to ensure it appears above most page content. If your cookie consent banner also uses a high `z-index`, both elements can coexist — the banner will typically appear above or alongside the chat widget depending on your CSS. If you need to adjust layering, contact your Spara account manager.


# Optimizing Your Webpages for Spara Scraping

How Spara scrapes your webpages into Knowledge, and what makes a page read well or badly.

Spara scrapes your public webpages and adds them to [https://docs.spara.com/platform/knowledge](https://docs.spara.com/platform/knowledge "mention"), the shared content library every Spara agent draws on — chat, email, and voice alike. Whatever survives the scrape is what your agents know about your product, pricing, and positioning; whatever doesn't, they can't use. This page is for the web or engineering team that owns the site: what Spara captures, what it misses, and the handful of markup choices that make the difference.

Knowledge is also where you manage which pages are indexed and review what Spara captured from each one.

## How Spara reads your pages

Spara scrapes your site ahead of time, on a recurring pass — it isn't fetching pages live during a conversation. Each page is loaded in a browser, its JavaScript runs, and the rendered result is converted to plain text and markdown. That text is what lands in Knowledge, and it's all your agents have to work from.

Because the page is genuinely rendered, client-side frameworks are not a problem: a React, Vue, or Svelte site reads the same as a server-rendered one.

What doesn't survive is anything that never becomes text on the rendered page. Spara reads the page as it loads and doesn't interact with it — no clicking, hovering, or scrolling — so content that a visitor has to act on to reveal stays hidden. And information carried only visually — pixels inside an image, a color, a CSS-drawn icon — leaves no text for the conversion to pick up.

One principle covers most of what follows: **if your page meets web accessibility standards, it will read well.** The semantics that let a screen reader convey a page are the same semantics this conversion extracts. If a screen reader can make sense of the page, so can Spara.

## What reads well

* **Content that is on the page once it has finished loading.** Whether the markup came from the server or was rendered in the browser makes no difference. Server-rendered and static pages remain the most predictable choice, because nothing depends on timing.
* **Semantic structure** — `<article>`, `<section>`, real headings (`<h1>`–`<h3>`), lists, and paragraphs. These carry through as headings and lists, which is what tells your agents which facts belong to which topic.
* **Clean, readable body text.** If a sentence could be read aloud and still make sense, it survives.
* **Informative content in the main article flow.** Sidebars, nav, footers, ads, social widgets, and modals are treated as boilerplate and dropped before conversion. If a fact matters, don't leave it in a widget.
* **Real `<table>` markup** for tabular data such as pricing and feature comparisons.
* **Paginated listings.** Spara reads one URL at a time, and paginated pages have real URLs it can follow.

## What reads badly

* **Content that only appears after a particular user interaction** — click-to-expand sections, tabbed panels, "load more" buttons. Spara doesn't click, so whatever the interaction would have revealed is not read.
* **Content that arrives after the page has settled.** Spara doesn't wait around for late additions once the page has loaded, so a slow request still streaming content in can miss the window.
* **Text baked into images.** In a screenshot or an exported graphic, the words are part of the image itself, not machine-readable text. A spec sheet saved as a PNG contributes nothing.
* **Canvas and WebGL interfaces.** Text drawn into a `<canvas>` element or a 3D scene is invisible to the conversion.
* **Infinite scroll** in place of pagination. Items that load only as a visitor scrolls are never fetched.

## Images and figures

`alt` text is what carries an image's meaning through the conversion, and it is sufficient on its own — it becomes the image's content in Knowledge. Give descriptive `alt` text to every image that is structural to the information on the page: a diagram, a screenshot of a report, a checkmark that means "supported."

For a dense chart or diagram, a `<figcaption>` is worth adding for a reason of its own: unlike `alt`, it is visible to every reader, and it has room for detail that doesn't sit comfortably in an `alt` string.

```html
<figure>
  <img src="/img/uptime-by-region.png"
       alt="Uptime by region in 2026: US 99.99%, EU 99.98%, APAC 99.95%">
  <figcaption>Uptime by region, 2026: US 99.99%, EU 99.98%, APAC 99.95%.</figcaption>
</figure>
```

The `alt` attribute carries the numbers into Knowledge; the caption puts them in front of human readers as well.

## Tables

Pricing and comparison tables are the most common place information gets lost, in two distinct ways.

**Use real table markup, not stacked `<div>`s.** A table assembled from `<div>`s converts to an undifferentiated run of text: the words come through, but which value belongs to which plan is lost.

```html
<table>
  <caption>Plan comparison</caption>
  <thead>
    <tr><th>Feature</th><th>Starter</th><th>Pro</th></tr>
  </thead>
  <tbody>
    <tr><td>SSO</td><td>Not included</td><td>Included</td></tr>
  </tbody>
</table>
```

**Don't put meaning in a decorative checkmark.** This is the single item most worth checking on your own pricing page. A checkmark marked up as an image with `alt` text reads correctly:

```html
<td><img src="/img/check.svg" alt="Supported"></td>
```

The same checkmark drawn with a CSS `background-image`, or marked up as `<div role="img" aria-label="Supported">`, produces an **empty table cell**. There is no text for the conversion to pick up, so Knowledge holds a blank where you meant "supported" — and a blank in a pricing table is easily read as "not included." Use an `<img>` with descriptive `alt` text, or simply put the word in the cell.

## Checking a page yourself

Three checks catch nearly everything, all of them free.

1. **Search the rendered DOM without touching the page.** Load the page, open DevTools (F12), and search the Elements panel for the text you expect Spara to capture. That rendered DOM is close to what Spara reads. The discipline is not to click, expand, or scroll first — if you have to interact with the page to make the text appear, Spara won't see it either.
2. **Run an accessibility audit.** Lighthouse is built into Chrome DevTools (Lighthouse panel, Accessibility category); [axe DevTools](https://www.deque.com/axe/devtools/) is a free browser extension that reports more detail. Anything flagged as missing alt text, a non-semantic table, or an unlabeled control is likely also missing from what Spara captures.
3. **Read the page with a screen reader.** VoiceOver is built into macOS (Cmd+F5) and [NVDA](https://www.nvaccess.org/download/) is free on Windows. This is the human-scale version of the same check, and it is the fastest way to notice a checkmark or a table cell that conveys nothing.

To see roughly what the text extraction yields, pipe the page through a local HTML-to-markdown converter such as [Pandoc](https://pandoc.org/) (`pandoc -f html -t markdown`). Save the rendered DOM from DevTools rather than the raw response, so the converter sees the same content Spara does.

## FAQ

### How soon will markup changes show up in Knowledge?

By default, Spara re-crawls each site once every 24 hours, so a markup change is normally reflected within a day. The refresh interval is configurable per domain, so yours may be set differently — ask your Spara representative if you need to know or change the interval for your site. If you need an immediate refresh after a site update, they can also re-index the affected pages on request.

### Can I check what Spara actually captured from a page?

Yes. The [https://docs.spara.com/platform/knowledge](https://docs.spara.com/platform/knowledge "mention") page lists every indexed page and lets you review the content Spara extracted from each one, which is the fastest way to confirm a fix worked.