> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryhamsa.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Overview
> Comprehensive phone number management with multi-provider support and voice agent integration
## Overview
The Phone Numbers feature provides comprehensive management of telephony resources in the Hamsa platform. It enables you to add, configure, and manage phone numbers from multiple providers, assign them to Voice Agents, and make outbound calls.
**Phone Numbers enable you to:**
* Add phone numbers from multiple providers (Twilio, SIP Trunk)
* Assign phone numbers to Voice Agents for inbound calls
* Make outbound calls using your Voice Agents
* Configure SIP trunk connections for enterprise telephony
* Manage phone number lifecycle and assignments
## What are Phone Numbers?
Phone Numbers are telephony resources that connect your Voice Agents to the outside world. Each phone number acts as an endpoint that can receive inbound calls and place outbound calls using your configured Voice Agents.
### Key Capabilities
**Multi-Provider Support**
* Support for multiple telephony providers
* Twilio integration with account credentials
* SIP Trunk support for enterprise telephony
* Provider-specific configuration options
* Easy provider switching and management
**Voice Agent Integration**
* Assign phone numbers to Voice Agents
* One-to-one agent assignment
* Automatic call routing to assigned agents
* Reassignment with validation
* Unassign to make numbers available
**Outbound Calling**
* Make test calls from the dashboard
* Pass custom parameters to agents
* Configure webhooks for call events
* Real-time call initiation
* Support for dynamic variables
**Batch Calls**
* Use phone numbers as "From Number" for batch calls
* Execute bulk calls to multiple recipients
* Schedule batch calls for specific times
* Track individual call statuses per recipient
* Manage batch call execution (pause, resume, retry, cancel)
**SIP Trunk Configuration**
* Full SIP trunk support for enterprises
* Inbound and outbound SIP configuration
* Custom SIP headers support
* Multiple transport types (TCP, UDP)
* SIP connection testing before deployment
* Authentication support (username/password)
## Supported Providers
The platform supports multiple telephony providers, each with specific capabilities:
### Twilio
Industry-leading cloud communications platform.
**Features:**
* Global phone number availability
* Reliable call quality
* Enterprise-grade infrastructure
* Wide geographic coverage
**Requirements:**
* Twilio Account SID
* Twilio Auth Token
* Phone number from your Twilio account
**Best for:**
* Standard voice applications
* Global deployments
* Reliable cloud telephony
### SIP Trunk
Session Initiation Protocol trunking for enterprise telephony.
**Features:**
* Direct carrier connectivity
* Custom SIP configurations
* Inbound and outbound support
* Transport protocol flexibility (TCP, UDP)
* Custom header support
* Authentication options
**Requirements:**
* SIP trunk address (IP or domain)
* Phone number for identification
* Transport type selection
* Optional: SIP credentials (username/password)
* Optional: Custom headers for routing
**Best for:**
* Enterprise deployments
* Custom telephony infrastructure
* Direct carrier connections
* Advanced routing requirements
**Configuration Options:**
*Inbound:*
* Origination URI (SIP over TCP/UDP)
* Automatic Hamsa webhook configuration
*Outbound:*
* Destination address (IP or domain)
* Transport type (TCP, UDP)
* Optional authentication (username/password)
* Custom headers for routing
* Connection testing before deployment
## Phone Number Components
### Basic Information
Each phone number includes:
* **Phone Number**: The actual phone number in E.164 format
* **Label**: Descriptive name for easy identification
* **Provider Type**: The telephony provider (Twilio, SIP)
* **Provider Credentials**: Provider-specific configuration
### Voice Agent Assignment
**Assignment Options:**
* **Assigned**: Phone number is assigned to a specific Voice Agent
* **Unassigned**: Phone number is available but not assigned
* **None**: Default state for new phone numbers
**Assignment Rules:**
* One phone number can be assigned to one agent at a time
* Reassignment requires confirmation if number is in use
* Unassigning makes the number available for other agents
### Provider Configuration
**Twilio Configuration:**
* Account SID (required)
* Auth Token (required)
* Automatic webhook configuration
**SIP Trunk Configuration:**
*Inbound Settings:*
* Origination URI type (SIP-TCP, SIP-UDP)
* Webhook URL (automatically configured by Hamsa)
*Outbound Settings:*
* Destination address (IP address or domain)
* Transport type (TCP, UDP)
* SIP trunk authentication (optional)
* Username
* Password
* Custom headers (optional)
* Key-value pairs for routing
* Multiple headers supported
**SIP Connection Testing:**
* Test connectivity before saving
* Validates destination reachability
* Checks authentication if configured
* Provides detailed error messages
* Ensures proper configuration
### Webhook Configuration
Phone numbers automatically receive webhook URLs for call events:
* Inbound call initiation
* Call status updates
* Call completion events
* Error notifications
Webhooks are automatically configured by the platform based on your provider type.
## Phone Number Actions
Available actions for phone numbers:
| Action | Description | Availability |
| ----------------------- | -------------------------------------------- | --------------------------------------- |
| **Add Number** | Add a new phone number from a provider | Always |
| **Assign Agent** | Assign a Voice Agent to handle inbound calls | When unassigned |
| **Reassign Agent** | Change the assigned Voice Agent | When assigned |
| **Unassign Agent** | Remove agent assignment | When assigned |
| **Make Call** | Place an outbound test call | When assigned to an agent |
| **View SIP Config** | View SIP trunk configuration details | SIP numbers only |
| **Test SIP Connection** | Test SIP connectivity | SIP numbers only (during initial setup) |
| **Delete** | Remove phone number from the system | Always |
Reassignment and deletion actions require confirmation to prevent accidental changes.
## Prerequisites
Before adding phone numbers, ensure you have:
**Provider Account**
* Active account with your chosen provider (Twilio or SIP trunk)
* Valid credentials (API keys, tokens, or SIP address)
* Phone number purchased from your provider (or SIP trunk configured)
**Project Setup**
* Active project selected
* Appropriate permissions to manage phone numbers
**Voice Agent Not Required**: You can add phone numbers without having a Voice Agent. Voice Agents are only needed when you want to assign numbers for inbound calls or make outbound calls.
## Common Use Cases
### Inbound Customer Support
**Scenario**: Receive customer calls and route to support agent
**Setup**:
* Add phone number from Twilio
* Assign to your customer support Voice Agent
* Configure agent with knowledge base and tools
* Test with incoming calls
**Result**: Customers can call your number and speak with AI support agent
### Outbound Appointment Reminders
**Scenario**: Make outbound calls for appointment reminders
**Setup**:
* Add phone number from your provider
* Assign to appointment reminder Voice Agent
* Configure agent with appointment details
* Use "Make Outbound Call" feature to test
**Result**: System can place calls to remind customers of appointments
### Enterprise SIP Integration
**Scenario**: Integrate with existing enterprise SIP infrastructure
**Setup**:
* Configure SIP trunk with your carrier details
* Set up inbound origination URI (SIP-TCP/UDP)
* Configure outbound destination address
* Add authentication credentials if required
* Add custom headers for routing
* Test SIP connection before deployment
**Result**: Seamless integration with existing PBX and telephony infrastructure
### Multi-Agent Phone System
**Scenario**: Multiple agents handling different phone lines
**Setup**:
* Add multiple phone numbers
* Create specialized Voice Agents (sales, support, billing)
* Assign each number to appropriate agent
* Monitor calls in call history
**Result**: Professional multi-line phone system with specialized AI agents
## SIP Trunk Best Practices
### Inbound Configuration
1. **Choose Right Protocol**: Select TCP for most deployments, UDP for lower latency
2. **Whitelist IPs**: Configure your firewall to allow Hamsa's IP addresses
3. **Test Connectivity**: Always test before going live
4. **Monitor Calls**: Check call history regularly for connection issues
### Outbound Configuration
1. **Validate Address**: Ensure SIP destination is reachable
2. **Test Authentication**: Verify username/password before deployment
3. **Use Custom Headers**: Add routing headers as required by your carrier
4. **Choose Transport**: TCP for reliability, UDP for lower latency
5. **Document Settings**: Keep records of your SIP configuration
### Security
1. **Secure Credentials**: Store SIP credentials securely
2. **Choose Appropriate Transport**: Use TCP for reliability, UDP for lower latency
3. **IP Whitelisting**: Restrict access to known IP ranges
4. **Regular Audits**: Review SIP access logs periodically
5. **Rotate Credentials**: Change SIP passwords regularly
## Phone Number Limitations
### Provider-Specific Limitations
**Twilio:**
* Requires valid Twilio account
* Subject to Twilio's rate limits and pricing
* Geographic availability varies
**SIP Trunk:**
* Requires proper network configuration
* Firewall rules may need adjustment
* Carrier-specific requirements vary
* Custom headers depend on carrier support
### Platform Limitations
**Assignment:**
* One phone number can be assigned to one agent at a time
* Reassignment requires existing calls to complete
**Outbound Calls:**
* Requires agent to be assigned
* Requires valid API key configured
* Subject to concurrency limits of your plan
## Getting Started
1. **Choose Provider** - Select Twilio or SIP Trunk based on your needs
2. **Gather Credentials** - Collect necessary credentials from your provider
3. **[Add Phone Number](./managing-numbers#adding-phone-numbers)** - Use the Phone Numbers section to add your number
4. **[Assign to Agent](./managing-numbers#assigning-phone-numbers-to-voice-agents)** (Optional) - Connect the number to a Voice Agent when ready
5. **Test Connection** - Make a test call to verify configuration
6. **Monitor Calls** - Track calls in [Call History](/agents/call-history/introduction)
7. **[Create Batch Calls](/agents/batch-calls/introduction)** (Optional) - Use your phone number for batch calls
## What's Next?
* **[Quick Start](./quick-start)** - Get started with phone numbers in 4 simple steps
* **[Managing Phone Numbers](./managing-numbers)** - Learn how to add, configure, and delete phone numbers
* **[Making Outbound Calls](./making-calls)** - Understand how to place outbound calls
* **[Best Practices](./best-practices)** - Optimize your phone number management
## Related Documentation
Learn about creating and configuring Voice Agents
Track and monitor all your calls
Use your phone numbers for batch calls
Learn how to use phone numbers in batch calls
Monitor system performance