README.md

metadata

title: vBot - AI-Powered Call Analysis
emoji: 📞
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 4.19.2
app_file: main.py
pinned: false

vBot - Intelligent Call Analysis System

vBot is a distributed call analysis system where a central server ONLY handles AI-powered transcription and analysis, while each customer maintains their own complete infrastructure (FreePBX, database) and receives results via webhooks.

System Architecture

Central Server (vBot)

• ONLY handles call transcription and analysis
• ONLY manages customer accounts and API keys
• ONLY sends results via webhooks
• Hosted on Hugging Face Space
• Does NOT store customer data
• Does NOT connect to customer databases
• Does NOT manage customer infrastructure
• Does NOT store call recordings permanently

Customer Infrastructure (Remote)

Each customer maintains their own complete system:

• FreePBX server (includes Asterisk, Apache web server, and database)
• MySQL database (included with FreePBX)
• SSL certificate for secure webhooks
• Complete control over their data and infrastructure
• Full ownership of their call recordings

Features

• Centralized AI-powered call analysis
• Distributed customer infrastructure
• Secure customer isolation
• Real-time call processing
• Sentiment analysis and keyword extraction
• Modern admin interface for customer management
• Webhook-based result delivery
• Seamless FreePBX integration

System Requirements

Central Server (vBot)

• Python 3.8 or higher
• MySQL 5.7 or higher
• Hugging Face Space deployment

Customer Infrastructure

• FreePBX 16 or higher
• PHP 7.4 or higher
• MySQL 5.7 or higher (included with FreePBX)
• SSL certificate for secure webhooks

Quick Start

Central Server (vBot)

1. Deploy to Hugging Face Space:

   git clone https://huggingface.co/spaces/iajitpanday/vBot
   

2. Configure environment variables in Hugging Face Space settings:

   • DATABASE_URL: Your MySQL database connection string
   • SECRET_KEY: A secure random string for JWT token generation
   • API_BASE_URL: The base URL of your vBot API

Customer Setup

1. Install FreePBX:

   • Download and install FreePBX 16 or higher
   • Complete the FreePBX setup wizard
   • Ensure the system is properly configured

2. Clone the repository:

   git clone https://huggingface.co/spaces/iajitpanday/vBot
   cd vBot
   

3. Install the customer webhook package:

   cd customer_webhook
   composer install
   cp config/config.example.php config/config.php
   

4. Configure the webhook package:

   • Update config/config.php with your FreePBX database details
   • Set the vBot API URL and your API key
   • Configure FreePBX to use the webhook endpoint

5. Configure FreePBX:

   • Enable call recording in FreePBX
   • Set up the recording path
   • Configure the webhook endpoint in FreePBX
   • Set up SSL for secure webhook communication

Admin Setup (Central Server)

1. Access the admin interface:

   • URL: https://your-domain.com/admin
   • Default credentials: admin/admin (change immediately)

2. Create a new customer:

   • Click "Add Customer"
   • Fill in customer details:
     • Name
     • Company Name
     • Email
   • System will generate a unique API key

3. Configure customer webhook:

   • Customer provides their webhook URL
   • Optional: Set webhook secret for additional security

Customer Setup

1. Asterisk Configuration

On your Asterisk server:

[from-internal]
exten => _X.,1,Answer()
same => n,Record(/tmp/calls/${UNIQUEID}.wav,0,0)
same => n,Set(CALL_ID=${UNIQUEID})
same => n,Set(CALLER=${CALLERID(num)})
same => n,Set(CALLED=${EXTEN})
same => n,AGI(agi://localhost:4573/process_call)
same => n,Hangup()

2. Download Webhook Handler

git clone https://huggingface.co/spaces/iajitpanday/vBot/customer_webhook

3. Deploy to Your Web Server

cp -r customer_webhook/* /var/www/html/vbot-webhook/

4. Create Database

On your MySQL server:

CREATE DATABASE vbot_calls;
USE vbot_calls;

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
);

5. Configure Webhook Handler

• Copy config/config.example.php to config/config.php
• Update database credentials
• Add your API key (provided by vBot admin)

6. Configure Web Server

Apache Configuration

# Place in Apache configuration or .htaccess
RewriteEngine On
RewriteBase /vbot-webhook/
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ webhook.php [QSA,L]

Nginx Configuration

location /vbot-webhook/ {
    root /var/www/html;
    index webhook.php;
    
    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
        fastcgi_index webhook.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

API Integration

1. Process a Call (from your Asterisk server)

curl -X POST https://vbot-server.com/api/process-call \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/tmp/calls/${UNIQUEID}.wav" \
  -H "caller_number=${CALLER}" \
  -H "called_number=${CALLED}"

2. Receive Webhook Data

Your webhook endpoint will receive POST requests with call analysis results:

{
  "call_id": "uuid",
  "caller_number": "+1234567890",
  "called_number": "+0987654321",
  "transcription": "Call transcript...",
  "summary": "Call summary...",
  "sentiment": "positive",
  "keywords": "keyword1, keyword2",
  "timestamp": "2024-03-14T12:00:00Z",
  "customer_id": 123
}

Security

1. API Authentication:

   • All API requests require valid API key
   • API keys are unique per customer
   • Keys can be regenerated if compromised

2. Webhook Security:

   • HTTPS required for webhook endpoints
   • Optional webhook secret for signature validation
   • Input validation and sanitization

3. Data Protection:

   • Call recordings are temporary on central server
   • Analysis results sent securely via webhooks
   • Each customer maintains their own database
   • Complete data isolation between customers
   • No shared infrastructure

Monitoring

Central Server (vBot)

• Application logs: logs/app.log
• Error logs: logs/error.log
• Access logs: logs/access.log
• Health endpoint: /health

Customer Infrastructure

• Asterisk logs
• Webhook logs: logs/webhook.log
• Database monitoring
• Web server logs

Troubleshooting

1. Common Issues:

   • Webhook delivery failures
   • API key validation errors
   • Database connection issues
   • Asterisk integration problems

2. Solutions:

   • Check webhook URL and SSL
   • Verify API key
   • Test database connection
   • Review Asterisk logs
   • Check webhook logs

Support

For support:

• Email: support@vbot.com
• Documentation: https://vbot.com/docs
• GitHub Issues: https://github.com/vbot/issues

License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation

• Setup Guide - Detailed setup instructions
• User Manual - End-user documentation
• API Documentation - API reference and examples

Architecture

vBot follows a modern API-first architecture:

1. Core Components:

   • FastAPI backend
   • MySQL database
   • Hugging Face AI models
   • Asterisk integration

2. Data Flow:

   • Calls are received by Asterisk
   • Audio is processed by vBot
   • Results are stored and accessible via API
   • Customers access data through their API keys

3. Security:

   • JWT-based authentication for admin
   • API key authentication for customers
   • Secure data isolation between customers

Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

API Endpoints

Admin Endpoints