# VoIP Notification System for Class Routines

## Overview
This system provides automated VoIP notifications to teachers when their class routine time arrives. The system monitors class schedules and sends notifications to teachers at the appropriate times.

## Features
- Automated VoIP notifications to teachers when their class is about to start
- Manual notification triggering for specific classes
- Precise timing notifications that occur exactly when class time arrives
- Configurable notification timing
- Comprehensive logging of all notification attempts
- Integration with the existing class routine system

## Files Created/Modified

### Core Components
- `classes/VoIPNotificationService.php` - Main VoIP notification service class
- `config/voip_settings.php` - Configuration for VoIP notification system
- `cron/check_class_notifications.php` - Cron script for periodic checks
- `teachers/class_notification.php` - Direct notification handler
- `test_voip_notifications.php` - Test script
- `trigger_class_voip.php` - Direct trigger for class notifications
- `add_sample_timetable.php` - Utility to add sample timetable data for testing

### Modified Files
- `teachers/routine.php` - Added VoIP notification functionality to class routine page

## Setup Instructions

### 1. Configure VoIP Settings
Edit `config/voip_settings.php` to adjust settings:
- `VOIP_ENABLED` - Set to `true` to enable notifications
- `VOIP_CHECK_INTERVAL` - How often the cron job runs (in seconds)
- `VOIP_NOTIFICATION_WINDOW` - How early to send notifications (in seconds)
- `VOIP_PROVIDER` - VoIP service provider (currently set to SIMULATED)

### 2. Set Up Cron Job
To enable automatic notifications, add this line to your crontab to run every minute for precise timing:

```
* * * * * /usr/bin/php /path/to/your/project/cron/check_class_notifications.php
```

Or for Windows Task Scheduler, create a task that runs every minute:
```
C:\xampp\php\php.exe C:\MAMP\htdocs\bidda\cron\check_class_notifications.php
```

### 3. Ensure Teachers Have Phone Numbers
For the system to work, teachers must have phone numbers stored in the `teachers` table in the `phone` column.

## Exact Timing Feature

The system is designed to announce class routines at the exact class time by:

1. Checking the current time against scheduled class start times every minute
2. Looking for classes that are starting exactly at the current time
3. Including a small grace period (5 minutes) to catch any timing discrepancies during normal school hours (7:00 AM - 6:00 PM)
4. Sending immediate VoIP notifications when a match is found

The timing precision is achieved through:
- Frequent checks (every minute via cron)
- Exact time matching (TIME(start_time) = current_time)
- Small time window for precision (current_time to current_time + 5 minutes)
- School hours restriction (7:00 AM - 6:00 PM) to avoid notifications at unusual hours

## Testing the System

### Adding Sample Data
If you don't have any timetable data for testing, you can add a sample entry:

```
php add_sample_timetable.php
```

This will create a sample class scheduled for Wednesday at 10:00 AM - 11:00 AM.

### Manual Testing
Run the test script to verify the system works:
```
php test_voip_notifications.php
```

### Direct URL Testing
To test the specific URL mentioned in the requirements, you need to have a class scheduled for the current time. If you added the sample data above, you would need to wait until 10:00 AM on Wednesday to see the notification trigger.

## Usage

### Automatic Notifications
The system automatically checks for classes starting at the exact time every minute (or as configured) and sends notifications to teachers whose classes are starting right now.

### Manual Notifications
Administrators can manually trigger VoIP notifications for specific classes directly from the class routine page by clicking the phone icon button.

### Direct URL Access
The system can also be triggered via URL:
```
http://localhost/bidda/teachers/class_notification.php?session_id=X&class_id=Y&teacher_id=Z
```

## Integration with Existing System

The VoIP notification system integrates seamlessly with the existing class routine system:

1. When viewing class routines, administrators see an additional "VoIP Notification" button next to each class
2. The system checks the timetable database for classes starting at the exact time
3. When a class is starting right now, notifications are sent to the assigned teacher
4. All notifications are logged for tracking and troubleshooting

## Production Considerations

### VoIP Provider Integration
The current implementation uses a simulated VoIP service. For production use, integrate with a real VoIP provider such as:

#### Twilio Integration
Uncomment and configure these settings in `config/voip_settings.php`:
```php
define('VOIP_PROVIDER', 'TWILIO');
define('TWILIO_ACCOUNT_SID', 'your_account_sid');
define('TWILIO_AUTH_TOKEN', 'your_auth_token');
define('TWILIO_PHONE_NUMBER', 'your_twilio_number');
```

Then implement the `sendViaTwilio` method in the `VoIPNotificationService` class.

### Security
- Ensure the cron script cannot be accessed via web requests
- Validate and sanitize all input parameters
- Use proper authentication for manual notification triggers

### Performance
- Monitor database performance with frequent queries
- Adjust check intervals based on system load
- Consider caching mechanisms for large institutions

## Troubleshooting

### Notifications Not Sending
1. Check that `VOIP_ENABLED` is set to `true`
2. Verify that teachers have phone numbers in the database
3. Check the logs in the `/logs/voip/` directory
4. Ensure the cron job is running properly
5. Confirm that classes are scheduled during normal school hours (7:00 AM - 6:00 PM)

### Cron Job Issues
1. Verify the cron job is scheduled correctly
2. Check that the PHP path is correct in the cron entry
3. Ensure the script has proper permissions to execute
4. Monitor the log files for error messages

## Future Enhancements

1. Real VoIP provider integration (Twilio, Plivo, etc.)
2. Customizable notification messages
3. Opt-in/opt-out functionality for teachers
4. SMS fallback for missed VoIP calls
5. Mobile app push notifications
6. Advanced scheduling options