USER_MANUAL.md

# vBot User Manual

## Introduction
vBot is an intelligent call analysis system that provides real-time transcription, summarization, and sentiment analysis for phone calls. This manual will guide you through setting up and using the system with FreePBX.

## Getting Started

### Installation
1. Install FreePBX:
   - Download and install FreePBX 16 or higher
   - Complete the FreePBX setup wizard
   - Ensure the system is properly configured

2. Install the customer webhook package:
   ```bash
   git clone https://huggingface.co/spaces/iajitpanday/vBot
   cd vBot/customer_webhook
   composer install
   cp config/config.example.php config/config.php
   ```

3. Configure FreePBX:
   - Enable call recording in FreePBX Admin
   - Set up recording paths
   - Configure recording formats
   - Set up SSL certificates

4. Configure the webhook package:
   - Update `config/config.php` with FreePBX database details
   - Set the vBot API URL and your API key
   - Configure the webhook endpoint

### 1. System Requirements
- FreePBX 16 or higher
- PHP 7.4 or higher
- MySQL 5.7 or higher (included with FreePBX)
- Apache web server (included with FreePBX)
- SSL certificate for secure webhooks

### 2. FreePBX Configuration
1. Recording Settings:
   - Enable call recording
   - Set recording format (WAV recommended)
   - Configure recording paths
   - Set up recording retention

2. Webhook Integration:
   - Configure webhook endpoint
   - Set up SSL for secure communication
   - Configure post-processing
   - Test webhook delivery

3. Security Settings:
   - Enable SSL
   - Configure firewall rules
   - Set up API key authentication
   - Implement rate limiting

### 3. Using the System
1. Making Calls:
   - Use FreePBX to make/receive calls
   - Recordings are automatically created
   - Results are sent via webhook

2. Viewing Results:
   - Access results through webhook
   - View transcriptions
   - Check sentiment analysis
   - Review call summaries

3. Managing Recordings:
   - Access through FreePBX interface
   - Download recordings
   - Manage storage
   - Set retention policies

### 4. Troubleshooting
1. Common Issues:
   - Recording not created
   - Webhook delivery failed
   - API connection issues
   - Performance problems

2. Solutions:
   - Check FreePBX logs
   - Verify webhook configuration
   - Test API connection
   - Monitor system resources

3. Support:
   - Contact support
   - Submit issues
   - Check documentation
   - Join community forums

### 5. Best Practices
1. Security:
   - Keep FreePBX updated
   - Use strong passwords
   - Enable SSL
   - Regular backups

2. Performance:
   - Monitor system resources
   - Optimize recording settings
   - Manage storage
   - Regular maintenance

3. Maintenance:
   - Regular updates
   - Monitor logs
   - Check storage
   - Backup configuration

### 6. Updates and Maintenance
1. System Updates:
   - Keep FreePBX updated
   - Update webhook package
   - Update SSL certificates
   - Test updates in staging

2. Regular Tasks:
   - Monitor system logs
   - Check recording storage
   - Verify webhook delivery
   - Update security certificates

3. Backup:
   - Backup FreePBX configuration
   - Backup recordings
   - Backup webhook configuration
   - Test restore procedures

### 7. Support
For additional support:
- Email: support@example.com
- Phone: +1-XXX-XXX-XXXX
- Documentation: https://docs.example.com
- Community: https://community.example.com

## Admin Interface

### 1. Dashboard

The dashboard shows:
- Total calls processed
- Recent activity
- System health
- Usage statistics

### 2. Customer Management

#### View Customers
- List all customers
- View customer details
- Check customer status

#### Add Customer
1. Click "Add Customer"
2. Fill in details:
   - Name
   - Company Name
   - Email
3. Save customer
4. Copy API key

#### Edit Customer
1. Select customer
2. Click "Edit"
3. Update details
4. Save changes

#### Delete Customer
1. Select customer
2. Click "Delete"
3. Confirm deletion

### 3. System Settings

#### API Configuration
- View API key
- Regenerate API key
- Set webhook URL
- Configure webhook secret

#### Security Settings
- Change password
- Enable 2FA
- Set session timeout

## API Usage

### 1. Process a Call

```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=@/path/to/call.wav" \
  -H "caller_number=${CALLER}" \
  -H "called_number=${CALLED}"
```

### 2. Receive Webhook Data

Your webhook endpoint receives:
```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
}
```

### 3. Rate Limits

- 100 API requests per minute
- 3 webhook retry attempts
- 10 concurrent calls

## Troubleshooting

### 1. Common Issues

#### Webhook Failures
1. Check webhook URL
2. Verify SSL certificate
3. Check webhook logs
4. Test webhook endpoint

#### API Errors
1. Verify API key
2. Check request format
3. Review error messages
4. Check rate limits

#### Database Issues
1. Test database connection
2. Check database logs
3. Verify permissions
4. Monitor disk space

### 2. Debug Tools

#### Log Files
```bash
# Webhook logs
tail -f /var/log/apache2/vbot-access.log

# Database logs
tail -f /var/log/mysql/error.log

# Asterisk logs
tail -f /var/log/asterisk/messages
```

#### Health Checks
```bash
# Check webhook endpoint
curl -X POST https://your-domain.com/vbot-webhook/webhook.php \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

# Check database
mysql -u vbot_user -p vbot_calls

# Check Asterisk
sudo asterisk -rx "core show version"
```

## Best Practices

### 1. Security

- Use strong passwords
- Keep API keys secure
- Enable HTTPS
- Regular security updates
- Monitor access logs

### 2. Performance

- Monitor system resources
- Regular maintenance
- Optimize database
- Clean old recordings
- Monitor disk space

### 3. Reliability

- Regular backups
- Monitor system health
- Test failover
- Keep systems updated
- Document procedures

## Updates and Maintenance

### 1. Regular Tasks

- Update system packages
- Rotate logs
- Backup database
- Clean old recordings
- Monitor disk space

### 2. Backup Strategy

```bash
# Database backup
mysqldump -u vbot_user -p vbot_calls > backup.sql

# Configuration backup
tar -czf config_backup.tar.gz /etc/asterisk/
```

### 3. Update Process

```bash
# Update webhook handler
cd /var/www/html/vbot-webhook
git pull

# Update Asterisk
sudo apt update
sudo apt upgrade
```

## Support

### 1. Getting Help

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

### 2. Reporting Issues

When reporting issues:
1. Check documentation
2. Review logs
3. Gather error messages
4. Provide system info
5. Describe steps to reproduce

### 3. Feature Requests

To request features:
1. Check existing issues
2. Create detailed proposal
3. Provide use cases
4. Suggest implementation
5. Submit request

## Glossary

- **API Key**: Unique identifier for API access
- **Webhook**: URL endpoint for receiving data
- **Transcription**: Text version of call audio
- **Sentiment**: Emotional tone of call
- **Keywords**: Important terms from call
- **Asterisk**: Open-source PBX system
- **PBX**: Private Branch Exchange
- **SSL**: Secure Sockets Layer
- **HTTPS**: Secure HTTP protocol
- **MySQL**: Database system
- **Apache**: Web server
- **Nginx**: Web server
- **AGI**: Asterisk Gateway Interface
- **SIP**: Session Initiation Protocol
- **RTP**: Real-time Transport Protocol