Phone Numbers

Phone numbers enable voice agents to receive and make calls. Each phone number can be linked to one agent and supports both inbound and outbound calling through Twilio integration.

Key Features

Inbound Calling

• Receive calls on your agent’s phone number
• Automatic agent dispatch when calls arrive
• Configurable SIP trunk settings
• Connection policy management

Outbound Calling

• Make calls programmatically from your agent
• Twilio trunk integration
• Credential management for authentication
• Custom SIP headers support

Automatic Twilio Setup

When you create a phone number with Twilio credentials, the system automatically:

1. Creates SIP trunk in Twilio
2. Configures origination URLs for inbound (if supports_inbound: true)
3. Creates credential lists for outbound (if supports_outbound: true)
4. Sets up connection policies for inbound routing
5. Configures LiveKit integration for real-time communication

Rollback Protection

If any setup step fails, all external resources are automatically cleaned up to prevent orphaned configurations in Twilio.

Phone Number States

Linking to Agents

• Each phone number can be linked to one agent at a time
• Link during agent creation via phone_number_id parameter
• Link during phone number creation if agent exists
• Update agent to change linked phone number
• Unlinking happens automatically when phone number is deleted

Provider Support

Currently supported providers:

Available Operations

• List Phone Numbers - Retrieve all phone numbers
• Get Phone Number - Get a specific phone number
• Create Phone Number - Add a new phone number
• Delete Phone Number - Remove a phone number
• Force Delete Phone Number - Force delete corrupted phone numbers

Common Workflows

Setting Up Inbound Calling

1. Create a phone number with supports_inbound: true
2. Provide Twilio credentials
3. Link to an agent (during creation or via agent update)
4. System automatically configures Twilio trunk and LiveKit integration
5. Agent receives calls automatically

Setting Up Outbound Calling

1. Create a phone number with supports_outbound: true
2. Provide Twilio credentials
3. Link to an agent
4. System automatically configures outbound trunk with credentials
5. Agent can make outbound calls programmatically

Handling Cleanup Failures

If phone number deletion fails:

1. Phone number is marked as corrupted
2. Review error message for cleanup instructions
3. Manually clean up external resources (Twilio)
4. Use Force Delete to remove database record

E.164 Format

All phone numbers should use E.164 format:

+[country code][subscriber number]

Examples:

• US: +14155551234
• UK: +442071838750
• Australia: +61212345678

See Also

• Agents Overview - Learn about voice agents
• Create Agent - Link phone numbers during agent creation
• Update Agent - Change linked phone numbers