--- title: "PBX Voice Guide Module Documentation" description: "Documentation for PBX Voice Guide" --- ## Table of Contents 1. [Navigation & Access](#navigation--access) 2. [Screenshots & Visual Interface](#screenshots--visual-interface) 3. [Module Overview (Technical)](#1-module-overview-technical) 4. [Module Overview (Commercial/Business)](#2-module-overview-commercialbusiness) 5. [Module Overview (End User/Administrator)](#3-module-overview-end-useradministrator) 6. [User Roles & Key Capabilities](#-user-roles--key-capabilities) 7. [Interface Features](#4-interface-features) 8. [Voice Guide Generation](#5-voice-guide-generation) 9. [Model Context Protocol (MCP) AI Integration](#model-context-protocol-mcp-ai-integration) 10. [Common Scenarios & Examples](#6-common-scenarios--examples) 11. [Limitations & Important Notes](#7-limitations--important-notes) 12. [Troubleshooting Tips](#8-troubleshooting-tips) 13. [Glossary](#9-glossary) --- ## Navigation & Access To access the PBX Voice Guide configuration module: 1. Log in to the Ring2All Web Portal (`https:///login`). 2. In the left navigation sidebar, expand **Settings**. 3. Under **Voice Prompts**, click **PBX Voice Guide** (`/settings/voice-prompts/pbx-guide`). 4. To register or generate a new system voice prompt pack, click **+ Add Voice Guide**. To preview or edit an existing voice guide, click on the row or the **Edit** action button. --- ## Screenshots & Visual Interface ### PBX Voice Guide Catalog & Inventory Interactive directory of Telephony Server telephony prompt packages, showing language code, dialect, voice persona, sound directory paths, AI TTS generator integrations, and system-wide fallback flags. ![PBX Voice Guide List](/screenshots/settings/voice/pbx-voice-guide-list.png) --- ## 1. Module Overview (Technical) ### What Is PBX Voice Guide? PBX Voice Guide is a **voice prompts management system** that allows administrators to view, create, and manage Telephony Services voice prompts. It supports both viewing existing prompt catalogs and **generating new voice guides using AI TTS (Text-to-Speech)** with OpenAI, Azure, or Google voices. ### Architecture ``` ┌─────────────────────────────────────────────────────────────────┐ │ PBX Voice Guide Architecture │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Admin Panel │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ PBX Voice Guide │ │ │ │ │ │ │ │ Catalog View: │ │ │ │ ┌───────────────────────────────────────────────────┐ │ │ │ │ │ Prompt Name │ Lang │ Voice │ Type │ Actions │ │ │ │ │ ├───────────────┼──────┼───────┼────────┼─────────┤ │ │ │ │ │ English Emma │ EN │ emma │ System │ ✏️ │ │ │ │ │ │ Spanish Paloma│ ES │ paloma│ System │ ✏️ │ │ │ │ │ │ English Maria│ EN │ maria │ Custom │ ✏️ 🗑️ │ │ │ │ │ └───────────────────────────────────────────────────┘ │ │ │ │ │ │ │ │ [+ Create Voice Guide] │ │ │ │ │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ Reads/Writes │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ Voice Prompts Storage │ │ │ │ │ │ │ │ /usr/share/freeswitch/sounds/ │ │ │ │ ├─ en/us/emma/ │ │ │ │ │ ├─ ivr/ │ │ │ │ │ ├─ voicemail/ │ │ │ │ │ └─ digits/ │ │ │ │ ├─ es/us/paloma/ │ │ │ │ └─ (custom voices) │ │ │ │ │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ AI TTS Generation │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ AI Profile Integration │ │ │ │ ┌─────────────┬─────────────┬─────────────┐ │ │ │ │ │ OpenAI │ Azure │ Google │ │ │ │ │ │ TTS-1 │ TTS │ TTS │ │ │ │ │ └─────────────┴─────────────┴─────────────┘ │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Database Schema ```sql CREATE TABLE public.voice_guides ( id SERIAL PRIMARY KEY, uuid UUID NOT NULL DEFAULT uuid_generate_v4(), name TEXT NOT NULL, description TEXT, language_code VARCHAR(2) NOT NULL, dialect_code VARCHAR(2) NOT NULL, voice_name VARCHAR(50) NOT NULL, sound_path TEXT NOT NULL, is_fallback BOOLEAN NOT NULL DEFAULT FALSE, is_system BOOLEAN NOT NULL DEFAULT FALSE, enabled BOOLEAN NOT NULL DEFAULT TRUE, created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), updated_at TIMESTAMPTZ ); ``` --- ## 2. Module Overview (Commercial/Business) ### Business Value PBX Voice Guide provides **voice prompt management and AI generation**: | Without Voice Guide | With Voice Guide | |---------------------|------------------| | Manual file creation | AI-powered generation | | SSH to upload files | Web-based management | | No inventory tracking | Complete catalog view | | Limited languages | Unlimited AI voices | | Manual discovery | Filtered search | ### Use Cases 1. **Custom Voice Prompts** - Generate AI voice prompts in any language - Use OpenAI, Azure, or Google TTS 2. **Language Expansion** - Add new language support - Create regional dialects 3. **Brand Voice** - Create custom voice identities - Consistent voice across IVR, voicemail, etc. 4. **Rapid Deployment** - Bulk generate prompts from CSV - Batch processing with progress tracking ### Feature Highlights | Feature | Benefit | |---------|---------| | **AI TTS Generation** | Create prompts using AI voices | | **Batch Processing** | Generate multiple prompts at once | | **Progress Tracking** | Real-time progress bar with count | | **CSV Import** | Bulk prompt definition | | **System Protection** | System guides cannot be deleted | | **Edit Mode** | Add prompts to existing guides | | **Fallback Config** | Identify fallback voices | --- ## 3. Module Overview (End User/Administrator) ### What Can You Do? - **View** all available voice guides - **Create** new voice guides with AI TTS - **Edit** existing guides (add more prompts) - **Delete** custom voice guides (system guides protected) - **Filter** by language, status, type - **Search** for specific guides - **Track** generation progress in real-time ### Voice Guide List Interface ``` ┌─────────────────────────────────────────────────────────────────┐ │ PBX Voice Guide │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ [🔍 Search by name, language, dialect or voice...] │ │ │ │ [+ Create Voice Guide] [🔄 Refresh] │ │ │ │ ┌───────────────────────────────────────────────────────────┐ │ │ │ Prompt Name │ Lang │ Voice │ Type │ Status│Actions│ │ │ ├─────────────────┼──────┼─────────┼────────┼───────┼───────┤ │ │ │ English Emma │ EN │ Emma │ System │Enabled│ ✏️ │ │ │ │ Spanish Paloma │ ES │ Paloma │ System │Enabled│ ✏️ │ │ │ │ English Maria │ EN │ Maria │ Custom │Enabled│ ✏️ 🗑 │ │ │ └───────────────────────────────────────────────────────────┘ │ │ │ │ Showing 3 voice guides │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Voice Guide Types | Type | Badge Color | Deletable | Description | |------|-------------|-----------|-------------| | **System** | Blue | ❌ No | Pre-installed, protected guides | | **Custom** | Green | ✅ Yes | User-created guides | ### Quick Tips > [!TIP] > **Edit Mode**: Click the edit icon on any guide to add more prompts to it. > [!TIP] > **CSV Format**: Use `path,filename,text` format for bulk prompt definition. --- ## 🎯 User Roles & Key Capabilities | Role | Key Capabilities & Permissions | Operational Scope | | :--- | :--- | :--- | | **PBX Super Administrator** | • Global catalog audit across all languages, dialects, and sound paths
• System voice guide protection flag (`is_system`) enforcement
• Fallback voice guide designation and Telephony Server sound directory root path configuration
• AI TTS profile configuration and batch token rate limit orchestration | Full Platform Scope | | **Tenant Administrator** | • Custom domain voice guide creation and prompt review
• Multilingual audio prompt batch generation via AI voice models
• Custom phrase library management and prompt preview playback
• Domain-level prompt selection for IVRs, queues, and announcements | Domain Scope | | **Call Center Supervisor** | • Read-only inspection of active prompt packages
• Audio phrase playback verification for customer greeting compliance
• Audio guide preview and request submission for queue waiting audio | Supervised Queues | | **AI Copilot / MCP Agent** | • Automated voice guide inventory query (`list_voice_guides`)
• Diagnostic inspection of prompt paths and dialects (`get_voice_guide_status`)
• Dynamic prompt synthesis for automated IVR expansions | Autonomous Assistant | --- ## 4. Interface Features ### List Columns | Column | Description | |--------|-------------| | **Prompt Name** | Display name of the voice guide | | **Language** | ISO language code (EN, ES, FR) | | **Dialect** | Regional variant (US, UK, MX) | | **Voice Profile** | Voice name (emma, paloma) | | **Sound Path** | Telephony Server sound path | | **Type** | System (protected) or Custom | | **Status** | Enabled/Disabled | | **Actions** | Edit, Delete (custom only) | ### Filters | Filter | Options | |--------|---------| | **Language** | All, English, Spanish, etc. | | **Status** | All, Enabled, Disabled | | **Fallback Only** | Show only fallback voices | ### Type Values | Type | Description | |------|-------------| | **System** | Pre-installed, cannot be deleted | | **Custom** | User-created, can be deleted | --- ## 5. Voice Guide Generation ### Create Voice Guide Form ``` ┌─────────────────────────────────────────────────────────────────┐ │ 🔊 Create Voice Guide │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ ┌─ Configuration ─────────────────────────────────────────┐ │ │ │ Name: [English Custom Voice ] │ │ │ │ Description: [Custom IVR prompts for... ] (optional)│ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ │ ┌─ Language & Voice ──────────────────────────────────────┐ │ │ │ Language: [English ▼] Dialect: [US ▼] │ │ │ │ Voice Name: [custom_voice ] │ │ │ │ TTS Profile: [OpenAI TTS-1 HD - alloy ▼] │ │ │ │ │ │ │ │ 📁 Output Path: en/us/custom_voice/ │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ │ ┌─ Prompt Definitions ────────────────────────────────────┐ │ │ │ CSV Content (path,filename,text): │ │ │ │ ┌─────────────────────────────────────────────────────┐│ │ │ │ │ ivr,welcome,Welcome to our company ││ │ │ │ │ ivr,goodbye,Thank you for calling ││ │ │ │ │ voicemail,greeting,Please leave a message ││ │ │ │ └─────────────────────────────────────────────────────┘│ │ │ │ [📁 Upload CSV File] or paste directly │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ │ ┌─ Prompts Preview (3 items) ─────────────────────────────┐ │ │ │ Path │ Filename │ Text │ Status │ │ │ │ ivr │ welcome │ Welcome to our company │ ⏳ │ │ │ │ ivr │ goodbye │ Thank you for calling │ ⏳ │ │ │ │ voicemail │ greeting │ Please leave a message │ ⏳ │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ ├─────────────────────────────────────────────────────────────────┤ │ [Stop] ████████████░░░░ 2/3 (67%) [🔄 Generating...] │ └─────────────────────────────────────────────────────────────────┘ ``` ### CSV Format ```csv path,filename,text ivr,welcome,Welcome to our company. How may I help you today? ivr,goodbye,Thank you for calling. Goodbye! ivr,hold,Please hold while we connect you. voicemail,greeting,You have reached the voicemail of voicemail,instructions,Please leave a message after the beep digits,0,zero digits,1,one digits,2,two ``` ### Generation Features | Feature | Description | |---------|-------------| | **Batch Processing** | Processes prompts in batches of 10 | | **Progress Bar** | Real-time visual progress indicator | | **Count Display** | Shows "X / Y (Z%)" during generation | | **Auto-scroll** | Table scrolls to show current batch | | **Status Tracking** | Each prompt shows ⏳ pending, ✅ completed, ❌ failed | | **Stop Button** | Shows "Stop" during generation to abort batch processing | | **Cancel Button** | Restores original values in edit mode, resets form in create mode | | **Completion Modal** | Summary of generated vs failed prompts | ### Edit Mode When editing an existing voice guide: - **Language, Dialect, Voice Name** are read-only (defines the path) - Can add new prompts to the existing guide - New prompts are appended or overwrite existing files --- ## Model Context Protocol (MCP) AI Integration The **PBX Voice Guide** module exposes native Model Context Protocol (MCP) tools allowing AI Copilots, automated speech orchestration agents, and diagnostic assistants to discover, inspect, and verify telephony voice prompt packages and sound directory structures across all configured languages. ### Available MCP Telephony Tools | Tool Name | Action Type | Access Level | Description | | :--- | :--- | :--- | :--- | | `list_voice_guides` | `READ` | `Read-Only` | Lists all installed voice guide prompt suites, displaying language code, dialect, voice persona, sound directory path, and default fallback status. | | `get_voice_guide_status` | `READ` | `Read-Only` | Retrieves detailed metadata, prompt path, fallback state, and system flags of a specific multilingual voice guide by ID or name. | ### Tool Schemas & Input Parameters #### `list_voice_guides` ```json { "name": "list_voice_guides", "description": "List system Voice Guides and multilingual telephony prompt suites installed in the PBX.", "inputSchema": { "type": "object", "properties": { "search": { "type": "string", "description": "Filter voice guides by name or language code (e.g. 'Spanish', 'en-US')." } } } } ``` #### `get_voice_guide_status` ```json { "name": "get_voice_guide_status", "description": "Get configuration and prompt path details of a specific multilingual voice guide.", "inputSchema": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique numerical ID of the voice guide." }, "name": { "type": "string", "description": "Name of the voice guide (e.g. 'Spanish Mexican Standard')." } } } } ``` ### Natural Language AI Copilot Prompts #### English Prompts - *"List all installed voice guides in the PBX and show which one is designated as the system default fallback."* - *"Check the prompt directory path and status for voice guide 'Spanish Mexican Standard'."* - *"Are there any English UK voice prompt packs available for our IVR menus?"* #### Spanish Prompts - *"Lista todas las guías de voz configuradas y verifica cuál está marcada como fallback predeterminado."* - *"Muestra el estado detallado y la ruta de archivos de sonido de la guía de voz 'Spanish Paloma'."* - *"¿Qué paquetes de audio en inglés y español tenemos disponibles para el conmutador?"* ### Enterprise Safeguards & Multi-Tenant Isolation 1. **Domain Scoping**: Read operations are filtered to the authenticated tenant/domain context, preventing cross-tenant leakage of proprietary custom brand audio files. 2. **System Guide Protection**: System voice guides (`is_system = true`) are protected from automated deletion or accidental overwrite by AI agents. 3. **Audio File Integrity**: Paths returned by `get_voice_guide_status` are sanitized to prevent directory traversal outside `/usr/share/freeswitch/sounds/`. --- ## 6. Common Scenarios & Examples ### Scenario 1: Create Custom IVR Prompts 1. Click **"Create Voice Guide"** 2. Enter name: "Custom IVR English" 3. Select Language: English, Dialect: US 4. Enter Voice Name: "custom_ivr" 5. Select TTS Profile (e.g., OpenAI alloy) 6. Paste or upload CSV with prompts: ```csv ivr,main_menu,Press 1 for sales, 2 for support ivr,sales_queue,Connecting you to sales ivr,support_queue,Connecting you to support ``` 7. Click **"Generate Voice Guide"** 8. Watch progress bar fill up 9. Review completion summary ### Scenario 2: Add Prompts to Existing Guide 1. Find the voice guide in the list 2. Click the **Edit** (pencil) icon 3. Form opens with existing configuration (read-only) 4. Paste new prompts in CSV format 5. Click **"Generate Voice Guide"** 6. New prompts are added to existing directory ### Scenario 3: Identify System vs Custom Guides 1. View the **Type** column in the list 2. **Blue "System"** badge = Protected, cannot delete 3. **Green "Custom"** badge = User-created, can delete 4. System guides have no delete button in Actions ### Scenario 4: Generate Multilingual Prompts 1. Create separate voice guides for each language: - "Spanish Mexico Prompts" (es/mx/custom) - "French Canada Prompts" (fr/ca/custom) 2. Use appropriate TTS profiles for each language 3. Use same prompt structure (path/filename) for consistency --- ## 7. Limitations & Important Notes ### Technical Notes > [!NOTE] > **Audio Format**: Generated files are WAV format, 8kHz mono (telephony optimized). > [!NOTE] > **File Location**: Files are saved to `/usr/share/freeswitch/sounds/{language}/{dialect}/{voice_name}/`. > [!WARNING] > **Overwrite Behavior**: Generating a prompt with the same path/filename overwrites the existing file. > [!CAUTION] > **System Guides**: Deleting system voice guides (is_system=true) is blocked at both UI and API level. ### Best Practices 1. **Use Descriptive Names**: Name guides clearly (e.g., "Custom IVR English HD") 2. **Plan Voice Names**: Use lowercase, no spaces (e.g., "custom_ivr" not "Custom IVR") 3. **Consistent Structure**: Use same path/filename patterns across languages 4. **Test Prompts**: Generate a few prompts first before bulk generation 5. **Backup Before Overwrite**: System won't backup existing files ### Supported TTS Providers | Provider | Voices | Quality | |----------|--------|---------| | **OpenAI** | alloy, echo, fable, onyx, nova, shimmer | HD available | | **Azure** | Multiple per language | Neural voices | | **Google** | Multiple per language | Neural voices | --- ## 8. Troubleshooting Tips ### Common Issues | Symptom | Possible Cause | Solution | |---------|---------------|----------| | "Generating..." stuck | TTS API issue | Check AI Profile credentials | | Prompts fail | Invalid text or path | Check CSV format, remove special characters | | No TTS profiles | Profiles not configured | Create AI Profiles with type=TTS | | Cannot delete guide | System guide | System guides are protected | | Edit button opens empty | Guide data issue | Refresh the list | | Progress bar not moving | Batch failure | Check browser console for errors | ### Verify Generated Files ```bash # Check generated files ls -la /usr/share/freeswitch/sounds/en/us/custom_voice/ # Check specific path ls -la /usr/share/freeswitch/sounds/en/us/custom_voice/ivr/ # Verify file format file /usr/share/freeswitch/sounds/en/us/custom_voice/ivr/welcome.wav ``` ### Check Voice Guide in Database ```sql -- List all voice guides SELECT name, language_code, dialect_code, voice_name, is_system, is_fallback FROM public.voice_guides; -- Check contents of a specific guide SELECT vg.name, vgc.path, vgc.name as filename, vgc.phrase FROM public.voice_guides vg JOIN public.voice_guide_contents vgc ON vgc.voice_guide_id = vg.id WHERE vg.name = 'English Emma'; ``` --- ## 9. Glossary | Term | Definition | |------|------------| | **Voice Guide** | Collection of voice prompts with a specific language/dialect/voice | | **Dialect** | Regional language variant (US, UK, MX) | | **Voice Name** | Identifier for the voice directory (e.g., "emma", "custom_ivr") | | **TTS Profile** | AI profile configured for text-to-speech generation | | **is_system** | Flag indicating protected system voice guides | | **is_fallback** | Flag indicating the default fallback voice guide | | **Batch Processing** | Generating prompts in groups of 10 for efficiency | | **Sound Path** | Telephony Server directory path for voice files | --- *Documentation last updated: January 2026*