VoIP Caller ID & Call Management System

A comprehensive web-based tool for changing caller ID and placing real-time VoIP calls using Asterisk and VoIP.ms SIP trunking.

Features

• Real-time VoIP calling via Asterisk AMI integration
• Dynamic caller ID setting for outbound calls
• VoIP.ms SIP trunk configuration and management
• Phone number validation (E.164 format)
• RESTful API endpoints for call control
• Call monitoring and channel management
• CLI fallback scripts for direct Asterisk control
• Comprehensive error handling and logging

Setup

1. Install dependencies:

   npm install

2. Create environment file:

   cp .env.example .env

3. Configure your VoIP.ms and Asterisk credentials in .env:

   PORT=3000
   
   # Legacy telecom API (optional)
   TELECOM_API_KEY=your_api_key_here
   TELECOM_API_URL=https://api.telecom-provider.com/v1
   TELECOM_ACCOUNT_SID=your_account_sid_here
   
   # VoIP.ms SIP Configuration
   VOIPMS_SIP_USERNAME=your_voipms_username
   VOIPMS_SIP_PASSWORD=your_voipms_password
   VOIPMS_SIP_SERVER=newyork.voip.ms
   
   # Asterisk AMI Configuration
   ASTERISK_AMI_HOST=localhost
   ASTERISK_AMI_PORT=5038
   ASTERISK_AMI_USER=admin
   ASTERISK_AMI_PASS=your_ami_password
   

Usage

Start the server:

npm start

For development with auto-reload:

npm run dev

Asterisk Configuration

Before using the VoIP calling features, you need to configure Asterisk with the provided configuration files:

1. Copy Configuration Files

# Copy SIP configuration
sudo cp asterisk-configs/sip.conf /etc/asterisk/sip.conf

# Copy dialplan configuration  
sudo cp asterisk-configs/extensions.conf /etc/asterisk/extensions.conf

# Copy AMI configuration
sudo cp asterisk-configs/manager.conf /etc/asterisk/manager.conf

2. Update Configuration with Your Credentials

Edit the configuration files and replace the placeholder variables with your actual credentials:

• ${VOIPMS_SIP_USERNAME} - Your VoIP.ms SIP username
• ${VOIPMS_SIP_PASSWORD} - Your VoIP.ms SIP password
• ${ASTERISK_AMI_PASS} - Your desired AMI password

3. Restart Asterisk

sudo systemctl restart asterisk
# or
sudo asterisk -rx "core reload"

4. Test SIP Registration

asterisk -rx "sip show peers"
asterisk -rx "sip show registry"

API Endpoints

Health Check

GET /health

Legacy Caller ID Change (API-based)

POST /api/caller-id/change
Content-Type: application/json

{
  "fromNumber": "+1234567890",
  "toNumber": "+0987654321",
  "newCallerId": "+1111111111"
}

Place VoIP Call (Asterisk-based)

POST /api/caller-id/call
Content-Type: application/json

{
  "to": "+15551234567",
  "from": "+15559876543",
  "context": "outbound",
  "timeout": 30000
}

Hangup Active Call

POST /api/caller-id/hangup
Content-Type: application/json

{
  "channel": "Local/15551234567@outbound-00000001;1"
}

Get Active Channels

GET /api/caller-id/channels

Get Available Caller IDs

GET /api/caller-id/available

Testing

Run the test suite:

npm test

Note: Make sure the server is running before running tests.

Command Line Interface

Using the Shell Script

Place calls directly via command line:

# Basic call
./call.sh +15551234567 +15559876543

# Call with custom context
./call.sh +15551234567 +15559876543 outbound

# The script will validate phone numbers and provide detailed output

Direct Asterisk Commands

# Check Asterisk status
asterisk -rx "core show channels"

# Check SIP peers
asterisk -rx "sip show peers"

# Originate a call manually
asterisk -rx "channel originate Local/15551234567@outbound extension 15551234567@outbound"

Security Considerations

1. Firewall Configuration: Ensure proper firewall rules for:

   • SIP (UDP 5060)
   • RTP (UDP 10000-20000)
   • AMI (TCP 5038) - restrict to localhost

2. AMI Security:

   • Use strong passwords for AMI users
   • Restrict AMI access by IP address
   • Consider using fail2ban for brute force protection

3. Let's Encrypt: For production, consider TLS encryption:

   # Install certbot and configure SSL
   sudo certbot --nginx -d yourdomain.com

Network Configuration

NAT and External IP

If running behind NAT, update the SIP configuration:

[general]
externip=your.external.ip.address
localnet=192.168.1.0/255.255.255.0
nat=yes

VoIP.ms Server Options

Choose the server closest to your location:

• newyork.voip.ms
• chicago.voip.ms
• losangeles.voip.ms
• montreal.voip.ms
• toronto.voip.ms

Troubleshooting

Common Issues

1. SIP Registration Failed

   asterisk -rx "sip show registry"
   # Check credentials and server settings

2. AMI Connection Failed

   # Check AMI is enabled and credentials are correct
   asterisk -rx "manager show users"

3. Calls Not Connecting

   # Check dial plan and SIP peer status
   asterisk -rx "dialplan show outbound"
   asterisk -rx "sip show peers"

4. Audio Issues

   • Verify RTP port range (10000-20000) is open
   • Check NAT configuration
   • Test with a SIP client (Zoiper, etc.) first

Phone Number Format

All phone numbers should be in E.164 format (e.g., +1234567890).

Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Express API   │────│   Asterisk AMI   │────│   VoIP.ms SIP   │
│   (Node.js)     │    │   (Call Control) │    │   (SIP Trunk)   │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                        │                       │
         │                        │                       │
    ┌────▼────┐              ┌────▼────┐            ┌────▼────┐
    │ REST    │              │ Dial    │            │ PSTN    │
    │ Client  │              │ Plan    │            │ Network │
    └─────────┘              └─────────┘            └─────────┘