What Are Phone Numbers?
Phone Numbers in Feather are the telephone numbers your agents use to make and receive calls. They connect your voice AI agents to the traditional phone network through Twilio integration, enabling:
Inbound calling - Customers call your numbers to reach agents
Outbound calling - Agents call customers from your numbers
Caller ID - Display your business numbers to customers
SMS/MMS - Send and receive text messages (in workflows)
Number portability - Import existing Twilio numbers
Phone Number Types
Inbound Numbers
Inbound numbers handle calls to your agents:
Customer → Calls +1-555-123-4567 → Agent handles call
Use cases:
Customer support hotlines
Sales inquiry lines
Appointment booking lines
General information numbers
Outbound Numbers
Outbound numbers are used when agents call from your system:
Agent → Calls customer → Shows +1-555-987-6543
Use cases:
Sales outreach campaigns
Appointment reminders
Follow-up calls
Customer notifications
Twilio Integration
Feather uses Twilio as the telephony provider. You’ll need:
Twilio Account - Active Twilio account
Account SID - Your Twilio Account SID
Auth Token - Your Twilio Auth Token
Phone Numbers - Twilio phone numbers (purchased or existing)
Connecting Your Twilio Account
const twilioConnection = {
accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ,
authToken: "your_twilio_auth_token" ,
phoneNumber: "+15551234567"
};
const response = await fetch ( 'https://prod.featherhq.com/api/v1/twilio/import' , {
method: 'POST' ,
headers: {
'X-API-Key' : API_KEY ,
'Content-Type' : 'application/json'
},
body: JSON . stringify ( twilioConnection )
});
Acquiring Phone Numbers
Option 1: Search and Purchase
Search for available numbers in specific area codes:
// Search for available numbers
const searchParams = {
areaCode: "415" , // San Francisco
country: "US"
};
const searchResponse = await fetch (
`https://prod.featherhq.com/api/v1/phone-number/search?areaCode= ${ searchParams . areaCode } &country= ${ searchParams . country } ` ,
{
headers: {
'X-API-Key' : API_KEY
}
}
);
const availableNumbers = await searchResponse . json ();
// Purchase a number
const purchaseRequest = {
phoneNumber: availableNumbers [ 0 ]. phoneNumber
};
const purchaseResponse = await fetch ( 'https://prod.featherhq.com/api/v1/phone-number/purchase' , {
method: 'POST' ,
headers: {
'X-API-Key' : API_KEY ,
'Content-Type' : 'application/json'
},
body: JSON . stringify ( purchaseRequest )
});
Option 2: Import Existing Twilio Numbers
If you already have Twilio numbers, import them:
const importRequest = {
accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ,
authToken: "your_twilio_auth_token" ,
phoneNumber: "+15551234567"
};
const response = await fetch ( 'https://prod.featherhq.com/api/v1/twilio/import' , {
method: 'POST' ,
headers: {
'X-API-Key' : API_KEY ,
'Content-Type' : 'application/json'
},
body: JSON . stringify ( importRequest )
});
Dispatch Rules
Dispatch Rules determine which agent handles calls on a phone number. They connect phone numbers to agents.
Inbound Dispatch Rules
Configure which agent answers calls to an inbound number:
const inboundRule = {
agentId: "agent-123"
};
const response = await fetch (
`https://prod.featherhq.com/api/v1/phone-number/inbound/ ${ phoneNumberId } /dispatch-rule` ,
{
method: 'POST' ,
headers: {
'X-API-Key' : API_KEY ,
'Content-Type' : 'application/json'
},
body: JSON . stringify ( inboundRule )
}
);
Flow:
Customer calls → +1-555-123-4567 → Inbound dispatch rule → Agent-123 answers
Outbound Dispatch Rules
Configure which agents can use a number for outbound calls:
const outboundRule = {
agentIds: [ "agent-456" , "agent-789" , "agent-101" ]
};
const response = await fetch (
`https://prod.featherhq.com/api/v1/phone-number/outbound/ ${ phoneNumberId } /dispatch-rule` ,
{
method: 'PUT' ,
headers: {
'X-API-Key' : API_KEY ,
'Content-Type' : 'application/json'
},
body: JSON . stringify ( outboundRule )
}
);
Flow:
Agent-456 makes call → Uses +1-555-987-6543 → Customer sees this number
Managing Phone Numbers
List Organization Numbers
View all phone numbers in your organization:
const response = await fetch ( 'https://prod.featherhq.com/api/v1/phone-number' , {
headers: {
'X-API-Key' : API_KEY
}
});
const phoneNumbers = await response . json ();
phoneNumbers . forEach ( number => {
console . log ( ` ${ number . phoneNumber } - ${ number . type } - Agent: ${ number . agentId } ` );
});
Remove Dispatch Rules
Remove inbound rule:
const response = await fetch (
`https://prod.featherhq.com/api/v1/phone-number/inbound/ ${ phoneNumberId } /dispatch-rule` ,
{
method: 'DELETE' ,
headers: {
'X-API-Key' : API_KEY
}
}
);
Remove outbound rule:
const response = await fetch (
`https://prod.featherhq.com/api/v1/phone-number/outbound/ ${ phoneNumberId } /dispatch-rule` ,
{
method: 'DELETE' ,
headers: {
'X-API-Key' : API_KEY
}
}
);
Delete Phone Number
Remove a phone number from your organization:
const response = await fetch ( `https://prod.featherhq.com/api/v1/phone-number/ ${ phoneNumberId } ` , {
method: 'DELETE' ,
headers: {
'X-API-Key' : API_KEY
}
});
Deleting a phone number releases it from your Twilio account. This action cannot be undone.
Common Patterns
Dedicated Support Line
Single number for customer support:
// 1. Import or purchase number
const number = "+1-555-SUPPORT" ;
// 2. Create support agent
const supportAgent = await createAgent ({
name: "Customer Support Agent" ,
// ... configuration
});
// 3. Set inbound dispatch rule
await setInboundRule ( phoneNumberId , supportAgent . id );
Result: Customers call your support line and always reach the support agent.
Multi-Agent Outbound Pool
Multiple agents sharing outbound numbers:
// Create multiple agents
const salesAgents = [
await createAgent ({ name: "Sales Agent 1" }),
await createAgent ({ name: "Sales Agent 2" }),
await createAgent ({ name: "Sales Agent 3" })
];
// Acquire multiple outbound numbers
const numbers = [
"+1-555-0001" ,
"+1-555-0002" ,
"+1-555-0003"
];
// Each number can be used by all agents
for ( const phoneNumberId of numberIds ) {
await setOutboundRule ( phoneNumberId , salesAgents . map ( a => a . id ));
}
Result: Any sales agent can use any of the outbound numbers.
Department-Specific Routing
Route different numbers to different departments:
const setup = [
{
number: "+1-555-SALES" ,
agent: salesAgentId ,
department: "Sales"
},
{
number: "+1-555-SUPPORT" ,
agent: supportAgentId ,
department: "Support"
},
{
number: "+1-555-BILLING" ,
agent: billingAgentId ,
department: "Billing"
}
];
for ( const config of setup ) {
await setInboundRule ( config . phoneNumberId , config . agent );
}
Result: Customers call department-specific numbers and reach the right agent.
Geographic Distribution
Use local numbers for different regions:
const regions = [
{ areaCode: "415" , city: "San Francisco" , agentId: "west-coast-agent" },
{ areaCode: "212" , city: "New York" , agentId: "east-coast-agent" },
{ areaCode: "312" , city: "Chicago" , agentId: "midwest-agent" }
];
for ( const region of regions ) {
// Search for local number
const numbers = await searchNumbers ( region . areaCode );
// Purchase first available
const purchased = await purchaseNumber ( numbers [ 0 ]);
// Set dispatch rule
await setInboundRule ( purchased . id , region . agentId );
}
Result: Customers see local area codes, increasing answer rates.
All phone numbers use E.164 international format:
+[country code][area code][local number]
Examples:
✅ +14155551234 (US)
✅ +442071234567 (UK)
✅ +81312345678 (Japan)
❌ (415) 555-1234 (Invalid)
❌ 555-1234 (Invalid)
❌ 14155551234 (Missing +)
Always include:
Plus (+) prefix
Country code (1 for US/Canada)
No spaces, dashes, or parentheses
Best Practices
Number Selection
Local area codes - Choose area codes matching your target audience
Memorable numbers - Select numbers that are easy to remember
Consistent branding - Use numbers that align with your brand
Toll-free options - Consider 800/888/877 numbers for inbound support
Number pooling - Have multiple numbers for high-volume outbound
Dispatch Rules
Test before production - Verify dispatch rules work correctly
Document assignments - Keep track of which agents use which numbers
Monitor performance - Track answer rates and call quality by number
Update regularly - Review and update dispatch rules as agents change
Backup agents - Consider fallback agents for redundancy
Compliance
Caller ID accuracy - Ensure displayed numbers are accurate
DNC lists - Respect Do Not Call lists
TCPA compliance - Follow calling time restrictions
Number reputation - Monitor and maintain number reputation
Registration - Register numbers for A2P (Application-to-Person) messaging
Cost Management
Number consolidation - Use fewer numbers when possible
Release unused numbers - Delete numbers no longer needed
Monitor usage - Track per-number call volumes
Optimize routing - Reduce transfer costs with proper dispatch rules
Geographic optimization - Use local numbers to reduce long-distance charges
Number Reputation
Maintaining Good Reputation
Phone number reputation affects answer rates:
Do:
Make calls only to consenting recipients
Honor opt-out requests immediately
Call during appropriate hours
Maintain consistent calling patterns
Register numbers properly
Don’t:
Make excessive calls to the same number
Use numbers for spam
Rotate numbers frequently
Ignore complaints
Call DNC-listed numbers
Reputation Monitoring
Monitor these metrics:
Answer rate - Percentage of calls answered
Block rate - How often the number is blocked
Complaint rate - Number of spam reports
Voicemail rate - Percentage going to voicemail
Low answer rates may indicate reputation issues.
Troubleshooting
Inbound Calls Not Routing
Check:
Dispatch rule is set correctly
Agent is deployed and active
Twilio number is configured properly
Webhook URLs are set in Twilio
Verify:
const number = await getPhoneNumber ( phoneNumberId );
console . log ( 'Dispatch Rule:' , number . dispatchRule );
console . log ( 'Agent ID:' , number . agentId );
console . log ( 'Agent Status:' , agent . deploymentStatus );
Outbound Calls Failing
Common causes:
Agent not in outbound dispatch rule
Number not configured for outbound
Insufficient Twilio balance
Invalid destination number
Verify:
const number = await getPhoneNumber ( phoneNumberId );
console . log ( 'Outbound Agents:' , number . outboundAgentIds );
console . log ( 'Agent Included:' , number . outboundAgentIds . includes ( agentId ));
Number Purchase Failures
Reasons:
Number already owned
Insufficient Twilio funds
Geographic restrictions
Number type not supported
Solution: Try different area code or check Twilio account status.
Common Use Cases
Customer Support Dedicated support numbers routing to specialized support agents
Sales Outreach Outbound number pools for sales campaigns with local presence
Appointment Lines Booking hotlines connecting to scheduling agents
Emergency Hotlines Critical support lines with 24/7 agent availability
Multi-Location Different numbers for each business location
Language-Specific Numbers routing to agents speaking different languages
Next Steps