Phone Numbers - Feather

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.

Phone Number Formats

E.164 Format

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 +)

Formatting Tips

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

Agents

Configure agents to handle phone calls

Workflows

Use phone numbers in automated workflows

Calls

Monitor and analyze call records

API Reference

Explore the phone numbers API

Getting Started

Core Concepts

​What Are Phone Numbers?

​Phone Number Types

​Inbound Numbers

​Outbound Numbers

​Twilio Integration

​Connecting Your Twilio Account

​Acquiring Phone Numbers

​Option 1: Search and Purchase

​Option 2: Import Existing Twilio Numbers

​Dispatch Rules

​Inbound Dispatch Rules

​Outbound Dispatch Rules

​Managing Phone Numbers

​List Organization Numbers

​Remove Dispatch Rules

​Delete Phone Number

​Common Patterns

​Dedicated Support Line

​Multi-Agent Outbound Pool

​Department-Specific Routing

​Geographic Distribution

​Phone Number Formats

​E.164 Format

​Formatting Tips

​Best Practices

​Number Selection

​Dispatch Rules

​Compliance

​Cost Management

​Number Reputation

​Maintaining Good Reputation

​Reputation Monitoring

​Troubleshooting

​Inbound Calls Not Routing

​Outbound Calls Failing

​Number Purchase Failures

​Common Use Cases

Customer Support

Sales Outreach

Appointment Lines

Emergency Hotlines

Multi-Location

Language-Specific

​Next Steps

Agents

Workflows

Calls

API Reference

What Are Phone Numbers?

Phone Number Types

Inbound Numbers

Outbound Numbers

Twilio Integration

Connecting Your Twilio Account

Acquiring Phone Numbers

Option 1: Search and Purchase

Option 2: Import Existing Twilio Numbers

Dispatch Rules

Inbound Dispatch Rules

Outbound Dispatch Rules

Managing Phone Numbers

List Organization Numbers

Remove Dispatch Rules

Delete Phone Number

Common Patterns

Dedicated Support Line

Multi-Agent Outbound Pool

Department-Specific Routing

Geographic Distribution

Phone Number Formats

E.164 Format

Formatting Tips

Best Practices

Number Selection

Dispatch Rules

Compliance

Cost Management

Number Reputation

Maintaining Good Reputation

Reputation Monitoring

Troubleshooting

Inbound Calls Not Routing

Outbound Calls Failing

Number Purchase Failures

Common Use Cases

Next Steps