> ## 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. # Manage phone numbers > Buy a number from Tars, connect a Twilio number or a SIP route, assign voice agents, and set business hours and the do-not-call list. > [!NOTE] > > This capability is in **beta**. Behavior can change before general availability. At the end of this page, your organization has a phone number that a voice agent answers and calls from. Phone numbers live in **Settings** → **Phone numbers**, and every voice agent in the organization can use them. ## Before you start Before you start, sign in to [the dashboard](https://dashboard.hellotars.com) and select the organization you want to work in. * Voice is on for your organization. See [Who can use voice agents](https://hellotars.com/docs/guides/voice/voice-overview.md#who-can-use-voice-agents). * Your role lets you manage resources. Other members can view numbers and their settings but cannot change them. * A published voice agent to assign. See [Test and publish a voice agent](https://hellotars.com/docs/guides/voice/launch/test-and-publish-a-voice-agent.md). ## Add a phone number Select **Add phone number** and choose how to connect the number: | Option | What it does | | - | - | | **Buy a number** | Gets a local or toll-free number managed by Tars. | | **Use a Twilio number** | Uses a number from a Twilio account you own. | | **Connect via SIP** | Connects a number from your carrier or call center platform. | When your plan reaches its phone number limit, the **Phone number limit reached** dialog opens instead. See [Voice billing](https://hellotars.com/docs/guides/billing/voice-billing.md). ### Buy a number > [!WARNING] > > A payment method is required. The number's monthly fee starts when the number is activated and is prorated from that date. **1. Select Buy a number** The **Buy phone number** dialog opens. **2. Choose the Country and the Number type** **Local** or **Toll-free**. **3. Search by Area code or digits and choose a number** If no number matches, try another area code. **4. Optional: enter a Nickname and choose an Inbound agent and an Outbound agent** Assignments use each voice agent's latest published version. You can also assign voice agents later. **5. Select Review purchase, then Purchase number** The number shows **Setting up your number** until it is ready. Calls use your voice minute balance. Number rental does not include minutes or extra concurrent calls. With no inbound agent, incoming callers hear that the number is not configured. ### Use a Twilio number **1. Select Use a Twilio number** If no Twilio account is connected yet, the dialog asks for one. **2. Enter the Account SID and Auth Token of your Twilio account** Your numbers stay in your Twilio account. **3. Choose the number and turn on Calls with voice agents** Tars replaces where the number's calls go. If you disconnect the number, Tars restores the previous settings. **4. Optional: choose an Inbound agent, an Outbound agent and a Nickname, then select Set up number** A **Phone number connected** message confirms it. Twilio trial accounts can only call verified numbers. Tars manages a SIP trunk in your Twilio account. When you disconnect the Twilio account, Tars deletes the SIP trunk it created there. ### Connect via SIP Your number stays with your provider. You need access to the provider's SIP trunk configuration. **1. Select Connect via SIP and choose the platform that manages the number** The platforms are Telnyx (own account), Vonage, Genesys Cloud, Avaya, Five9, Amazon Connect, and **Other SIP provider**. **2. Under Route incoming calls to Tars, add the addresses to your provider's allowlist** The step lists the regional **Signalling addresses** and **Media addresses**. Supported codecs are PCMU, PCMA and G.722, with SRTP and TLS for media. **3. Enter the connection details** Enter your provider's termination URI, and either **Allowed source addresses** or a **SIP username** and **SIP password**. **4. Select Verify connection** If the check fails, fix the host, source addresses and credentials, then select **Retry verification**. **Allow a verification test call** is optional. The test is canceled before it rings, and your carrier bills the telephony usage. If verification keeps failing, **Save anyway** saves the number as unverified. Failed blocking health checks stop calls until you repair the connection. ## Assign voice agents to a number Select a number to open it, then open the **Voice agents** tab. * **Inbound calls** sets the voice agent that answers incoming calls. * **Outbound calls** sets the default voice agent for calls placed from this number. **A/B testing** splits calls between several published voice agents. Traffic percentages must be above zero and add up to 100%. New calls use each voice agent's latest published version. Changes do not move calls already in progress. ## Number settings | Tab | What it holds | | - | - | | **General** | **Nickname**, **Tags**, **Calling countries** for inbound and outbound calls, a **Fallback phone number** for when every concurrent-call slot is busy, and an optional **Inbound call check** webhook on a public https address. | | **Business hours** | A schedule in the number's own timezone. **Outside business hours** sends calls to a **Fallback phone number** or an **After-hours agent**. **Holidays** are whole days treated as outside business hours. | | **Connection** | The provider and the carrier connection. With a SIP trunk, you can edit the connection in place. Calls in progress continue on their current connection. | | **Health & history** | The connection health checks, and a history of number changes, checks and voice agent assignments. | Calls must be on in **Connection** before you can assign voice agents or set business hours. ## Block numbers from being called Select **Do-not-call list** on the **Phone numbers** page. Voice agents never call the numbers on this list. Enter a full number, or a prefix that ends in one `*`, such as `+1415*`. Add an optional note, then select **Add**. ## Release a number You release a number bought from Tars, and disconnect a Twilio number or a SIP route. Only an organization **Admin** can release or disconnect a number. Members who manage resources cannot. > [!WARNING] > > Releasing a number removes its voice agent assignments and cannot be undone. The number stops routing calls. Existing call history is kept. **1. On the Phone numbers page, open the number and go to its General tab** The release option shows only to an **Admin**. **2. Select Release number, or Disconnect number for a Twilio number or a SIP route** The dialog lists the voice agents assigned to the number. If the number has calls in progress, the dialog says so and you cannot continue. Wait for the calls to finish, then try again. **3. Type the phone number exactly as shown, then select Release number or Disconnect number** The button stays unavailable until the number matches. What happens to the number depends on where it came from: * **Bought from Tars**: the monthly fee stops. The number returns to the carrier and someone else may buy it. * **Twilio number**: the number stays in your Twilio account, and Tars restores its previous call settings. The Twilio account stays connected. * **SIP route**: the number stays with your provider. Tars removes its connection and stored credentials. While a release finishes, the number's settings are read-only. ## Verify The number shows on the **Phone numbers** page with its source, health and uses. Call it, and the inbound voice agent answers. ## Related pages * [Distribute a voice agent](https://hellotars.com/docs/guides/voice/launch/distribute-a-voice-agent.md) * [Voice billing](https://hellotars.com/docs/guides/billing/voice-billing.md) * [Set the voice call policy](https://hellotars.com/docs/guides/security/voice-privacy.md) * [Phone numbers API](https://hellotars.com/docs/developer/api/phone-numbers.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.