Queue Profiles Module Documentation

Module Overview (Technical)
Module Overview (Commercial/Business)
Module Overview (End User/Administrator)
Configuration Tabs
Settings Reference
Common Scenarios & Examples
Limitations & Important Notes
Troubleshooting Tips
Glossary

---

1. Module Overview (Technical)

What Are Queue Profiles?

Queue Profiles are call center configuration templates that define how queues handle calls, route to agents, manage tiers, and control caller experience. They are assigned to queues in the Queues module.

Architecture

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                Queue Profiles Architecture                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Admin Panel                                                    │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        Queue Profiles                                    │   │
│  │                                                          │   │
│  │  Tabs:                                                   │   │
│  │  ├─ General (max wait, no answer, queue size)           │   │
│  │  ├─ Caller Experience (sounds, announcements)           │   │
│  │  ├─ Tier Rules (escalation, wait times)                 │   │
│  │  └─ Advanced (debug, agent cooldown)                    │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ Assigned to queues                                     │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        Queues Module                                     │   │
│  │                                                          │   │
│  │  Sales Queue → Profile: aggressive-routing              │   │
│  │  Support Queue → Profile: tiered-escalation             │   │
│  │  VIP Queue → Profile: immediate-connect                 │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ Applied by queue handler                               │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        Queue Lua Handler                                 │   │
│  │                                                          │   │
│  │  Load profile settings → Apply to call                   │   │
│  │  ├─ Tier rule wait times                                │   │
│  │  ├─ Agent routing logic                                 │   │
│  │  ├─ Announcements and sounds                            │   │
│  │  └─ Timeout and delay settings                          │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

Table	Purpose
`public.queue_profiles`	Profile definitions and settings

Key Files

File	Description
`modules/queueProfiles/`	Frontend module

---

2. Module Overview (Commercial/Business)

Business Value

Queue Profiles provides customized call center behavior:

Without Profiles	With Profiles
Default handling	Custom routing
One-size-fits-all	Different strategies
Fixed escalation	Tiered escalation
No announcements	Full caller experience

Use Cases

Tiered Escalation

- Wait times per tier

- Automatic escalation

Caller Experience

- Position announcements

- Estimated wait time

Agent Optimization

- Skip busy agents

- Cooldown periods

High-Priority Queues

- Immediate routing

- VIP handling

Feature Highlights

Feature	Benefit
Tier Rules	Escalation control
Announcements	Caller experience
Agent Cooldown	Prevent burnout
Max Queue Size	Capacity control
Progressive Ring	Ring more agents
Whisper Tone	Agent notification

---

3. Module Overview (End User/Administrator)

What Can You Do?

Create queue profile templates
Configure tier escalation rules
Set caller announcements
Configure agent timeouts
Set queue capacity limits
Enable position/wait time announcements
Configure progressive ringing

Queue Profiles Interface

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              Queue Profiles                                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Manage queue profile configurations for call center queues    │
│                                                                 │
│  [+ Create Profile]                                             │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ Name               │ Description         │ Status       │  │
│  ├────────────────────┼─────────────────────┼──────────────┤  │
│  │ default            │ Standard queues     │ ✓ Enabled    │  │
│  │ tiered-escalation  │ Multi-tier routing  │ ✓ Enabled    │  │
│  │ aggressive         │ Fast routing        │ ✓ Enabled    │  │
│  │ vip-priority       │ VIP customers       │ ✓ Enabled    │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Profile Edit View

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              Edit Queue Profile                                 │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  [General] [Caller Experience] [Tier Rules] [Advanced]         │
│  ─────────────────────────────────────────────────────────────  │
│                                                                 │
│  General Settings                                               │
│                                                                 │
│  Queue Profile Name: [tiered-escalation         ]              │
│                                                                 │
│  Max Wait Agents: [5                ]                          │
│    Maximum number of agents waiting in queue                    │
│                                                                 │
│  Max No Answer: [3                ]                            │
│    Maximum unanswered calls before agent skip                   │
│                                                                 │
│  Queue Max Size: [50               ]                           │
│    Maximum callers in queue (0 = unlimited)                     │
│                                                                 │
│  Agent No-Answer Delay: [10              ]                     │
│    Delay before considering agent unavailable                   │
│                                                                 │
│  Member Delay: [2                ]                             │
│    Delay before ringing member                                  │
│                                                                 │
│  Member Timeout: [30               ]                           │
│    Timeout for member to answer                                 │
│                                                                 │
│  [Save] [Cancel]                                                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Tips

TIP

Tier Rules: Enable for complex escalation scenarios.

TIP

Agent Cooldown: Give agents time between calls.

NOTE

Profile Assignment: Profiles are assigned in Queues module.

---

4. Configuration Tabs

General Tab

Field	Description
Queue Profile Name	Unique identifier
Max Wait Agents	Agent limit in queue
Max No Answer	Unanswered calls before skip
Queue Max Size	Caller capacity limit
Agent No-Answer Delay	Time before unavailable
Member Delay	Pre-ring delay
Member Timeout	Answer timeout

Caller Experience Tab

Field	Description
Announce Hold Time	Tell caller wait time
Announce Position	Tell caller queue position
Announce Estimated Hold Time	Estimated wait announcement
Welcome Sound	Played on queue entry
Exit Sound	Played on queue exit
Ringback Tone	Tone while waiting
Agent Whisper Tone	Agent notification sound
Play Ringback Before MOH	Ringback then music
Announce Wrap-up Message	Post-call message
Announce Resume Playback	Resume after announcement

Tier Rules Tab

Field	Description
Tier Rules Apply	Enable tier escalation
Tier Rule Wait	Seconds per tier
Tier Rule Wait Multiply Level	Multiply wait by tier level
Tier Rule No Agent No Wait	Skip empty tiers
Tier Rule Max Wait	Maximum tier wait
Tier Skip Busy Agents	Skip busy agents
Tier Randomize Agents	Random agent selection
Tier No Wait	Immediate tier skip
Tier Wait Stop Sound	Sound between tiers
Reserve Agents	Reserve selected agents

Advanced Tab

Field	Description
Skip Agents With Active Call	Skip busy agents
Agent Cooldown Time	Rest time between calls
Agent Busy Delay	Delay when busy
Agent Reject Delay	Delay after rejection
Strict Retry	Strict retry logic
Ring Progressively	Add agents over time
Log Debug Info	Enable debug logging
Truncate Agents on Load	Clear agents on reload

---

5. Settings Reference

Common Profile Types

Profile	Settings
Default	Standard settings
Aggressive	Short timeouts, fast escalation
Tiered	Multi-tier with wait times
VIP	Immediate routing, short waits

Tier Rule Logic

Plaintext

Tier 1: Wait tier_rule_wait seconds
    ↓ (no answer)
Tier 2: Wait tier_rule_wait × 2 seconds (if multiply enabled)
    ↓ (no answer)
Tier 3: Wait tier_rule_wait × 3 seconds
    ↓ (max wait reached)
Exit to destination

Timing Recommendations

Setting	Typical Value
Member Timeout	20-30 seconds
Agent No-Answer Delay	5-10 seconds
Tier Rule Wait	30-60 seconds
Agent Cooldown	5-15 seconds

---

6. Common Scenarios & Examples

Scenario 1: Basic Queue Profile

Create new profile
Set Max No Answer = 3
Set Member Timeout = 30
Enable Announce Position
Save

Scenario 2: Tiered Escalation

Create new profile
Enable Tier Rules Apply
Set Tier Rule Wait = 60 seconds
Enable Tier Rule Wait Multiply Level
Set Tier Rule No Agent No Wait = Yes
Save

Scenario 3: VIP Priority

Create new profile
Set Member Delay = 0
Set Member Timeout = 15
Set Tier Rule Wait = 15
Enable Announce Estimated Hold Time
Save

Scenario 4: Agent-Friendly

Create new profile
Set Agent Cooldown Time = 10
Set Max No Answer = 2
Enable Skip Agents With Active Call
Save

---

7. Limitations & Important Notes

Technical Notes

NOTE

Profile Assignment: Profiles are assigned in Queues module.

NOTE

Tier Rules: Require tiers to be configured in queue.

WARNING

High Thresholds: Very high member timeouts can frustrate callers.

Best Practices

Balance Wait Times: Not too long, not too short
Enable Announcements: Keep callers informed
Use Cooldowns: Prevent agent burnout
Test Tier Rules: Verify escalation works
Monitor Metrics: Adjust based on data

Tier Rule Behavior

Flag	Effect
Multiply Level	Tier 2 waits 2x, Tier 3 waits 3x
No Agent No Wait	Skip tiers with no agents
Skip Busy Agents	Don't offer to busy agents
Randomize Agents	Random within tier

---

8. Troubleshooting Tips

Common Issues

Symptom	Possible Cause	Solution
Calls not escalating	Tier rules disabled	Enable Tier Rules Apply
Agent overloaded	No cooldown	Set Agent Cooldown Time
Queue full	Max size reached	Increase Queue Max Size
Long wait times	Slow escalation	Reduce Tier Rule Wait
No announcements	Not enabled	Enable Announce Position

Check Profile Settings

Sql

SELECT 
  name,
  settings
FROM public.queue_profiles
WHERE name = 'profile-name';

Debug Tier Escalation

Enable Log Debug Info
Monitor FreeSWITCH logs
Check tier transitions
Verify agent availability

---

9. Glossary

Term	Definition
Queue Profile	Queue behavior template
Tier	Agent priority level
Tier Rule Wait	Time per tier level
Escalation	Moving to next tier
Cooldown	Rest time between calls
Member Timeout	Agent ring time
Whisper Tone	Agent notification

---

Lua Script Status ℹ️

Configuration Module

Component	Status
Queue Profiles	ℹ️ Configuration module - settings applied by queue Lua handler

Queue Profiles is a configuration module. Settings are stored and loaded by the queue Lua handler when processing queue calls.

---

Documentation last updated: January 2026

Queue Profiles Module Documentation

Table of Contents

1. Module Overview (Technical)

What Are Queue Profiles?

Architecture

Key Tables

Key Files

2. Module Overview (Commercial/Business)

Business Value

Use Cases

Feature Highlights

3. Module Overview (End User/Administrator)

What Can You Do?

Queue Profiles Interface

Profile Edit View

Quick Tips

4. Configuration Tabs

General Tab

Caller Experience Tab

Tier Rules Tab

Advanced Tab

5. Settings Reference

Common Profile Types

Tier Rule Logic

Timing Recommendations

6. Common Scenarios & Examples

Scenario 1: Basic Queue Profile

Scenario 2: Tiered Escalation

Scenario 3: VIP Priority

Scenario 4: Agent-Friendly

7. Limitations & Important Notes

Technical Notes

Best Practices

Tier Rule Behavior

8. Troubleshooting Tips

Common Issues

Check Profile Settings

Debug Tier Escalation

9. Glossary

Lua Script Status ℹ️

Configuration Module