AI Profiles Module Documentation
Table of Contents
- Module Overview (Technical)
- Module Overview (Commercial/Business)
- Module Overview (End User/Administrator)
- Configuration Sections
- Settings Reference
- Common Scenarios & Examples
- Limitations & Important Notes
- Troubleshooting Tips
- Glossary
---
1. Module Overview (Technical)
What Are AI Profiles?
AI Profiles is an AI configuration module that defines how AI services behave in the PBX system. Each profile configures the AI provider, model settings, voice parameters, and behavior for features like TTS, transcription, and intelligent assistants.
Architecture
┌─────────────────────────────────────────────────────────────────┐
│ AI Profiles Architecture │
├─────────────────────────────────────────────────────────────────┤
│ │
│ AI Profile: Customer Service │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ API Connection: │ │
│ │ ├─ Provider: OpenAI │ │
│ │ └─ Model: GPT-4o │ │
│ │ │ │
│ │ Model Behavior: │ │
│ │ ├─ Temperature: 0.7 (creative) │ │
│ │ ├─ Max Tokens: 2000 │ │
│ │ └─ Embeddings: text-embedding-3-small │ │
│ │ │ │
│ │ Voice Settings: │ │
│ │ ├─ Voice Engine: OpenAI TTS │ │
│ │ ├─ Voice: Alloy │ │
│ │ ├─ Pitch: Medium │ │
│ │ ├─ Volume: Medium │ │
│ │ └─ Speech Rate: Normal │ │
│ │ │ │
│ │ System Prompt: "You are a helpful customer service..." │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ Referenced by AI Features │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ Recording TTS ──────────► Profile: Studio Voice │ │
│ │ AI Assistant ───────────► Profile: Customer Service │ │
│ │ Voicemail Summary ──────► Profile: Analysis │ │
│ │ IVR Agent ──────────────► Profile: IVR Bot │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Key Tables
| Table | Purpose |
|---|
public.ai_profiles | Profile configurations |
Key Files
| File | Description |
|---|
modules/aiProfiles/ | Frontend module |
2. Module Overview (Commercial/Business)
Business Value
AI Profiles provides customized AI behavior:
| Without Profiles | With Profiles |
|---|
| Single AI config | Multiple personalities | |
| Fixed voice | Customizable TTS | |
| No tuning | Temperature, tokens | |
| One-size-fits-all | Task-specific AI |
Use Cases
- Customer Service Bot
- Friendly, helpful tone
- Moderate creativity
- Professional Announcements
- Clear, formal voice
- Low creativity (consistent)
- Call Transcription
- Accurate model
- Fast processing
- IVR Assistant
- Natural voice
- Specific system prompt
Feature Highlights
| Feature | Benefit |
|---|
| Multiple Profiles | Different use cases | |
| Voice Customization | Pitch, rate, volume | |
| Temperature Control | Creativity level | |
| System Prompts | Define AI behavior | |
| TTS Testing | Preview voices | |
| Embeddings | Semantic search |
3. Module Overview (End User/Administrator)
What Can You Do?
- Create AI profiles for different purposes
- Select providers and models
- Configure temperature and tokens
- Choose TTS voice and settings
- Write system prompts
- Test voice generation
- Adjust pitch, volume, rate
AI Profiles - List View
┌─────────────────────────────────────────────────────────────────┐
│ AI Profiles │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Configure AI integration settings, voice profiles, and │
│ intelligent assistants │
│ │
│ [+ Add] │
│ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ Name │ Provider │ Model │ Voice │ Status│ │
│ ├──────────────────┼──────────┼─────────┼──────────┼───────┤ │
│ │ Customer Service │ OpenAI │ GPT-4o │ Alloy │ Active│ │
│ │ Studio Voice │ OpenAI │ - │ Nova │ Active│ │
│ │ Analysis │ Anthropic│ Claude 3│ - │ Active│ │
│ │ IVR Bot │ OpenAI │ GPT-4 │ Shimmer │ Active│ │
│ └───────────────────────────────────────────────────────────┘ │
│ │
│ Actions: [🧪 Test] [✏️ Edit] [🗑️ Delete] │
│ │
└─────────────────────────────────────────────────────────────────┘
Add/Edit AI Profile
┌─────────────────────────────────────────────────────────────────┐
│ Edit AI Profile │
├─────────────────────────────────────────────────────────────────┤
│ │
│ [API Connection] [Model Config] [Voice Settings] [System] │
│ │
│ ▼ API Connection │
│ │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ ││
│ │ Profile Name: [Customer Service ] ││
│ │ Unique identifier for this AI profile ││
│ │ ││
│ │ Provider: [OpenAI ▼] ││
│ │ OpenAI | Anthropic | Google | Hugging Face | Local ││
│ │ ││
│ │ Model: [GPT-4o ▼] ││
│ │ Default AI model for reasoning and responses ││
│ │ ││
│ │ [Test Connection] ││
│ │ ││
│ └─────────────────────────────────────────────────────────────┘│
│ │
│ ▼ Model Behavior │
│ │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ ││
│ │ Temperature: [0.7 ] (0.0 - 1.0) ││
│ │ Lower = focused, Higher = creative ││
│ │ ││
│ │ Max Tokens: [2000 ] (500 - 8000) ││
│ │ Maximum response length ││
│ │ ││
│ │ Embeddings Model: [text-embedding-3-small ▼] ││
│ │ Model for semantic search and indexing ││
│ │ ││
│ └─────────────────────────────────────────────────────────────┘│
│ │
│ ▼ System Settings │
│ │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ ││
│ │ Timeout (ms): [30000 ] (1000 - 60000) ││
│ │ ││
│ │ Retry Attempts: [3 ] (0 - 5) ││
│ │ ││
│ │ Status: ✓ Enabled ││
│ │ ││
│ └─────────────────────────────────────────────────────────────┘│
│ │
│ [Save] [Cancel] │
│ │
└─────────────────────────────────────────────────────────────────┘
Voice Settings Tab
┌─────────────────────────────────────────────────────────────────┐
│ Edit AI Profile - Voice Settings │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ▼ Voice Selection │
│ │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ ││
│ │ Voice Engine: [OpenAI TTS ▼] ││
│ │ OpenAI TTS | ElevenLabs | AWS Polly | Google TTS ││
│ │ ││
│ │ Voice: [🔍 Search voices... ] ││
│ │ Alloy | Echo | Fable | Nova | Onyx | Shimmer ││
│ │ ││
│ │ ─── Google TTS Selection (if Google TTS selected) ─── ││
│ │ Language: [🔍 Search language... ] ││
│ │ Spanish | English | French | Portuguese | German... ││
│ │ Accent: [Spain ▼] ││
│ │ Spain | Mexico | US | Argentina... ││
│ │ Voice: [🔍 Enceladus ▼] ││
│ │ Chirp D - Female | Chirp E - Male | Enceladus - Female ││
│ │ Style: [Natural ▼] ││
│ │ Natural | Alegre | Triste | Susurrar | Storyteller ││
│ │ ││
│ └─────────────────────────────────────────────────────────────┘│
│ │
│ ▼ Voice Configuration │
│ │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ ││
│ │ Pitch: [Medium ▼] ││
│ │ Very Low | Low | Medium | High | Very High ││
│ │ ││
│ │ Volume: [Medium ▼] ││
│ │ Silent | Very Soft | Soft | Medium | Loud | Very Loud ││
│ │ ││
│ │ Speech Rate: [Medium ▼] ││
│ │ Very Slow | Slow | Medium | Fast | Very Fast ││
│ │ ││
│ └─────────────────────────────────────────────────────────────┘│
│ │
│ ▼ Test Voice │
│ │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ ││
│ │ Text to convert: [Hello, welcome to our service ] ││
│ │ ││
│ │ [Generate] [🔊 Play] ││
│ │ ││
│ │ [Download Production] ││
│ │ ││
│ └─────────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────────┘
System Prompt Tab
┌─────────────────────────────────────────────────────────────────┐
│ Edit AI Profile - System Settings │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ▼ System Prompt │
│ │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ ││
│ │ System Prompt: ││
│ │ ┌─────────────────────────────────────────────────────┐ ││
│ │ │ You are a helpful customer service assistant for │ ││
│ │ │ a telecommunications company. Be friendly, concise,│ ││
│ │ │ and helpful. Guide users to solutions efficiently. │ ││
│ │ │ │ ││
│ │ │ Key behaviors: │ ││
│ │ │ - Greet customers warmly │ ││
│ │ │ - Understand their needs quickly │ ││
│ │ │ - Provide clear, step-by-step help │ ││
│ │ │ - Offer to transfer to human agent if needed │ ││
│ │ └─────────────────────────────────────────────────────┘ ││
│ │ Instructions that define how the AI should behave ││
│ │ ││
│ └─────────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────────┘
Quick Tips
TIP
Temperature: Use 0.3 for accuracy, 0.7+ for creativity.
TIP
Test Voice: Always preview before using in production.
NOTE
System Prompt: Define AI personality and behavior.
---
4. Configuration Sections
API Connection
| Field | Description |
|---|
| Profile Name | Unique identifier | |
| Provider | AI service (OpenAI, etc.) | |
| Model | LLM model to use |
Model Behavior
| Field | Description |
|---|
| Temperature | Creativity (0.0-1.0) | |
| Max Tokens | Response length limit | |
| Embeddings Model | For semantic search |
Voice Settings
| Field | Description |
|---|
| Voice Engine | TTS provider | |
| Voice | Voice selection | |
| Pitch | Voice pitch level | |
| Volume | Output volume | |
| Speech Rate | Speaking speed |
System Settings
| Field | Description |
|---|
| Timeout | API response timeout | |
| Retry Attempts | Retry on failure | |
| Status | Enable/disable | |
| System Prompt | AI behavior instructions |
5. Settings Reference
Providers
| Provider | Models | Voice Engines |
|---|
| OpenAI | GPT-4o, GPT-4 Turbo | OpenAI TTS | |
| Anthropic | Claude 3 Opus | - | |
| Google | Gemini | Google TTS | |
| Local | Local LLM | Local TTS |
Temperature Guide
| Value | Behavior | Use Case |
|---|
| 0.0-0.3 | Focused, consistent | Transcription, facts | |
| 0.4-0.6 | Balanced | General assistance | |
| 0.7-1.0 | Creative, varied | Creative content |
Voice Engines
| Engine | Provider | Features |
|---|
| OpenAI TTS | OpenAI | High quality, fast | |
| ElevenLabs | ElevenLabs | Voice cloning | |
| AWS Polly | Amazon | Neural voices | |
| Google TTS | Google | 300+ voices, cascading selection, emotion styles |
Google TTS Selection Hierarchy
Google TTS uses a 4-stage cascading selection to manage 300+ voice options:
| Stage | Description | Example |
|---|
| Language | Base language | Spanish, English | |
| Accent | Regional variant | Spain, Mexico, US | |
| Voice | Technical variant with persona | Enceladus, Chirp D | |
| Style | Emotional tone | Natural, Alegre, Triste |
Google TTS Voice Types
| Type | Quality | Cost | Use Case |
|---|
| Standard | Basic | Low | Testing, drafts | |
| Wavenet | High | Medium | Production | |
| Neural2 | Premium | High | Professional | |
| Chirp3-HD | Ultra | Premium | Studio quality |
Google TTS Prosody Controls
| Control | Range | Default | Effect |
|---|
| Speed | 0.25x - 4.0x | 1.0x | Speaking rate | |
| Pitch | -20 to +20 semitones | 0 | Voice tone | |
| Volume | -10 to +10 dB | 0 dB | Output level |
Pitch Levels
| Level | Value | Effect |
|---|
| Very Low | -50% | Deep voice | |
| Low | -25% | Slightly lower | |
| Medium | 0% | Normal | |
| High | +25% | Slightly higher | |
| Very High | +50% | High pitched |
Speech Rate Levels
| Level | Speed | Use Case |
|---|
| Very Slow | 0.5x | Clear dictation | |
| Slow | 0.75x | Instructions | |
| Medium | 1.0x | Normal | |
| Fast | 1.5x | Quick info | |
| Very Fast | 2.0x | Rapid playback |
6. Common Scenarios & Examples
Scenario 1: Create Customer Service Profile
- Add Profile
- Name = "Customer Service"
- Provider = OpenAI
- Model = GPT-4o
- Temperature = 0.7
- Max Tokens = 2000
- Voice Engine = OpenAI TTS
- Voice = Alloy
- System Prompt = "You are a helpful..."
- Save
Scenario 2: Studio Voice Profile
- Add Profile
- Name = "Studio Voice"
- Voice Engine = ElevenLabs
- Voice = (select professional voice)
- Pitch = Medium
- Rate = Slow
- Test Voice
- Save
Scenario 3: Analysis Profile
- Add Profile
- Name = "Analysis"
- Provider = Anthropic
- Model = Claude 3 Opus
- Temperature = 0.3 (accurate)
- Max Tokens = 4000
- (No voice settings needed)
- Save
Scenario 4: IVR Bot Profile
- Add Profile
- Name = "IVR Bot"
- Provider = OpenAI
- Model = GPT-4o
- Temperature = 0.5
- Voice = Nova
- Rate = Medium
- System Prompt = "You are an IVR assistant..."
- Test Voice with sample greeting
- Save
Scenario 5: Google TTS Profile (Spanish)
- Add Profile
- Name = "Spanish Voice"
- Provider = Google
- Voice Engine = Google TTS
- Language = Spanish
- Accent = Spain (or Mexico, US, etc.)
- Voice = Enceladus (or select from Chirp, Wavenet, Neural2)
- Style = Natural (or Alegre for friendly, Triste for empathetic)
- Adjust Speed, Pitch, Volume as needed
- Enter test text and click "Convert to Audio"
- Preview, then Save
---
7. Limitations & Important Notes
Technical Notes
NOTE
Provider Required: Must select a provider from AI Providers first.
NOTE
Voice Testing: Uses API credits for TTS generation.
WARNING
System Prompt: Keep concise for faster responses.
Best Practices
- Use Profiles for Purposes: Don't reuse same profile for everything
- Test Voice Settings: Preview before production
- Tune Temperature: Match to use case
- Write Clear Prompts: Specific instructions work best
- Monitor Usage: API calls cost money
Profile Use Cases
| Profile Type | Temperature | Voice | Example |
|---|
| Customer Service | 0.6-0.7 | Friendly | Alloy, Nova | |
| Announcements | 0.2-0.3 | Professional | Onyx | |
| Analysis | 0.1-0.3 | None | - | |
| Creative | 0.7-1.0 | Varied | - |
8. Troubleshooting Tips
Common Issues
| Symptom | Possible Cause | Solution |
|---|
| Connection failed | Wrong provider | Check AI Providers | |
| Voice won't play | Audio blocked | Check browser | |
| Slow responses | Low timeout | Increase timeout | |
| Generic answers | Vague prompt | Improve system prompt |
Test Connection
# Test API manually
curl https://api.openai.com/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello"}]}'
Debug Voice
- Click Test Voice
- Enter sample text
- Click Generate
- Check for error messages
- Verify voice is selected
- Check audio playback
---
9. Glossary
| Term | Definition |
|---|
| Temperature | AI creativity control | |
| Max Tokens | Response length limit | |
| TTS | Text-to-Speech | |
| Embeddings | Vector representations | |
| System Prompt | AI behavior instructions | |
| Voice Engine | TTS service provider |
Lua Script Status ℹ️
Integration Module
| Component | Status |
|---|
| AI Profiles | ℹ️ AI configuration - no Lua handler required |
---
Documentation last updated: January 2026
