Multi-Tenant DID Optimization Service for VICIdial with intelligent rotation algorithms, real-time analytics, and machine learning-based optimization.
This system provides intelligent Direct Inward Dialing (DID) optimization for VICIdial call centers, featuring:
- 🌍 Geographic Proximity Matching: Automatically selects DIDs closest to customer locations
- 📊 Daily Usage Limits: Prevents DID burnout with configurable usage caps
- 🤖 AI-Powered Optimization: Machine learning models that improve selection over time
- 🔐 Multi-Tenant Architecture: Secure isolation for multiple organizations
- 📈 Real-Time Analytics: Comprehensive metrics and reporting
- ⚡ High Performance: Optimized for high-volume call centers
- Geographic Algorithm: Uses Haversine formula for precise distance calculations
- Usage Balancing: Automatically distributes calls across DID pools
- State/Area Code Matching: Prioritizes local presence for better answer rates
- Reputation Filtering: Automatically excludes DIDs with poor reputation scores (<50)
- Fallback Strategies: Multiple algorithms ensure calls always get a DID
- Seamless Setup: Simple configuration via Asterisk dialplan
- Real-Time API: Fast DID selection during active calls
- Comprehensive Reporting: Collects call outcomes for AI training
- Campaign-Specific Rules: Different optimization strategies per campaign
- Usage Tracking: Monitor DID performance and utilization
- Success Metrics: Track answer rates, conversion rates, and more
- Alert System: Notifications for API failures or limit breaches
- Export Options: Data exports for external analysis
- VICIdial server with Asterisk
- MongoDB server for DID Optimizer data
- Node.js 18+ for the API server
- Root access on VICIdial server for installation
# Clone the repository
git clone https://github.com/nikvb/vicidial-did-optimizer.git
cd vicidial-did-optimizer
# Install dependencies
npm install
# Configure environment variables
cp .env.example .env
# Edit .env with your settings (MongoDB URL, API key, etc.)
# Start the server
PORT=5000 node server-full.js# 1. Download the installer
wget https://raw.githubusercontent.com/nikvb/vicidial-did-optimizer/main/vicidial-integration/install-vicidial-integration-autodetect.sh
# 2. Make it executable
chmod +x install-vicidial-integration-autodetect.sh
# 3. Run the installer (as root)
sudo ./install-vicidial-integration-autodetect.shThe installer will:
- ✅ Auto-detect your VICIdial database settings
- ✅ Auto-detect your AGI directory location
- ✅ Install all required AGI scripts
- ✅ Configure the API endpoint settings
- ✅ Set up logging in
/var/log/astguiclient/ - ✅ Install Perl dependencies automatically
After installation, edit /etc/asterisk/dids.conf to set your API server details:
[general]
# Your DID Optimizer API server
api_base_url=http://your-api-server:5000
api_key=YOUR_ACTUAL_API_KEY_HERE
# Fallback DID when API is unavailable
fallback_did=+18005551234- Install the DID Optimizer Service (see Server Setup)
- Configure VICIdial Integration (see VICIdial Setup)
- Node.js 18+
- MongoDB 4.4+
- Redis 6+
- PostgreSQL 12+ (optional)
# Clone the repository
git clone https://github.com/nikvb/vicidial-did-optimizer.git
cd vicidial-did-optimizer
# Install dependencies
npm install
# Configure environment
cp .env.example .env
# Edit .env with your database credentials
# Start the service
npm start# Database
MONGODB_URI=mongodb://localhost:27017/did_optimizer
REDIS_URL=redis://localhost:6379
# API Configuration
PORT=3001
JWT_SECRET=your_jwt_secret_here
API_KEY=your_secure_api_key
# VICIdial Integration
VICIDIAL_DB_HOST=localhost
VICIDIAL_DB_USER=cron
VICIDIAL_DB_PASS=1234
VICIDIAL_DB_NAME=asteriskThe installer automatically handles this, or manually:
# Copy configuration
sudo cp dids.conf /etc/asterisk/
sudo chmod 600 /etc/asterisk/dids.conf
# Copy integration script
sudo cp vicidial-did-optimizer-config.pl /usr/share/astguiclient/
sudo chmod +x /usr/share/astguiclient/vicidial-did-optimizer-config.pl
# Install Perl dependencies
sudo apt-get install libwww-perl libjson-perl libdbi-perl libdbd-mysql-perlEdit /etc/asterisk/dids.conf:
[general]
# Your DID Optimizer server
api_base_url=http://your-server.com:3001
api_key=your_actual_api_key_here
# Optimization settings
daily_usage_limit=200
max_distance_miles=500
enable_geographic_routing=1Add to /etc/asterisk/extensions.conf (or let the installer handle this):
; DID Optimizer Integration
[did-optimizer]
exten => _X.,1,NoOp(=== DID Optimizer: Processing ${EXTEN} ===)
exten => _X.,n,System(/usr/share/astguiclient/vicidial-did-optimizer-config.pl "${campaign}" "${agent}" "${EXTEN}" > /tmp/did_${campaign}_${UNIQUEID})
exten => _X.,n,Set(SELECTED_DID=${FILE(/tmp/did_${campaign}_${UNIQUEID})})
exten => _X.,n,Set(CALLERID(num)=${SELECTED_DID})
exten => _X.,n,Goto(vicidial-auto,${EXTEN},1)
; Modify your [vicidial-auto] context - add as first line:
[vicidial-auto]
exten => _X.,1,GotoIf($["${CALLERID(num)}" = "COMPAT_DID_OPTIMIZER"]?did-optimizer,${EXTEN},1)
; ... rest of your existing dialplan ...
- Login to VICIdial Admin Interface
- Go to: Admin → Campaigns → [Your Campaign]
- Set Outbound Caller ID:
COMPAT_DID_OPTIMIZER - Set Campaign CID Override:
Y - Click SUBMIT
sudo asterisk -rx "dialplan reload"sudo -u asterisk /usr/share/astguiclient/vicidial-did-optimizer-config.pl --testsudo -u asterisk /usr/share/astguiclient/vicidial-did-optimizer-config.pl "CAMPAIGN001" "1001" "4155551234" "CA" "94102"# DID Optimizer logs
tail -f /var/log/astguiclient/did_optimizer.log
# Asterisk logs
tail -f /var/log/asterisk/messagesGET /api/v1/dids/next?campaign_id=SALES001&agent_id=1001&customer_phone=4155551234&customer_state=CA&customer_zip=94102GET /api/v1/healthGET /api/v1/analytics/metrics
GET /api/v1/analytics/reportsgeographic: Distance-based selection with daily limitsround_robin: Equal distribution across DIDsrandom: Random selection from available poolleast_used: Prioritizes DIDs with lowest usageml_optimized: AI-powered selection (requires training)
max_distance_miles: Maximum distance for DID selectionenable_state_fallback: Use state-level matching if no local DIDsenable_area_code_detection: Match area codes when possible
daily_usage_limit: Max calls per DID per day (default: 200)api_timeout: Request timeout in seconds (default: 10)cache_ttl: Cache time-to-live in seconds (default: 3600)
❌ "API key not configured"
# Solution: Update the config file
sudo nano /etc/asterisk/dids.conf
# Set: api_key=your_actual_key_here❌ "Permission denied"
# Solution: Fix file permissions
sudo chmod 600 /etc/asterisk/dids.conf❌ "Can't locate JSON.pm"
# Solution: Install Perl dependencies
sudo apt-get install libwww-perl libjson-perl libdbi-perl libdbd-mysql-perl# Check script permissions
ls -la /usr/share/astguiclient/vicidial-did-optimizer-config.pl
# Test API connectivity
curl -H "x-api-key: YOUR_KEY" http://your-server:3001/api/v1/health
# Check configuration loading
sudo -u asterisk /usr/share/astguiclient/vicidial-did-optimizer-config.pl --config- Quick Setup Guide - Get up and running in 3 steps
- Dialplan Integration - Detailed VICIdial setup
- Step-by-Step Dialplan Modification - Manual configuration guide
- API Documentation - Complete API reference
- Configuration Reference - All configuration options
We welcome contributions! Please see our Contributing Guide for details.
git clone https://github.com/nikvb/vicidial-did-optimizer.git
cd vicidial-did-optimizer
npm install
npm run devThis project is licensed under the MIT License - see the LICENSE file for details.
- 📧 Email: support@example.com
- 🐛 Issues: GitHub Issues
- 💬 Discussions: GitHub Discussions
When working correctly, you'll see:
✅ Improved Answer Rates: Local presence increases customer pickup rates ✅ Balanced DID Usage: Prevents individual DIDs from being flagged as spam ✅ Real-Time Optimization: AI learns and improves selection over time ✅ Comprehensive Analytics: Deep insights into call performance
🚀 Transform your VICIdial campaigns with intelligent DID optimization!