Agents (Call Center) Module Documentation

Module Overview (Technical)
Module Overview (Commercial/Business)
Module Overview (End User/Administrator)
Configuration Fields Reference
Agent States & Transitions
Queue Membership
Common Scenarios & Examples
Limitations & Important Notes
Troubleshooting Tips
Glossary

---

1. Module Overview (Technical)

What Are Agents?

Agents are call center operators who handle calls from queues. Each agent is linked to an extension and can log in/out of queues, pause for breaks, and have configurable timeouts and wrap-up times.

Architecture

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                    Agent System                                 │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                      Agent                                │  │
│  │              Name: "John Smith"                           │  │
│  │              Extension: 101                               │  │
│  │              Status: Available                            │  │
│  ├───────────────────────────────────────────────────────────┤  │
│  │                                                           │  │
│  │  Behavior Settings:                                       │  │
│  │  ├─ Max No Answer: 3                                     │  │
│  │  ├─ Ring Timeout: 20 sec                                 │  │
│  │  ├─ Wrap-Up Time: 10 sec                                 │  │
│  │  └─ Reject Delay: 90 sec                                 │  │
│  │                                                           │  │
│  │  Queue Membership:                                        │  │
│  │  ├─ Sales Queue (Level 1, Position 1)                    │  │
│  │  └─ Support Queue (Level 2, Position 3)                  │  │
│  │                                                           │  │
│  └───────────────────────────────────────────────────────────┘  │
│                          │                                      │
│                          ▼                                      │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │               FreeSWITCH mod_callcenter                   │  │
│  │                                                           │  │
│  │  Agent: 101@domain.com                                   │  │
│  │  Type: callback                                          │  │
│  │  Contact: user/101@domain.com                            │  │
│  │  Status: Available                                       │  │
│  │  State: Waiting                                          │  │
│  │                                                           │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

Table	Purpose
`public.call_center_agents`	Agent definitions
`public.call_center_queues`	Queue definitions
`public.call_center_tiers`	Agent-Queue assignments
`public.call_center_agent_profiles`	Shared agent settings
`ss_cc.agents`	mod_callcenter runtime state

Key Files

File	Description
`admin/apps/web/src/modules/agents/`	Frontend module
`admin/apps/web/src/i18n/en/agents.json`	Translations
`telephony/freeswitch/lua/main/xml_handlers/callcenter/agent_control.lua`	Agent login/logout/pause handler
`telephony/freeswitch/lua/main/xml_handlers/callcenter/agent_hotdesk_combo.lua`	Hotdesk + Agent combo login

---

2. Module Overview (Commercial/Business)

Business Value

Agents provide professional call center capabilities:

Without Agents	With Agents
Manual call handling	Queue-based distribution
No status tracking	Real-time availability
No break management	Pause/unpause controls
No performance data	Agent metrics

Use Cases

Inbound Call Centers

- Customer support teams

- Technical help desks

- Order taking

Sales Teams

- Lead qualification

- Outbound campaigns

- Appointment setting

Multi-Queue Routing

- Tiered support levels

- Skills-based routing

- Overflow handling

Feature Highlights

Feature	Benefit
4 Agent Statuses	Available, Available (On Demand), On Break, Logged Out
3 Agent Types	Inbound, Outbound, Callback
Auto/Manual State	Control how status changes
Max No Answer	Auto-pause after missed calls
Wrap-Up Time	Post-call processing time
Ring Timeout	Per-agent ring duration
Recording	Per-agent call recording
BLF Support	Lamp status on phones

---

3. Module Overview (End User/Administrator)

What Can You Do?

Create agents linked to extensions
Configure behavior settings
Set initial status and state mode
Assign agents to queues via Tiers
Enable/disable agents

Administrator Workflow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              Creating an Agent                                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Step 1: General Settings                                       │
│  ├─ Agent Name: "John Smith"                                   │
│  ├─ Extension: Select 101                                      │
│  ├─ Enabled: ✓                                                 │
│  ├─ Initial Status: Available                                  │
│  └─ State Mode: Auto                                           │
│                                                                 │
│  Step 2: Behavior Settings                                      │
│  ├─ Max No Answer: 3                                           │
│  ├─ Ring Timeout: 20 sec                                       │
│  ├─ Wrap-Up Time: 10 sec                                       │
│  ├─ Busy Delay Time: 90 sec                                    │
│  ├─ Reject Delay Time: 90 sec                                  │
│  └─ No Answer Delay Time: 30 sec                               │
│                                                                 │
│  Step 3: Advanced Settings                                      │
│  ├─ Agent Type: Inbound                                        │
│  ├─ Max Concurrent Calls: 1                                    │
│  └─ Record Calls: ✓                                            │
│                                                                 │
│  Step 4: Save, then assign to Queues via Tiers                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Agent Workflow (Using Feature Codes)

Plaintext

Login to all assigned queues:
  Dial *91 → "Agent logged in"

Logout from all queues:
  Dial *92 → "Agent logged out"

Pause (all queues):
  Dial *93 → "Agent paused"

Unpause (resume):
  Dial *93 → "Agent resumed"

Login to specific queue:
  Dial *91 + queue number# → "Logged into queue"

Pause in specific queue:
  Dial *93 + queue number# → "Paused in queue"

Quick Tips

TIP

State Mode Auto: System changes status based on phone state.

TIP

Max No Answer: Set to 3 to auto-pause after 3 missed calls.

CAUTION

Wrap-Up Time: Too short = missed calls; too long = idle agents.

---

4. Configuration Fields Reference

General Settings

Field	Description	Example
Agent Name	Display name	`John Smith`
Extension	Associated extension	`101`
Enabled	Agent can be used	On/Off
Initial Status	Status when logging in	Available
State Mode	Auto or Manual	Auto

Behavior Settings

Field	Description	Default
Max No Answer	Missed calls before pause	3
Ring Timeout	Seconds to ring agent	20
Wrap-Up Time	Post-call delay	10
Busy Delay Time	Delay after busy	90
Reject Delay Time	Delay after reject	90
No Answer Delay Time	Delay after no answer	30

Advanced Settings

Field	Description	Options
Agent Type	Call handling type	Inbound, Outbound, Callback
Max Concurrent Calls	Multi-call limit	1
Record Calls	Enable recording	On/Off

---

5. Agent States & Transitions

Agent Statuses

Status	Description	Available for Calls
Available	Ready to receive calls	✅ Yes
Available (On Demand)	Ready but rings only if no others	⚡ On Demand
On Break	Paused, not receiving	❌ No
Logged Out	Not in queues	❌ No

State Diagram

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                    Agent State Flow                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│                    ┌─────────────┐                              │
│                    │ Logged Out  │                              │
│                    └──────┬──────┘                              │
│                           │ *91 Login                           │
│                           ▼                                     │
│                    ┌─────────────┐                              │
│           ┌───────▶│  Available  │◀───────┐                    │
│           │        └──────┬──────┘        │                     │
│           │               │ *93 Pause     │ *93 Unpause         │
│           │               ▼               │                     │
│           │        ┌─────────────┐        │                     │
│           │        │  On Break   │────────┘                     │
│           │        └─────────────┘                              │
│           │                                                     │
│           │ *92 Logout                                          │
│           │                                                     │
│    ┌──────┴──────┐                                              │
│    │ Logged Out  │                                              │
│    └─────────────┘                                              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

State Mode

Mode	Behavior
Auto	System changes state based on phone activity
Manual	Agent must change state via feature codes

---

6. Queue Membership

Tier System

Agents are assigned to queues via Tiers with:

Level: Priority tier (1 = highest)
Position: Order within tier

Plaintext

Queue: Sales
├─ Tier Level 1 (try first)
│  ├─ Position 1: Agent Alice
│  └─ Position 2: Agent Bob
├─ Tier Level 2 (try if L1 unavailable)
│  └─ Position 1: Agent Carol
└─ Tier Level 3 (overflow)
   └─ Position 1: Agent Dave

Feature Codes for Queue Control

Code	Action
91	Global login (all assigned queues)
92	Global logout (all queues)
93	Global pause/unpause toggle
91 + queue#	Login to specific queue
93 + queue#	Pause in specific queue

---

7. Common Scenarios & Examples

Scenario 1: Basic Support Agent

Configuration:

Extension: 201
Initial Status: Logged Out
Max No Answer: 3
Ring Timeout: 20 sec
Wrap-Up Time: 10 sec

Workflow:

Agent dials 91 at shift start
Receives calls from Support queue
Dials 93 for lunch break

Dials 93 to resume
Dials 92 at shift end

Queue	Level	Position
Sales	1	1
Support	2	3
Billing	1	2

Symptom	Possible Cause	Solution
No calls received	Agent not Available	Check status via feature code
Immediate timeout	Ring timeout too short	Increase ring timeout
Stuck in queue	No available agents	Check agent availability
BLF not updating	Presence misconfigured	Verify BLF setup

Term	Definition
Agent	Call center operator handling queue calls
Tier	Agent-Queue assignment with level/position
Level	Priority tier (lower = higher priority)
Position	Order within a tier
Wrap-Up Time	Post-call processing delay
State Mode	Auto or Manual status control
BLF	Busy Lamp Field (phone status lights)

Issue	Before	After
Schema	`core.call_center_agents`	`public.call_center_agents`
Domain lookup	`core.tenants`	`public.domains`
Hotdesk tables	`core.hot_desk`, `core.sip_devices`	`public.hot_desk`, `public.sip_devices`
Variable naming	`tenant_id`	`domain_id`
Column names	`update_at`	`updated_at`

Scenario 2: Multi-Queue Agent
Queues:
Queue Level Position
Sales 1 1
Support 2 3
Billing 1 2
Behavior: Gets Sales calls first, Support only when Sales quiet.
Scenario 3: Hotdesk + Agent Combo
Flow:
Agent logs into hotdesk device

Automatically logs into call center queues

Device assignment + queue login in one step

---

8. Limitations & Important Notes

Technical Limitations

WARNING
Single Extension: Each agent is linked to one extension.

WARNING
mod_callcenter Sync: Changes may take seconds to propagate.

Best Practices

Set Max No Answer: Prevent indefinite missed calls

Appropriate Wrap-Up: Allow post-call work time

Use Tiers: Organize skill-based routing

Monitor BLF: Use lamp indicators

Test State Changes: Verify feature codes work

---

9. Troubleshooting Tips

Common Issues

Symptom Possible Cause Solution
No calls received Agent not Available Check status via feature code
Immediate timeout Ring timeout too short Increase ring timeout
Stuck in queue No available agents Check agent availability
BLF not updating Presence misconfigured Verify BLF setup
Diagnostic SQL
List agents:
Sql
SELECT id, name, extension, status, enabled FROM public.call_center_agents WHERE domain_id = [domain_id];

Check agent queues (tiers):
Sql
SELECT a.name, 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 a.domain_id = [domain_id];

FreeSWITCH API Commands

Bash
# List all agents callcenter_config agent list # Get agent status callcenter_config agent get status 101@domain.com # Set agent available callcenter_config agent set status 101@domain.com Available

---

10. Glossary

Term Definition
Agent Call center operator handling queue calls
Tier Agent-Queue assignment with level/position
Level Priority tier (lower = higher priority)
Position Order within a tier
Wrap-Up Time Post-call processing delay
State Mode Auto or Manual status control
BLF Busy Lamp Field (phone status lights)
---
Lua Script Status ✅

agent_control.lua
Already Correct — Uses public. schema throughout.
agent_hotdesk_combo.lua - Fixed

Issue Before After
Schema core.call_center_agents public.call_center_agents
Domain lookup core.tenants public.domains
Hotdesk tables core.hot_desk, core.sip_devices public.hot_desk, public.sip_devices
Variable naming tenant_id domain_id
Column names update_at updated_at
---

Documentation last updated: January 2026*

Agents (Call Center) Module Documentation

Table of Contents

1. Module Overview (Technical)

What Are Agents?

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

Agent Workflow (Using Feature Codes)

Quick Tips

4. Configuration Fields Reference

General Settings

Behavior Settings

Advanced Settings

5. Agent States & Transitions

Agent Statuses

State Diagram

State Mode

6. Queue Membership

Tier System

Feature Codes for Queue Control

7. Common Scenarios & Examples

Scenario 1: Basic Support Agent

Scenario 2: Multi-Queue Agent

Scenario 3: Hotdesk + Agent Combo

8. Limitations & Important Notes

Technical Limitations

Best Practices

9. Troubleshooting Tips

Common Issues

Diagnostic SQL

FreeSWITCH API Commands

10. Glossary

Lua Script Status ✅

agent_control.lua

agent_hotdesk_combo.lua - Fixed