Managing 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

​

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

​

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

​

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

​

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

​

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

​

Best Practices

​

Organization

• Use Descriptive Labels: Make it easy to identify purpose
• Naming Convention: Establish consistent naming (e.g., ‘Support-Primary’, ‘Sales-East’)
• Document Purpose: Keep external records of number usage
• Regular Audits: Review phone numbers periodically

​

Assignment Management

• Test Before Production: Always test after assignment changes
• Monitor Call History: Check calls are routing correctly
• Avoid Frequent Changes: Minimize reassignments to prevent confusion
• Document Assignments: Keep records of which agents handle which numbers

​

SIP Trunk Management

• Test During Setup: Always test SIP connection when adding a new trunk
• Monitor Call Quality: Check Call History for issues after deployment
• Keep Credentials Secure: Protect SIP authentication details
• Document Configuration: Maintain records of SIP settings
• Coordinate with Provider: Work closely with telephony provider

​

Security

• Protect Credentials: Never share Twilio or SIP credentials publicly
• Rotate Credentials: Change authentication credentials periodically
• Monitor Usage: Review Call History for suspicious activity
• Limit Access: Restrict phone number management to authorized users

​

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 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 using Twilio or SIP Trunk
2. Create Batch Call - Go to Batch Calls 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 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

​

Related Documentation