> ## 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.
# Managing Phone Numbers
> Comprehensive guide to adding, configuring, assigning, and deleting phone numbers
## Overview
Learn how to effectively manage your phone numbers in the Hamsa platform. This guide covers adding numbers from different providers, configuring them, assigning them to Voice Agents, and managing their lifecycle.
## Adding Phone Numbers
### Adding a Twilio Number
1. **Navigate to Phone Numbers**
* Go to Dashboard → Phone Numbers
* Click the "Add Phone Number" button
* Select "Twilio" from the provider dropdown
2. **Enter Phone Number Details**
* **Phone Number**: Enter in E.164 format (e.g., +12025551234)
* Must start with '+'
* Include country code
* No spaces or special characters
* **Label**: Enter a descriptive name (1-100 characters)
* Examples: 'Main Support', 'Sales Line', 'Emergency Hotline'
* Helps identify the number's purpose
3. **Enter Twilio Credentials**
* **Twilio Account SID**: Found in your Twilio Console
* **Twilio Auth Token**: Found in your Twilio Console
* These credentials allow Hamsa to configure webhooks automatically
4. **Save Configuration**
* Click "Save" to create the phone number
* System validates credentials and configures webhooks
* Number appears in the list upon successful creation
**Twilio Webhook Configuration:**
When you add a Twilio number, Hamsa automatically configures the necessary webhooks in your Twilio account. This ensures inbound calls are routed correctly to your Voice Agents.
### Adding a SIP Trunk
1. **Navigate to Phone Numbers**
* Go to Dashboard → Phone Numbers
* Click the "Add Phone Number" button
* Select "SIP Trunk" from the provider dropdown
2. **Enter Basic Information**
* **Label**: Enter a descriptive name for the trunk
* **Phone Number**: Choose one of two options:
* **Phone Number** (radio button):
* Select country code from the dropdown (e.g., US +1)
* Enter phone number in the input field
* Use this for standard phone number format
* **Other** (radio button):
* Enter phone number or identifier in custom format
* Use this for non-standard formats or custom identifiers
* Enter directly in the text input field
3. **Configure Inbound Settings**
**Origination URI:**
* Select the protocol type:
* **SIP-TCP**: Standard TCP connection (most common)
* **SIP-UDP**: UDP connection (lower latency)
**Webhook URL:**
* Automatically provided by Hamsa
* Copy this URL to your SIP trunk configuration
* Used for inbound call handling
4. **Configure Outbound Settings**
**Address (Required):**
* Enter your SIP destination
* Can be an IP address (e.g., 192.168.1.100) or domain (e.g., sip.example.com)
* Must be reachable from Hamsa's infrastructure
**Transport Type (Required):**
* **TCP**: Reliable, connection-oriented (recommended)
* **UDP**: Connectionless, lower overhead
**Authentication (Optional):**
* **SIP Trunk Username**: If your trunk requires authentication
* **SIP Trunk Password**: Corresponding password
* Leave empty if your trunk uses IP-based authentication
**Custom Headers (Optional):**
* Add key-value pairs for call routing, metadata, or carrier integration
* Click the "+ Add Header" button to add a new header
* Enter a key in the left field (e.g., 'X-Carrier-ID', 'X-Trunk-Group')
* Enter a value in the right field (e.g., 'CARRIER123', 'PRIMARY')
* Add multiple headers as needed
* Remove headers by clicking the trash icon on the right
* Examples:
* Key: 'X-Carrier-ID', Value: 'CARRIER123'
* Key: 'X-Trunk-Group', Value: 'PRIMARY'
* Key: 'X-Route-ID', Value: 'ROUTE456'
5. **Test Connection**
* Click "Test Connection" button
* System validates:
* Destination reachability
* Authentication credentials (if provided)
* Network connectivity
* Review test results:
* ✅ Success: Configuration is correct
* ❌ Failed: Review error message and fix issues
6. **Save Configuration**
* Click "Save" after successful connection test
* Number becomes available for assignment
**SIP Trunk Requirements:**
* Your SIP trunk must be configured to accept connections from Hamsa
* Firewall rules may need to allow Hamsa's IP addresses
* Coordinate with your telephony provider for proper setup
* Test thoroughly before production use
### Provider-Specific Considerations
**Twilio:**
* Requires active Twilio account with available balance
* Phone number must be purchased in Twilio first
* Supports SMS and voice capabilities
* Geographic restrictions may apply
* Subject to Twilio's pricing and rate limits
**SIP Trunk:**
* Requires coordination with your telephony provider
* May need firewall configuration changes
* Supports advanced routing scenarios
* Custom header support varies by carrier
* IP whitelisting may be required
## Viewing Phone Number Details
1. **Access Phone Number List**
* Navigate to Phone Numbers section
* View all configured phone numbers
* Numbers display with:
* Provider icon (Twilio or SIP)
* Label
* Phone number
2. **Select a Phone Number**
* Click any phone number in the list
* Details panel opens on the right (desktop)
* Full-screen details on mobile
3. **Review Information**
**Basic Information Card:**
* Phone number with copy button
* Label
* Provider type badge
* Creation timestamp
**Voice Agent Assignment Card:**
* Current assignment status
* Dropdown to change assignment
* Reassignment confirmation when needed
**Provider Configuration Card:**
*For Twilio:*
* Twilio Account SID
* Webhook URL (automatically configured)
*For SIP Trunk:*
* View SIP configuration button
* Opens modal with full SIP details
* Includes inbound and outbound settings
## Assigning Phone Numbers to Voice Agents
### Initial Assignment
1. **Select Unassigned Number**
* Choose a phone number with "None" assignment
* Open the phone number details
2. **Choose Voice Agent**
* In "Voice Agent Assignment" card
* Click the dropdown (showing "None")
* Select desired Voice Agent from list
* Assignment happens immediately
3. **Verify Assignment**
* Dropdown now shows selected agent
* Number ready to receive calls
* Inbound calls route to assigned agent
### Reassigning a Phone Number
1. **Select Assigned Number**
* Choose phone number currently assigned to an agent
* Open phone number details
2. **Change Assignment**
* Click the Voice Agent dropdown
* Select a different agent
* Reassignment dialog appears
3. **Confirm Reassignment**
* Dialog warns about changing assignment
* Lists current and new agent
* Click "Confirm" to proceed
* Click "Cancel" to abort
4. **Assignment Updated**
* New agent now handles inbound calls
* Old agent no longer receives calls on this number
* Change is immediate
**Reassignment Impact:**
* Active calls are not interrupted
* New inbound calls route to new agent immediately
* Ensure new agent is properly configured
* Test after reassignment to verify
### Unassigning a Phone Number
1. **Select Assigned Number**
* Choose phone number with agent assigned
* Open phone number details
2. **Remove Assignment**
* Click Voice Agent dropdown
* Select "None" from the list
* Confirmation may be required
3. **Number Unassigned**
* Number no longer receives calls
* Can be reassigned to different agent
* Useful for maintenance or reconfiguration
## Managing SIP Trunk Configuration
### Viewing SIP Configuration
1. **Open SIP Number Details**
* Select a SIP trunk number from the list
* Details panel displays
2. **View Configuration**
* In Provider Configuration card
* Click "View SIP Configuration" button
* Modal opens with full details
3. **Configuration Details**
**Inbound Configuration:**
* Origination URI (protocol type)
* Webhook URL to configure in your trunk
**Outbound Configuration:**
* Destination address
* Transport type
* Authentication status (if configured)
* Custom headers (if configured)
4. **Copy Information**
* Use copy buttons for URLs and addresses
* Share with telephony provider as needed
* Keep records for troubleshooting
### Testing SIP Connection
The "Test Connection" function is only available during the initial setup when adding a new SIP trunk. It cannot be accessed from existing phone number details.
1. **Access Test Function**
* Available only when adding a new SIP trunk
* Click "Test Connection" button in the outbound configuration section
* Must be done before saving the phone number
2. **Test Execution**
* System attempts connection to SIP destination
* Validates authentication if configured
* Checks network reachability
* Process takes 5-10 seconds
3. **Review Results**
**Success:**
* Green success message
* Connection parameters validated
* Safe to save and use for production calls
**Failure:**
* Red error message with details
* Common issues:
* Destination unreachable
* Authentication failed
* Firewall blocking connection
* Invalid address format
* Fix issues and retest before saving
**Important:**
* Test Connection is only available during initial SIP trunk setup
* You must test before saving the phone number
* If you need to test an existing SIP trunk, you'll need to check call history or make a test call
* Always test during setup to ensure proper configuration before deployment
## Deleting Phone Numbers
### Delete Process
1. **Select Phone Number**
* Choose number to delete
* Open details panel
2. **Initiate Deletion**
* Click "Delete" button in header
* Located next to "Make Outbound Call" button
3. **Confirm Deletion**
* Confirmation dialog appears
* Shows phone number and label
* Warns that action cannot be undone
* Click "Delete" to confirm
* Click "Cancel" to abort
4. **Number Removed**
* Phone number deleted from system
* No longer appears in list
* Cannot receive or place calls
* Assignment removed if was assigned
**Deletion is Permanent:**
* Cannot be undone
* All configuration is lost
* Must re-add if needed later
* Active calls may be interrupted
* Ensure number is not critical before deleting
### Pre-Deletion Checklist
Before deleting a phone number:
* [ ] Verify number is not actively receiving important calls
* [ ] Check if number is published in marketing materials
* [ ] Confirm replacement number is configured (if applicable)
* [ ] Notify team members of the change
* [ ] Update any documentation referencing the number
* [ ] Consider unassigning instead of deleting for temporary changes
## Troubleshooting
### Phone Number Not Saving
**Possible Causes:**
* Invalid phone number format
* Missing required fields (credentials, address)
* Network connectivity issues
* Invalid Twilio credentials
* SIP destination unreachable
**Solutions:**
* Verify phone number is in E.164 format
* Check all required fields are filled
* Validate credentials with provider
* Test SIP connection before saving
* Check browser console for errors
### Assignment Changes Not Working
**Possible Causes:**
* Voice Agent was deleted
* Network issues during save
* Insufficient permissions
* Browser cache issues
**Solutions:**
* Verify agent exists in Voice Agents section
* Refresh the page and try again
* Check permissions with administrator
* Clear browser cache
* Try different browser
### SIP Connection Test Fails
**Common Issues:**
**Destination Unreachable:**
* Verify address is correct (IP or domain)
* Check network connectivity
* Confirm firewall allows outbound SIP
* Verify DNS resolution for domains
**Authentication Failed:**
* Verify username and password
* Check for typos in credentials
* Confirm credentials with provider
* Test with IP authentication if available
**Timeout:**
* Destination may be down
* Network latency too high
* Firewall blocking connection
* Try different transport type
### Calls Not Routing Correctly
**For Twilio:**
* Verify Twilio webhook is configured
* Check Twilio account is active
* Ensure sufficient balance
* Review Twilio debugger logs
**For SIP:**
* Verify SIP configuration is correct (test during initial setup)
* Verify inbound webhook configuration
* Check firewall allows inbound SIP
* Review custom headers with provider
* Check Call History for connection issues
## Using Phone Numbers for Batch Calls
Phone numbers can be used as the "From Number" in [Batch Calls](/agents/batch-calls/introduction) to execute batch calls.
### Requirements
**For Batch Calls:**
* Phone number must be configured and available in your account
* Number must support outbound calling (Twilio or SIP Trunk)
* Phone number does not need to be assigned to a Voice Agent (the batch call uses its own Voice Agent)
* Number must exist before creating the batch call
### How It Works
1. **Add Phone Number** - [Create your phone number](#adding-phone-numbers) using Twilio or SIP Trunk
2. **Create Batch Call** - Go to [Batch Calls](/agents/batch-calls/introduction) section
3. **Select From Number** - Choose your phone number from the "From Number" dropdown
4. **Select Voice Agent** - Choose the Voice Agent that will handle the batch calls
5. **Upload Recipients** - Upload CSV with recipient phone numbers
6. **Configure Schedule** - Set when calls should run
7. **Execute** - Batch calls use your phone number to call all recipients
**Batch Calls vs Individual Calls:**
* **Individual Calls**: Use the [Make Outbound Call](./making-calls) feature for single test calls
* **Batch Calls**: Use [Batch Calls](/agents/batch-calls/introduction) for bulk campaigns with multiple recipients
* Both use the same phone numbers, but batch calls are more efficient for large-scale operations
### Batch Call Benefits
**Efficiency:**
* Execute hundreds or thousands of calls automatically
* Better concurrency management
* Automated scheduling and time constraints
* Individual recipient status tracking
**Management:**
* Pause, resume, or cancel entire campaigns
* Retry failed or unanswered calls
* Track progress in real-time
* Export recipient data
**Use Cases:**
* Appointment reminders
* Marketing campaigns
* Customer notifications
* Survey calls
* Emergency alerts
Learn more about creating and managing batch calls in the [Batch Calls documentation](/agents/batch-calls/introduction).
## Related Documentation
Overview of Phone Numbers features
Get started quickly with phone numbers
Learn how to place individual outbound calls
Use phone numbers for batch calls
Step-by-step guide to creating batch calls
Optimize your phone number usage