Overview

​

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.

​

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:

​

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

​

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 - Use the Phone Numbers section to add your number
4. Assign to Agent (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
7. Create Batch Calls (Optional) - Use your phone number for batch calls

​

What’s Next?

• Quick Start - Get started with phone numbers in 4 simple steps
• Managing Phone Numbers - Learn how to add, configure, and delete phone numbers
• Making Outbound Calls - Understand how to place outbound calls
• Best Practices - Optimize your phone number management

​

Related Documentation