# FlexPBX Feature Implementation Summary
**Date:** October 14, 2025
**Status:** Production Ready

---

##  Completed Features

### 1. Conditional Queue Audio System 

**Feature Codes:**
- **\*45** - Queue Login (support queue)
- **\*46** - Queue Logout (support queue)
- **\*47** - Queue Status (support queue)

**Conditional Logic:**
- Different audio plays depending on current queue membership status
- Uses `QUEUE_MEMBER()` function to check status before taking action
- Prevents duplicate login/logout attempts

**Audio Files:**
1. `callcueue-loged-out-to-in-prompt.wav` - Plays when successfully joining queue via \*45
2. `callcueue-login.wav` - Plays when dialing \*45 but already logged in
3. `callcueue-loged-in-to-out-prompt.wav` - Plays when successfully leaving queue via \*46
4. `callcueue-logout.wav` - Plays when dialing \*46 but already logged out

**Technical Implementation:**
- Location: `/etc/asterisk/extensions.conf` lines 936-963
- Audio files: `/var/lib/asterisk/sounds/callcueue-*`
- Formats: WAV (16-bit, 8kHz, mono) and ulaw
- Permissions: asterisk:asterisk, 644

**Testing:**
```
Dial *45 first time  -> Hear login success message -> Added to queue
Dial *45 again       -> Hear "already logged in" message -> No action
Dial *46 first time  -> Hear logout success message -> Removed from queue
Dial *46 again       -> Hear "already out" message -> No action
```

---

### 2. Music on Hold Streaming System 

**Configuration File:** `/etc/asterisk/musiconhold.conf`

**Supported Sources:**
1. **Local audio files** - MP3/WAV files in `/var/lib/asterisk/moh/`
2. **Icecast streams** - Internet radio streams (MP3/OGG)
3. **Shoutcast streams** - Traditional streaming servers
4. **Custom applications** - mpg123 with sox for processing

**MOH Classes Available:**
- `default` - Local files, random playback
- `stream-volume-quiet` - 50% volume streaming
- `stream-volume-normal` - 70% volume streaming
- `stream-volume-loud` - 80% volume streaming
- `stream-volume-full` - 100% volume streaming
- `icecast-soma-fm` - Example Soma FM stream at 70% volume
- `support-queue` - Dedicated for support queue
- `sales-queue` - Dedicated for sales queue

**Volume Control:**
Uses sox to adjust volume during streaming:
```bash
mpg123 -q -r 8000 --mono -s -@ | sox -t raw -r 8000 -c 1 -e signed -b 16 - -t raw -r 8000 -c 1 -e signed -b 16 - vol 0.7
```

**Web Interface:** `/home/flexpbxuser/public_html/admin/moh-manager.html`
- Add/edit stream URLs
- Adjust volume (0-100%)
- Test playback
- Assign to queues
- Upload local files
- Reload configuration

---

### 3. Audio Upload Auto-Conversion 

**Admin Interface:** `/home/flexpbxuser/public_html/admin/audio-upload.php`
**User Interface:** `/home/flexpbxuser/public_html/user-portal/my-recordings.php`

**Automatic Processing:**
1. Upload any audio format (MP3, WAV, OGG, etc.)
2. Converts to Asterisk-optimized format:
   - 8kHz sample rate
   - Mono channel
   - 16-bit depth
   - -3dB normalization
3. Creates ulaw format automatically
4. Sets proper ownership (asterisk:asterisk)
5. Sets proper permissions (644)
6. Deploys to correct directory

**Categories Supported:**
- IVR Prompts - `/var/lib/asterisk/sounds/custom/`
- Queue Announcements - `/var/lib/asterisk/sounds/`
- Voicemail Greetings - `/var/spool/asterisk/voicemail/{context}/{mailbox}/`
- Music on Hold - `/var/lib/asterisk/moh/`

**Technical Details:**
```bash
sox input.wav -r 8000 -c 1 -b 16 output.wav norm -3
sox output.wav -r 8000 -c 1 -t ul output.ulaw
```

---

### 4. Asterisk API Integration Documentation 

**Location:** `/home/flexpbxuser/public_html/api/ASTERISK_API_INTEGRATION.md`

**Documented Interfaces:**
1. **AMI (Asterisk Manager Interface)** - TCP socket on port 5038
2. **AGI (Asterisk Gateway Interface)** - Call control from dialplan
3. **ARI (Asterisk REST Interface)** - WebSocket + HTTP on port 8088/8089
4. **CLI Interface** - Shell command execution

**Features Documented:**
- Call control (originate, hangup, transfer, park)
- Music on Hold configuration and API control
- Queue management (add/remove/pause members, status)
- Voicemail integration
- Extension/Endpoint management
- Trunk management and monitoring
- Call Detail Records (CDR) access
- Call monitoring and recording
- Audio playback applications
- Conference bridges (ConfBridge)
- Real-time event subscriptions
- Call features and pickup codes
- Security and authentication
- Database integration (AstDB and Realtime)
- WebRTC support
- System control and diagnostics
- Prometheus metrics endpoint

**Code Examples Included:**
- PHP AMI Manager class
- JavaScript ARI client
- AGI script template
- Dialplan integration examples

---

### 5. Admin Dashboard Consolidation 

**Location:** `/home/flexpbxuser/public_html/admin/dashboard.html`

**Sections:**
1. **Media & Audio Management**
   - Audio Upload Manager
   - Media Manager
   - Music on Hold Manager (NEW)

2. **PBX Configuration**
   - Extensions Management
   - Trunks Management
   - Trunks & DIDs Manager
   - Inbound Routing
   - Google Voice Integration

3. **System Tools**
   - System Self-Check
   - Admin Client

4. **Documentation**
   - IVR Setup Guide
   - ElevenLabs Guide
   - User Portal Link

**Design:**
- Responsive grid layout
- Card-based interface
- Gradient purple theme
- Hover animations
- Badge indicators for new features

---

##  System Configuration

### Audio File Locations
```
/var/lib/asterisk/sounds/          - Custom prompts and queue audio
/var/lib/asterisk/sounds/en/       - English language prompts
/var/lib/asterisk/moh/             - Music on hold files
/usr/share/asterisk/sounds/        - System default sounds
/var/spool/asterisk/voicemail/     - Voicemail greetings
```

### Configuration Files Modified
```
/etc/asterisk/extensions.conf      - Dialplan with queue features
/etc/asterisk/musiconhold.conf     - MOH classes and streaming
/etc/asterisk/queues.conf          - Queue configuration
```

### Permissions
```
Owner: asterisk:asterisk
Audio files: 644
Directories: 755
```

---

##  Queue System Details

**Queue Name:** `support`

**Members:** Dynamic (agents login/logout via \*45/\*46)

**Strategy:** ringall (can be changed in queues.conf)

**Features:**
- Real-time login/logout with audio confirmation
- Status checking with \*47
- Conditional audio prevents confusion
- Music on hold during wait
- Agent penalty support
- Call recording capability

**AMI Events Generated:**
- QueueMemberAdded
- QueueMemberRemoved
- QueueCallerJoin
- AgentConnect
- QueueMemberStatus

---

##  Music on Hold Technical Details

**Audio Processing Chain:**
```
Stream URL -> mpg123 -> sox (volume adjust) -> Asterisk
```

**Format Requirements:**
- Sample Rate: 8000 Hz
- Channels: 1 (mono)
- Format: slin (signed linear)
- Bit Depth: 16-bit

**Example Stream Configuration:**
```ini
[icecast-soma-fm]
mode=custom
application=/usr/bin/bash -c 'echo "http://ice1.somafm.com/groovesalad-128-mp3" | /home/linuxbrew/.linuxbrew/bin/mpg123 -q -r 8000 --mono -s -@ | sox -t raw -r 8000 -c 1 -e signed -b 16 - -t raw -r 8000 -c 1 -e signed -b 16 - vol 0.7'
format=slin
```

**Local Files Configuration:**
```ini
[default]
mode=files
directory=/var/lib/asterisk/moh
sort=random
```

---

##  Reload Commands

**Reload dialplan:**
```bash
asterisk -rx "dialplan reload"
```

**Reload music on hold:**
```bash
asterisk -rx "module reload res_musiconhold.so"
```

**Show MOH classes:**
```bash
asterisk -rx "moh show classes"
```

**Show queue members:**
```bash
asterisk -rx "queue show support"
```

**Check queue status:**
```bash
asterisk -rx "queue show"
```

---

##  Testing Procedures

### Test Queue Audio
1. Dial \*45 from any extension (2000-2003)
2. Should hear login success message
3. Verify added to queue: `asterisk -rx "queue show support"`
4. Dial \*45 again
5. Should hear "already logged in" message
6. Dial \*46
7. Should hear logout success message
8. Verify removed from queue
9. Dial \*46 again
10. Should hear "already logged out" message

### Test Music on Hold
1. Log into support queue with \*45
2. Call support queue from another extension
3. Should hear music on hold
4. Adjust volume in MOH Manager
5. Reload MOH: `asterisk -rx "module reload res_musiconhold.so"`
6. Test again with new volume

### Test Audio Upload
1. Navigate to admin/audio-upload.php
2. Upload MP3/WAV file
3. Select category (IVR/Queue/Custom)
4. Verify conversion creates ulaw file
5. Check permissions: `ls -l /var/lib/asterisk/sounds/`
6. Test playback in dialplan

---

##  System Status

**Asterisk Version:** 18.12.1
**Active Extensions:** 2000, 2001, 2002, 2003
**Active Trunks:** CallCentric (registered)
**Queues Configured:** support, sales
**MOH Classes:** 11 classes (8 streaming, 3 local files)
**Audio Files:** 50+ prompts including conditional queue audio

---

##  Security Notes

**File Permissions:**
- All audio files owned by asterisk:asterisk
- Upload scripts validate file types
- sox conversion sanitizes audio format
- No shell injection vulnerabilities in upload paths

**Network Security:**
- AMI port 5038 should be firewalled (internal only)
- ARI port 8088/8089 behind authentication
- Streaming MOH uses HTTPS when available

---

##  Future Enhancements

**Potential Additions:**
1. Multiple queue support (sales, support, billing)
2. Queue priority and penalty management UI
3. Real-time queue dashboard with AMI events
4. Call recording download interface
5. IVR builder with drag-and-drop
6. Conference bridge management
7. WebRTC softphone integration
8. Mobile app for queue login/logout
9. Queue statistics and reporting
10. Wallboard display for queue metrics

---

##  Documentation References

**Internal Docs:**
- `/home/flexpbxuser/public_html/api/ASTERISK_API_INTEGRATION.md`
- `/etc/asterisk/extensions.conf` - Dialplan
- `/etc/asterisk/musiconhold.conf` - MOH configuration
- `/etc/asterisk/queues.conf` - Queue settings

**External Resources:**
- Asterisk Documentation: https://docs.asterisk.org/
- AMI Reference: https://docs.asterisk.org/Asterisk_18_Documentation/API_Documentation/AMI_Actions/
- ARI Reference: https://docs.asterisk.org/Asterisk_18_Documentation/API_Documentation/Asterisk_REST_Interface/

---

**Maintained by:** FlexPBX Development Team
**Last Updated:** October 14, 2025
**Version:** 1.0