README.md

---
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:
   ```bash
   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:
   ```bash
   git clone https://huggingface.co/spaces/iajitpanday/vBot
   cd vBot
   ```

3. Install the customer webhook package:
   ```bash
   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:
```ini
[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
```bash
git clone https://huggingface.co/spaces/iajitpanday/vBot/customer_webhook
```

### 3. Deploy to Your Web Server
```bash
cp -r customer_webhook/* /var/www/html/vbot-webhook/
```

### 4. Create Database
On your MySQL server:
```sql
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
```apache
# 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
```nginx
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)
```bash
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:
```json
{
  "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](SETUP_GUIDE.md) - Detailed setup instructions
- [User Manual](USER_MANUAL.md) - End-user documentation
- [API Documentation](API_DOCS.md) - 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