Queues (Call Center) Module Documentation

Module Overview (Technical)
Module Overview (Commercial/Business)
Module Overview (End User/Administrator)
Configuration Fields Reference
Queue Strategies
Tiers and Agents
Announcements & Caller Experience
Common Scenarios & Examples
Limitations & Important Notes
Troubleshooting Tips
Glossary

---

1. Module Overview (Technical)

What Are Queues?

Queues are call distribution points that hold incoming calls until agents become available. They use FreeSWITCH's mod_callcenter to manage call distribution, agent status, and real-time queue metrics.

Architecture

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                    Queue System                                 │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Caller dials Queue extension (e.g., 6000)                      │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              queue_join.lua                              │   │
│  │  - Answer call                                           │   │
│  │  - Play welcome message                                  │   │
│  │  - Announce position/wait time                           │   │
│  │  - Enable callback option (if configured)                │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │           mod_callcenter (FreeSWITCH)                    │   │
│  │                                                          │   │
│  │  Queue: Support@domain.com                               │   │
│  │  Strategy: longest-idle-agent                            │   │
│  │                                                          │   │
│  │  Waiting Callers:                                        │   │
│  │  ├─ Position 1: +1555123456 (waiting 45s)               │   │
│  │  └─ Position 2: +1555789012 (waiting 20s)               │   │
│  │                                                          │   │
│  │  Available Agents:                                       │   │
│  │  ├─ 101@domain.com (Available, idle 120s)               │   │
│  │  ├─ 102@domain.com (Available, idle 60s)                │   │
│  │  └─ 103@domain.com (On Break)                           │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼                                                         │
│  Agent answers → Call connected                                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

Table	Purpose
`public.call_center_queues`	Queue definitions
`public.call_center_agents`	Agent definitions
`public.call_center_tiers`	Agent-Queue assignments
`public.call_center_callback_profiles`	Callback configuration
`public.call_center_queue_profiles`	Shared queue settings
`ss_cc.queues`	mod_callcenter runtime state

Key Files

File	Description
`admin/apps/web/src/modules/queues/`	Frontend module
`admin/apps/web/src/i18n/en/queues.json`	Translations
`telephony/freeswitch/lua/main/xml_handlers/callcenter/queue_join.lua`	Queue entry handler
`telephony/freeswitch/lua/main/xml_handlers/routing/queue.lua`	Queue routing handler

---

2. Module Overview (Commercial/Business)

Business Value

Queues provide enterprise call center capabilities:

Without Queues	With Queues
Calls ring busy	Calls wait in order
No hold time info	Position/wait announcements
Random distribution	9 distribution strategies
No metrics	SLA tracking

Use Cases

Customer Support

- Tiered support levels

- Skill-based routing

- SLA management

Sales Teams

- Lead distribution

- Priority handling for VIPs

- Callback options

Help Desks

- Ticket-based routing

- Escalation paths

- After-hours handling

Feature Highlights

Feature	Benefit
9 Strategies	From Ring All to Least Talk Time
Position/Wait Announcements	Caller expectations
Callback Option	Reduce abandonment
VIP Lists	Priority routing
Max Wait Limits	Overflow handling
Tier System	Skill-based distribution
Recording	Quality assurance
SLA Tracking	Service level metrics

---

3. Module Overview (End User/Administrator)

What Can You Do?

Create queues with extensions
Configure distribution strategies
Set up announcements
Configure timeouts and overflow
Assign agents via Tiers
Enable callback profiles
Set VIP priority lists

Administrator Workflow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              Creating a Queue                                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Tab 1: General                                                 │
│  ├─ Queue Name: "Support"                                      │
│  ├─ Extension: 6000                                            │
│  ├─ Strategy: Longest Idle Agent                               │
│  ├─ Max Wait Time: 300 sec                                     │
│  ├─ Timeout Destination: Voicemail → 101                       │
│  └─ Enabled: ✓                                                 │
│                                                                 │
│  Tab 2: Announcements                                           │
│  ├─ Greeting: support_greeting.wav                             │
│  ├─ Music on Hold: local_stream://default                      │
│  ├─ Announce Position: ✓                                       │
│  ├─ Announce Frequency: 45 sec                                 │
│  └─ Agent Connect Sound: queue_connect.wav                     │
│                                                                 │
│  Tab 3: Advanced                                                │
│  ├─ Time Base Score: Queue                                     │
│  ├─ Wrap-Up Time: 10 sec                                       │
│  ├─ Exit Key: *                                                │
│  └─ Max Queue Size: 50                                         │
│                                                                 │
│  Tab 4: Agents and Tiers                                        │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ Agent 101 (Alice) | Level: 1 | Position: 1                │  │
│  │ Agent 102 (Bob)   | Level: 1 | Position: 2                │  │
│  │ Agent 103 (Carol) | Level: 2 | Position: 1                │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Tips

TIP

Strategy Choice: Use "Longest Idle Agent" for even distribution.

TIP

Announce Position: Reduces hang-ups during long waits.

CAUTION

No Agents = Quick Timeout: Set "Max Wait with No Agent" appropriately.

---

4. Configuration Fields Reference

General Settings

Field	Description	Example
Queue Name	Unique identifier	`Support`
Extension	Dialable number	`6000`
Strategy	Distribution method	Longest Idle Agent
Max Wait Time	Seconds before timeout	`300`
Timeout Destination	Where unans calls go	Voicemail
Queue Profile	Shared settings	(optional)
Callback Profile	Callback configuration	(optional)
VIP List	Priority callers	(optional)
Enabled	Queue active status	On/Off

Announcement Settings

Field	Description
Greeting	Welcome message audio
Music on Hold	Audio while waiting
Announce Position	Tell position in queue
Announce Hold Time	Tell estimated wait
Announce Frequency	Repeat interval (sec)
Announce Sound	Periodic message audio
Agent Connect Sound	Played to agent on connect

Advanced Settings

Field	Description	Default
Time Base Score	Queue or System	Queue
Wrap-Up Time	Post-call delay	10 sec
Exit Key	DTMF to leave queue
Max Queue Size	Max waiting callers	0 (unlimited)
Caller ID Prefix	Prefix for agents
Discard Abandoned After	Cleanup time	60 sec
Abandoned Resume	Rejoin at position	Off

---

5. Queue Strategies

Strategy Comparison

Strategy	Description	Best For
Ring All	Ring all available agents	Small teams
Longest Idle Agent	Agent idle longest	Even distribution
Round Robin	Rotate through agents	Fair rotation
Top Down	Always start at first	Priority agents
Least Talk Time	Agent with least talk	Balance workload
Least Calls	Agent with fewest calls	Balance call count
Sequentially by Agent Order	Fixed sequence	Specific order
Sequentially by Next Agent Order	Continue sequence	Continuous rotation
Random	Random selection	Load balancing

Strategy Diagrams

Plaintext

Longest Idle Agent:
─────────────────────────────────
Call comes in → Find agent idle longest → Ring that agent

Round Robin:
─────────────────────────────────
Call 1 → Agent 1
Call 2 → Agent 2
Call 3 → Agent 3
Call 4 → Agent 1 (restart)

Top Down:
─────────────────────────────────
Always try Agent 1 first
If busy → Agent 2
If busy → Agent 3

---

6. Tiers and Agents

Tier System

Tiers define which agents handle which queues with priority:

Level: Priority tier (1 = highest priority, 2 = next, etc.)
Position: Order within the same level

Plaintext

Queue: Support
├─ Tier Level 1 (Primary Agents)
│  ├─ Position 1: Alice (101)
│  └─ Position 2: Bob (102)
├─ Tier Level 2 (Secondary Agents)
│  └─ Position 1: Carol (103)
└─ Tier Level 3 (Overflow)
   └─ Position 1: Dave (104)

Tier Rules

Setting	Description
Tier Rules Apply	Enable tier escalation
Tier Rule Wait	Seconds before tier escalation
Tier Rule Multiply Level	Multiply wait by level
Tier Rule No Agent No Wait	Skip wait if no agents at tier

---

7. Announcements & Caller Experience

Announcement Flow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              Caller Experience                                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. Greeting (once, on entry)                                   │
│     "Thank you for calling support..."                          │
│                                                                 │
│  2. Position Announcement (if enabled)                          │
│     "You are caller number 3 in the queue"                      │
│                                                                 │
│  3. Wait Time Announcement (if enabled)                         │
│     "Your estimated wait time is 5 minutes"                     │
│                                                                 │
│  4. Music on Hold                                               │
│     ♪♪♪ [background music plays] ♪♪♪                            │
│                                                                 │
│  5. Periodic Announcement (every X seconds)                     │
│     "Please continue to hold, your call is important..."        │
│                                                                 │
│  6. Agent Connect Sound (to agent)                              │
│     "Call from Support queue"                                   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Callback Option

When enabled via a Callback Profile:

Caller hears: "Press 1 to receive a callback"
Caller presses 1
System captures caller's number
Caller hangs up
When agent available, system calls back

---

8. Common Scenarios & Examples

Scenario 1: Basic Support Queue

Configuration:

Extension: 6000
Strategy: Longest Idle Agent
Max Wait: 300 sec
Timeout: Voicemail 101

Agents (Tiers):

Agent	Level	Position
101	1	1
102	1	2
103	1	3

Scenario 2: Tiered Escalation

Configuration:

Extension: 7000
Strategy: Top Down
Tier Rule Wait: 30 sec

Agents (Tiers):

Agent	Level	Position	Role
201	1	1	Junior Support
202	1	2	Junior Support
203	2	1	Senior Support
204	3	1	Supervisor

Behavior: Tries Level 1 for 30s, then Level 2 for 30s, then Level 3.

Scenario 3: VIP Priority Queue

Configuration:

Extension: 8000
VIP List: "Premium Customers"
Strategy: Longest Idle Agent

VIP Behavior: Callers on VIP list get higher queue position score.

---

9. Limitations & Important Notes

Technical Limitations

WARNING

mod_callcenter Sync: Configuration changes need queue reload.

WARNING

Queue Name Unique: Queue names must be unique per domain.

Best Practices

Set Max Wait: Prevent infinite hold times
Configure Timeout: Route unanswered calls somewhere
Use Announcements: Keep callers informed
Monitor SLA: Track service level metrics
Enable Callback: Reduce abandonment

---

10. Troubleshooting Tips

Common Issues

Symptom	Possible Cause	Solution
Calls not answered	No available agents	Check agent status
Immediate timeout	Max wait = 0	Set max wait time
No announcements	Missing audio files	Check greeting paths
Agents not getting calls	Tier misconfigured	Verify level/position
Queue full	Max size reached	Increase max queue size

Diagnostic SQL

List queues:

Sql

SELECT id, name, extension, strategy, enabled
FROM public.call_center_queues
WHERE domain_id = [domain_id];

Check queue tiers:

Sql

SELECT a.name as agent, q.name as queue, t.level, t.position
FROM public.call_center_tiers t
JOIN public.call_center_agents a ON t.agent_id = a.id
JOIN public.call_center_queues q ON t.queue_id = q.id
WHERE q.domain_id = [domain_id]
ORDER BY q.name, t.level, t.position;

FreeSWITCH API Commands

Bash

# List all queues
callcenter_config queue list

# List agents in queue
callcenter_config queue list agents Support@domain.com

# List callers in queue
callcenter_config queue list members Support@domain.com

---

11. Glossary

Term	Definition
Queue	Call holding point for agent distribution
Strategy	Algorithm for selecting agents
Tier	Agent-Queue assignment with level/position
Level	Priority tier (1 = highest priority)
Position	Order within a tier
SLA	Service Level Agreement (target answer time)
Abandonment	Call that hangs up before answer
Callback	System calls back when agent available
VIP List	Priority callers list

---

Lua Script Status ✅

Both Scripts Already Correct

Script	Status	Schema
`queue_join.lua`	✅ Correct	Uses `public.domains`, `public.call_center_queues`, `public.call_center_callback_profiles`
`routing/queue.lua`	✅ Correct	Uses `public.dialplan_registry`, `public.call_center_queues`

No fixes required!

---

Documentation last updated: January 2026*

Queues (Call Center) Module Documentation

Table of Contents

1. Module Overview (Technical)

What Are Queues?

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?

Administrator Workflow

Quick Tips

4. Configuration Fields Reference

General Settings

Announcement Settings

Advanced Settings

5. Queue Strategies

Strategy Comparison

Strategy Diagrams

6. Tiers and Agents

Tier System

Tier Rules

7. Announcements & Caller Experience

Announcement Flow

Callback Option

8. Common Scenarios & Examples

Scenario 1: Basic Support Queue

Scenario 2: Tiered Escalation

Scenario 3: VIP Priority Queue

9. Limitations & Important Notes

Technical Limitations

Best Practices

10. Troubleshooting Tips

Common Issues

Diagnostic SQL

FreeSWITCH API Commands

11. Glossary

Lua Script Status ✅

Both Scripts Already Correct