Skip to main content
DocumentationAPI ReferenceVideo Tutorials

Phone Numbers

To have your voice agent answer real phone calls, you need to connect phone numbers. This section covers everything about acquiring, configuring, and managing phone numbers on the Hanc.AI platform.

Overview​

Getting Phone Numbers​

You can get phone numbers directly through the Hanc.AI platform:

  • Phone numbers available in 100+ countries
  • Reliable call routing
  • Local, mobile, and toll-free numbers
  • No external accounts needed

Phone Number Properties​

Each phone number has the following properties:

PropertyDescription
phone_numberThe number in E.164 format (e.g., +4312345678)
formatted_numberHuman-readable format (e.g., +43 1 234 5678)
nameCustom label for the number
countryCountry code (e.g., AT, DE, US)
area_codeArea code portion of the number
providerPhone number provider
inbound_agent_idAgent assigned to handle incoming calls
outbound_agent_idAgent assigned for outbound calls

Phone Number Statuses​

StatusDescription
ACTIVENumber is live and can receive/make calls
INACTIVENumber is paused, not handling calls
DELETEDNumber has been removed

Import Statuses​

When importing numbers:

StatusDescription
IMPORTEDNumber successfully imported and ready to use
PENDINGImport is in progress

Getting Started with Phone Numbers​

Option A: Buy Numbers Through Hanc.AI​

  1. Go to Phone Numbers in the sidebar
  2. Click "Buy Number"
  3. Select country and number type
  4. Complete purchase
  5. Number is automatically configured

Option B: Connect SIP Trunk​

If you have an existing SIP trunk provider:

  1. Go to Phone Numbers in the sidebar
  2. Click "Connect SIP"
  3. Enter your SIP trunk credentials:
    • SIP Server / Domain
    • Username
    • Password
    • Port (default: 5060)
  4. Click Connect
  5. Configure agent assignment
All Plans

SIP trunk connections are available on all plans, including Free.

Phone Number Types​

Local Numbers​

Phone numbers tied to a specific area:

ExampleCoverage
+43 1 xxx xxxxVienna, Austria
+49 30 xxx xxxxBerlin, Germany
+41 44 xxx xxxxZurich, Switzerland

Best for: Local businesses, regional presence

Mobile Numbers​

Numbers that appear as mobile phones:

Best for: Personal service feel, SMS capability

Toll-Free Numbers​

Numbers where caller doesn't pay:

ExampleCountry
0800 xxx xxxAustria/Germany
1-800-xxx-xxxxUSA

Best for: Customer service, national reach

Assigning Agents to Numbers​

Inbound Agent​

The agent that answers incoming calls:

  1. Go to Phone Numbers
  2. Click on a number
  3. Under Inbound Agent, select your agent
  4. Save

Outbound Agent​

The agent used for outbound calls from this number:

  1. Go to Phone Numbers
  2. Click on a number
  3. Under Outbound Agent, select your agent
  4. Save

Multiple Numbers, One Agent​

You can assign the same agent to multiple numbers:

Multiple Agents, Multiple Numbers​

Or different agents for different numbers:

Number Management​

View All Numbers​

Go to Phone Numbers to see:

  • All your numbers
  • Assigned agents
  • Status
  • Provider

Edit Number Settings​

  1. Click on the number
  2. Modify settings (name, assigned agents, status)
  3. Save changes

Remove Number​

  1. Click on the number
  2. Click Delete or Remove
  3. Confirm removal
warning

Removing a number may result in losing that number permanently. It might be assigned to someone else if released.

Call Routing Scenarios​

Simple: One Number, One Agent​

Most common setup:

With Fallback​

If agent can't handle:

Department Routing​

Different numbers for different purposes:

Best Practices​

Number Selection​

  • Choose local numbers for local businesses
  • Use toll-free for customer service lines
  • Consider mobile numbers for personal services
  • Have a backup number for emergencies

Configuration​

  • Test numbers before going live
  • Set fallback numbers for agent failures
  • Label numbers clearly in your account

Operations​

  • Monitor call volumes per number
  • Track success rates by number
  • Review periodically — remove unused numbers

Troubleshooting​

Calls not connecting​

Check:

  1. Number status is ACTIVE
  2. Phone number integration is connected
  3. Agent is assigned to number
  4. Agent is active (not paused)

Poor audio quality​

Possible causes:

  • Network issues
  • Provider region
  • Customer's phone quality

Solutions:

  • Check the platform status page
  • Test with different phones

Calls going to wrong agent​

Check:

  1. Number's inbound agent setting
  2. No conflicting webhooks
  3. Correct number displayed in dashboard

Costs​

Hanc.AI Usage​

Hanc.AI uses credit-based billing:

  • All plans include unlimited agents
  • Calls are billed per minute from your credit balance
  • Phone numbers cost per month (charged from credits)
  • Per-minute rates vary by plan (see Billing)