# Setting Up Voice Agents

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://github.com/spara-ai/spara-app/blob/gitbook/agents/voice-agents/README.md) 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](https://github.com/spara-ai/spara-app/blob/gitbook/guides/platform-guides/writing-effective-agent-prompts/README.md) 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://github.com/spara-ai/spara-app/blob/gitbook/integrations/calendar-integrations/cal.com) and additional options listed in [Calendar Integrations](https://github.com/spara-ai/spara-app/blob/gitbook/integrations/calendar-integrations/README.md).
* **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://github.com/spara-ai/spara-app/blob/gitbook/agents/voice-agents/README.md#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://github.com/spara-ai/spara-app/blob/gitbook/agents/voice-agents/README.md#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://github.com/spara-ai/spara-app/blob/gitbook/agents/workflows/call-phone/README.md) 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.
* **Add Key Questions.** The [Knowledge](https://github.com/spara-ai/spara-app/blob/gitbook/platform/knowledge/README.md) page lets you define ideal responses for important questions. This is the fastest way to improve accuracy on specific topics.
* **Use Ask Spara AI to debug.** The Ask Spara AI tab in the agent editor 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://github.com/spara-ai/spara-app/blob/gitbook/agents/workflows/call-phone/README.md) 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://github.com/spara-ai/spara-app/blob/gitbook/agents/workflows/send-text/README.md) 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.


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.spara.com/guides/platform-guides/setting-up-voice-agents.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

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