Managing Phone Numbers

The Phone Numbers page gives you a complete view of all numbers in your account. From here you can organize numbers with nicknames, check assignments, and release numbers you no longer need.

Phone Number List View

Navigate to Phone Numbers in the sidebar to see all your numbers. The list displays:

Phone number — The full number in E.164 format
Nickname — An optional friendly name you assign for quick identification
Provider — Which voice provider (Retell, Vapi, or Bland) the number belongs to
Assigned agent — The agent currently linked to this number, or “Unassigned”
Status — Active or inactive

Phone numbers list with columns for number, nickname, provider, and assigned agent

The phone numbers list gives you a clear view of your entire inventory.

Nicknames

Phone numbers are hard to remember. Nicknames let you label numbers with descriptive names so you and your team can quickly identify them.

Setting a Nickname

Find the number in the phone numbers list
Click the nickname field or edit icon
Enter a descriptive name (e.g., “Acme Corp Main Line”, “Sales Inbound”, “Support - West Coast”)
Save the change

Nicknames appear throughout the dashboard wherever the phone number is referenced, making it much easier to manage a large inventory.

💡

Use a consistent naming convention for nicknames. A good pattern is: [Client Name] - [Purpose] (e.g., “Pinnacle Dental - Appointment Booking”).

Inbound vs Outbound Configuration

Phone numbers in BuildVoiceAI serve both inbound and outbound purposes:

Inbound

When a number is assigned to an agent, any incoming call to that number is automatically routed to the agent. The agent picks up, greets the caller, and handles the conversation based on its configured prompt and behavior.

Outbound

When an agent makes an outbound call (via scheduled calls, workflow triggers, or API), the assigned phone number is used as the caller ID. The recipient sees this number on their phone.

If an agent does not have a phone number assigned, it cannot make or receive phone calls. It can still be used for browser-based test calls.

Releasing a Number

If you no longer need a phone number, you can release it to stop incurring monthly rental fees from your provider:

Navigate to Phone Numbers
Find the number you want to release
Unassign it from any agent if currently assigned
Click the Delete or Release button
Confirm the release

Delete confirmation dialog for releasing a phone number

Confirm before releasing a number — this action cannot be undone.

⚠️

Releasing a phone number is permanent. The number is returned to the provider’s pool and may be reassigned to someone else. You cannot recover a released number. If the number is printed on marketing materials or shared with customers, make sure to update those references first.

Bulk Number Management

If you manage a large number of phone numbers:

Use nicknames consistently to keep your list organized
Sort by assignment status to quickly find unassigned numbers
Filter by provider to see numbers grouped by Retell, Vapi, or Bland
Review monthly to identify unused numbers that can be released

Monitoring Number Health

Keep an eye on your numbers to ensure they are working correctly:

Check call volume — Numbers with zero calls over an extended period may be unused
Verify assignments — Make sure every production number is assigned to an active agent
Test periodically — Call your numbers to confirm they connect to the right agent
Watch for provider issues — If calls are failing on a specific number, check the provider dashboard for account or number-level issues

Best Practices

Document number purposes using nicknames so anyone on your team can understand the setup
Keep a buffer of one or two unassigned numbers ready for quick deployment when onboarding new clients
Separate test and production numbers so test calls do not interfere with live operations
Review your inventory quarterly and release numbers that are no longer serving a purpose