> ## Documentation Index
> Fetch the complete documentation index at: https://hellotars.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Distribute a voice agent

> Connect a voice agent to phone numbers, add a call button or call screen to your website, share its link, and place calls.

> [!NOTE]
>
> This capability is in **beta**. Behavior can change before general availability.

At the end of this page, callers reach your voice agent by phone, from your website, or from its link. Every channel runs the latest published version, so publish the voice agent first.

## Before you start

Before you start, sign in to [the dashboard](https://dashboard.hellotars.com) and select the organization you want to work in.

* A published voice agent. See [Test and publish a voice agent](https://hellotars.com/docs/guides/voice/launch/test-and-publish-a-voice-agent.md).
* For phone calls, a phone number in your organization. See [Manage phone numbers](https://hellotars.com/docs/guides/voice/launch/phone-numbers.md).

## Connect a phone number

**1. Open the voice agent and select Distribute**

The **Phone**, **Web** and **Developers** sections open.

**2. Under Phone numbers, select Connect a number**

The list shows the numbers your organization owns.

**3. Choose the number and what to Use for it**

**Incoming and outgoing calls**, **Incoming calls only** or **Outgoing calls only**.

**4. Confirm the connection**

A **Number connected to this agent** message confirms it.

To stop using a number for this voice agent, select **Disconnect from this agent**. To buy or import more numbers, go to **Settings** → **Phone numbers**.

## Place a call

> [!WARNING]
>
> **Place a call** rings a real phone number and uses your organization's voice minutes. Call your own number first, or try the voice agent in the [test panel](https://hellotars.com/docs/guides/voice/launch/test-and-publish-a-voice-agent.md#test-the-voice-agent).

Select **Place a call** next to a connected number.

| Field | What it holds |
| - | - |
| **Destination** | The number to call. |
| **Published agent** | The voice agent that places the call. |
| **Recipient's timezone (optional)** | The recipient's timezone. Leave it empty to use the end user's saved timezone, or the destination country's timezone when it has only one. |
| **Variables** | Values the call starts with. Use the variable names your voice agent declares. |
| **Schedule (optional)** | A later time for the call. |

Calls are placed only inside your calling hours for the recipient. Numbers on the **Do-not-call list** are never called. A scheduled call shows **Cancel scheduled call** until it starts.

## Add the voice agent to your website

**1. Under Web, find Add to your website**

If web calls are off, select **Turn on**. The button does not appear on your site until web calls are on.

**2. Choose Call button or Call screen in your page**

A call button floats on the page and opens the call. A call screen sits inside your page.

**3. Copy the snippet and paste it into your website**

For **Call screen in your page**, set the height to fit your page. 600 px works for most layouts.

[https://dashboard.hellotars.com](https://dashboard.hellotars.com)

![The Website page under Distribute with the Add to your website card highlighted, showing Call button and Call screen in your page, Where are you adding it?, and the embed snippet](https://hellotars.com/docs/docs/guides/voice/images/distribute-website.png)

Your website must use HTTPS and allow microphone access. Localhost also works for testing. Changes on the **Design** page appear on your site automatically.

## Share the voice agent link

**Agent link** opens a full-page call screen. Share it in emails, ads or support pages. **QR code** lets people scan to call. Select **Download SVG** or **Download PNG** for print or signage.

## Control web access

**Web access** controls where calls can start and how callers are checked.

| Setting | What it does |
| - | - |
| **Allowed websites** | One website per line. Leave it empty to allow calls from any website. |
| **Page variables** | The variables a page may pass when it starts a call. Any other variable is refused. |
| **reCAPTCHA** | Checks each caller with Google reCAPTCHA v3 before the call starts. Enter the **Site key**, the **Secret key** and a **Minimum score**. |

Select **Save access** to apply the changes.

> [!WARNING]
>
> **Reset sessions** stops every web call session issued so far, for the widget and for the voice agent link. Use it after a session token leaks. End users get a new session the next time they start a call.

## Change how the call screen looks

Open the **Design** page of the voice agent. It has **Brand identity**, **Theme** and **Call screen** settings, and a preview of each call state.

| Call screen setting | What it does |
| - | - |
| **Show a notice** and **Ask for consent** | Show a notice, or ask for consent, before the call connects. |
| **Start button label** | The text on the button that starts the call. |
| **Live captions** | Shows what is said, as it is said. End users can hide them. |
| **Show what the agent is doing** | Shows a short note while the voice agent uses a tool. |
| **Tars branding** | Shows "powered by Tars" in the footer. It is off on paid plans. |

Select **Save Changes** to save the design.

## Start calls from your backend

The **API** section shows the voice agent's **Agent ID** and a **Place a phone call** example. Create an API key in **Settings** → **Integrations**. Calls run the latest published version. See the [Calls API](https://hellotars.com/docs/developer/api/calls.md).

Conversation started, ended and analyzed events go to your webhook destinations. See [Webhook events](https://hellotars.com/docs/developer/webhooks/events.md).

## Verify

Call the connected number, or open the voice agent link and start a call. The call shows in **Calls** with the voice agent's name and version.

## Related pages

* [Manage phone numbers](https://hellotars.com/docs/guides/voice/launch/phone-numbers.md)
* [Review calls](https://hellotars.com/docs/guides/voice/monitor/review-calls.md)
* [Calls API](https://hellotars.com/docs/developer/api/calls.md)
* [Set the voice call policy](https://hellotars.com/docs/guides/security/voice-privacy.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.