FREEPBX_SETUP.md

vBot FreePBX Setup Guide

Overview

This guide provides detailed instructions for setting up FreePBX to work with vBot. FreePBX will handle call recording and webhook integration, while vBot processes the recordings and returns analysis results. All call records are stored locally in the FreePBX database.

Prerequisites

• FreePBX 16 or higher
• MySQL 5.7 or higher (included with FreePBX)
• PHP 7.4 or higher (included with FreePBX)
• SSL certificate for secure webhooks
• vBot API key (provided by central server admin)

Step 1: FreePBX Installation

1. Download FreePBX:

   • Visit https://www.freepbx.org/downloads/
   • Download FreePBX 16 or higher
   • Follow the installation guide

2. Complete FreePBX Setup:

   • Run the setup wizard
   • Configure basic settings
   • Set up admin credentials
   • Configure network settings

3. Verify Installation:

   # Check FreePBX version
   sudo asterisk -rx "core show version"
   
   # Check MySQL version
   mysql --version
   
   # Check PHP version
   php -v
   

Step 2: FreePBX Configuration

1. Configure Call Recording:

   • Log in to FreePBX Admin
   • Go to Admin → Call Recording
   • Enable call recording
   • Set recording path: /var/spool/asterisk/monitor
   • Configure recording format: WAV
   • Set recording options

2. Set Up Recording Post-Processing:

   • Log in to FreePBX Admin
   • Go to Admin → Advanced Settings
   • Navigate to "System Recordings" section
   • Enable "Post Call Recording Script"
   • Set the script path: /var/lib/asterisk/agi-bin/process_call
   • Configure script parameters:

     ${UNIQUEID} ${CALLERID(num)} ${EXTEN}
     

   • Set execution permissions:

     sudo chmod +x /var/lib/asterisk/agi-bin/process_call
     sudo chown asterisk:asterisk /var/lib/asterisk/agi-bin/process_call
     

   • Configure recording options:
     • Set recording format to WAV
     • Enable automatic recording
     • Set recording path
     • Configure file naming convention
   • Test recording:

     # Make a test call
     # Check recording directory
     ls -l /var/spool/asterisk/monitor/
     # Verify script execution
     tail -f /var/log/asterisk/messages
     

3. Configure Webhook Integration:

   • Go to Admin → Advanced Settings
   • Navigate to "Webhooks" section
   • Add new webhook:
     • Name: vBot Call Processing
     • URL: https://iajitpanday-vbot.hf.space/api/v1/process-call
     • Method: POST
     • Headers:

       X-API-Key: your_api_key
       Content-Type: multipart/form-data
       

     • Payload:

       file=@${RECORDING_FILE}
       caller_number=${CALLERID(num)}
       called_number=${EXTEN}
       

   • Configure webhook triggers:
     • Event: Call Recording Complete
     • Conditions: All calls
   • Set retry policy:
     • Max retries: 3
     • Retry interval: 5 seconds
   • Enable webhook logging:

     sudo nano /etc/asterisk/logger.conf
     # Add:
     [logfiles]
     webhook => notice,warning,error,debug
     

   • Test webhook:

     # Test webhook delivery
     curl -X POST https://iajitpanday-vbot.hf.space/api/v1/process-call \
       -H "X-API-Key: your_api_key" \
       -H "Content-Type: multipart/form-data" \
       -F "file=@/var/spool/asterisk/monitor/test.wav" \
       -F "caller_number=+1234567890" \
       -F "called_number=+0987654321"
     
     # Test webhook reception
     curl -X POST https://your-freepbx-domain.com/customer_webhook/webhook.php \
       -H "Content-Type: application/json" \
       -d '{"test": true}'
     

4. Configure SSL:

   • Go to Admin → Certificates
   • Generate or upload SSL certificate
   • Configure HTTPS settings
   • Verify SSL configuration

Step 3: Webhook Integration

1. Install Webhook Package:

   cd /var/www/html
   git clone https://huggingface.co/spaces/iajitpanday/vBot/customer_webhook
   cd customer_webhook
   composer install
   

2. Configure Webhook:

   cp config/config.example.php config/config.php
   nano config/config.php
   

   <?php
   return [
       'db' => [
           'host' => 'localhost',
           'name' => 'vbot_calls',
           'user' => 'vbot_user',
           'pass' => 'your_password'
       ],
       'api_key' => 'your_api_key',
       'api_url' => 'https://iajitpanday-vbot.hf.space',
       'webhook_secret' => 'your_webhook_secret'
   ];
   

3. Set Permissions:

   chown -R asterisk:asterisk /var/www/html/customer_webhook
   chmod -R 755 /var/www/html/customer_webhook
   

Step 4: Database Setup

1. Create Database:

   CREATE DATABASE vbot_calls;
   USE vbot_calls;
   
   -- This table stores all call records locally
   -- The central vBot server does not store call records
   CREATE TABLE call_records (
       id VARCHAR(36) PRIMARY KEY,
       customer_id INT NOT NULL,
       caller_number VARCHAR(20) NOT NULL,
       called_number VARCHAR(20) NOT NULL,
       transcription TEXT,
       summary TEXT,
       sentiment VARCHAR(50),
       keywords TEXT,
       created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
       updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
   );
   

2. Create Database User:

   CREATE USER 'vbot_user'@'localhost' IDENTIFIED BY 'your_password';
   GRANT ALL PRIVILEGES ON vbot_calls.* TO 'vbot_user'@'localhost';
   FLUSH PRIVILEGES;
   

Step 5: Call Processing Setup

1. Configure Dialplan:

   • Go to Admin → Dialplan
   • Add custom dialplan for call recording
   • Configure post-recording processing

2. Set Up AGI Script:

   nano /var/lib/asterisk/agi-bin/process_call
   

   #!/bin/bash
   CALL_ID=$1
   CALLER=$2
   CALLED=$3
   
   curl -X POST https://iajitpanday-vbot.hf.space/api/v1/process-call \
     -H "X-API-Key: your_api_key" \
     -H "Content-Type: multipart/form-data" \
     -F "file=@/var/spool/asterisk/monitor/${CALL_ID}.wav" \
     -F "caller_number=${CALLER}" \
     -F "called_number=${CALLED}"
   

3. Set Script Permissions:

   chmod +x /var/lib/asterisk/agi-bin/process_call
   chown asterisk:asterisk /var/lib/asterisk/agi-bin/process_call
   

Step 6: Security Configuration

1. Firewall Setup:

   sudo ufw allow 80/tcp
   sudo ufw allow 443/tcp
   sudo ufw allow 5060/udp  # SIP
   sudo ufw allow 10000:20000/udp  # RTP
   sudo ufw enable
   

2. SSL Configuration:

   • Use Let's Encrypt for free SSL certificates
   • Configure automatic renewal
   • Use strong cipher suites

3. File Permissions:

   • Secure webhook handler files
   • Restrict access to call recordings
   • Use appropriate ownership

Step 7: Testing

1. Test Call Recording:

   # Make a test call
   # Check recording directory
   ls -l /var/spool/asterisk/monitor/
   
   # Check FreePBX logs
   tail -f /var/log/asterisk/messages
   

2. Test Webhook:

   # Test webhook delivery
   curl -X POST https://iajitpanday-vbot.hf.space/api/v1/process-call \
     -H "X-API-Key: your_api_key" \
     -H "Content-Type: multipart/form-data" \
     -F "file=@/var/spool/asterisk/monitor/test.wav" \
     -F "caller_number=+1234567890" \
     -F "called_number=+0987654321"
   
   # Test webhook reception
   curl -X POST https://your-freepbx-domain.com/customer_webhook/webhook.php \
     -H "Content-Type: application/json" \
     -d '{"test": true}'
   

3. Test Database:

   SELECT * FROM call_records ORDER BY created_at DESC LIMIT 1;
   

Step 8: Monitoring

1. Log Monitoring:

   # FreePBX logs
   tail -f /var/log/asterisk/messages
   
   # Webhook logs
   tail -f /var/log/apache2/vbot-access.log
   
   # Database logs
   tail -f /var/log/mysql/error.log
   

2. System Monitoring:

   # Install monitoring tools
   sudo apt install prometheus node-exporter
   
   # Configure monitoring
   sudo nano /etc/prometheus/prometheus.yml
   

Step 9: Maintenance

1. Regular Tasks:

   • Update FreePBX
   • Rotate logs
   • Backup database
   • Clean old recordings

2. Backup Strategy:

   # Database backup
   mysqldump -u vbot_user -p vbot_calls > backup.sql
   
   # Configuration backup
   tar -czf config_backup.tar.gz /etc/asterisk/
   

3. Update Process:

   # Update FreePBX
   sudo apt update
   sudo apt upgrade
   
   # Update webhook package
   cd /var/www/html/customer_webhook
   git pull
   

Troubleshooting

1. Common Issues:

   • Call recording failures
   • Webhook delivery problems
   • Database connection errors
   • SSL certificate issues

2. Debug Tools:

   # Check FreePBX CLI
   sudo asterisk -rx "core show version"
   
   # Check webhook logs
   tail -f /var/log/apache2/vbot-error.log
   
   # Test database connection
   mysql -u vbot_user -p vbot_calls
   

3. Support:

   • Check FreePBX documentation
   • Review logs
   • Contact support
   • Submit issues