Callback Profiles Module Documentation

Module Overview (Technical)
Module Overview (Commercial/Business)
Module Overview (End User/Administrator)
Configuration Fields Reference
Callback Workflow
Strategies
Common Scenarios & Examples
Limitations & Important Notes
Troubleshooting Tips
Glossary

---

1. Module Overview (Technical)

What Are Callback Profiles?

Callback Profiles are reusable policies that define how queue callback (callback on hold) works. When a caller in a queue presses the designated DTMF key, they can request a callback instead of waiting on hold.

Architecture

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                  Callback Profile System                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Callback Profile: "Standard Callback"                          │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │ DTMF Key: 1          │ Max Attempts: 3                     │ │
│  │ Timeout: 3600s       │ Retry Interval: 300s                │ │
│  │ Strategy: same-queue │ Confirm Sound: callback_confirm.wav │ │
│  └────────────────────────────────────────────────────────────┘ │
│                          │                                      │
│        Assigned to Queues: Sales, Support, Billing              │
│                          │                                      │
│                          ▼                                      │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              Callback Capture Flow                       │   │
│  │                                                          │   │
│  │  1. Caller in queue presses "1"                         │   │
│  │  2. queue_callback_capture.lua handles DTMF             │   │
│  │  3. Play confirm sound, collect callback number         │   │
│  │  4. Validate and register callback request              │   │
│  │  5. Play thanks sound, caller hangs up                  │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                          │                                      │
│                          ▼                                      │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              Callback Dispatcher                         │   │
│  │                                                          │   │
│  │  1. Periodic check for pending callbacks                │   │
│  │  2. Originate call to callback number                   │   │
│  │  3. When answered, connect to queue or agent           │   │
│  │  4. On failure, retry based on profile settings         │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

Table	Purpose
`public.call_center_callback_profiles`	Profile definitions
`public.call_center_callbacks`	Callback requests
`public.call_center_queues`	Queue → Profile assignments

Key Files

File	Description
`admin/apps/web/src/modules/callbackProfiles/`	Frontend module
`admin/apps/web/src/i18n/en/callbackProfiles.json`	Translations
`telephony/freeswitch/lua/features/queue_callback_capture.lua`	DTMF capture handler
`telephony/freeswitch/lua/resources/functions/queue_callback_utils.lua`	Shared utilities
`telephony/freeswitch/lua/main/services/queue_callback_dispatcher.lua`	Callback originator
`telephony/freeswitch/lua/features/queue_callback_answer_handler.lua`	Answer handler

---

2. Module Overview (Commercial/Business)

Business Value

Callback Profiles provide professional callback on hold:

Without Callback	With Callback
Callers wait on hold	Option to hang up and be called back
High abandonment	Reduced abandonment
Poor experience	Modern customer experience
No retry logic	Automatic retries

Use Cases

High-Volume Call Centers

- Reduce hold times

- Improve customer satisfaction

After-Hours Overflow

- Collect callback requests

- Process when agents available

Premium Service

- VIP callers get callback option

- Reduced wait friction

Feature Highlights

Feature	Benefit
DTMF Key	Configurable trigger (default: 1)
3 Strategies	Same Queue, Overflow, Any Agent
Retry Logic	Automatic retries on failure
Rate Limiting	Prevent abuse
Custom Audio	Branded confirm/thanks sounds
Timeout	Auto-expire old requests

---

3. Module Overview (End User/Administrator)

What Can You Do?

Create callback profiles with policies
Configure DTMF trigger key
Set retry parameters
Choose callback strategy
Assign profiles to queues

Administrator Workflow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              Creating a Callback Profile                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  General Settings                                               │
│  ├─ Profile Name: "Standard Callback"                          │
│  ├─ DTMF Key: 1                                                │
│  ├─ Strategy: Same Queue                                       │
│  └─ Enabled: ✓                                                 │
│                                                                 │
│  Timing                                                         │
│  ├─ Timeout: 3600 sec (1 hour)                                 │
│  ├─ Retry Interval: 300 sec (5 min)                            │
│  └─ Max Attempts: 3                                            │
│                                                                 │
│  Audio                                                          │
│  ├─ Confirm Sound: callback_confirm.wav                        │
│  ├─ Thanks Sound: callback_thanks.wav                          │
│  └─ Announcement: callback_announcement.wav                    │
│                                                                 │
│  Save → Then assign to Queue in Queue settings                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Queue Integration

In Queue settings, select Callback Profile:

Plaintext

Queue Settings → Callback Profile → Select "Standard Callback"

Caller Experience

Plaintext

1. Caller enters queue, hears music on hold
2. Announcement: "Press 1 to receive a callback"
3. Caller presses 1
4. System: "Please confirm your callback number..."
5. Caller enters number or presses 1 for caller ID
6. System: "Thank you, we will call you back"
7. Caller hangs up
8. When agent available, system calls back

Quick Tips

TIP

Retry Interval: 5 minutes (300s) is a reasonable default.

TIP

Max Attempts: 3 attempts prevents endless retries.

CAUTION

Timeout: Set appropriate timeout—expired callbacks are not processed.

---

4. Configuration Fields Reference

Callback Profile Fields

Field	Description	Example	Default
Profile Name	Unique identifier	`Standard Callback`	Required
DTMF Key	Key to trigger callback	`1`	1
Strategy	How callback is routed	Same Queue	same-queue
Timeout (s)	Request validity period	`3600`	3600
Retry Interval (s)	Wait between retries	`300`	300
Max Attempts	Maximum retry count	`3`	3
Confirm Sound	Plays when requesting	audio file	-
Thanks Sound	Plays after registration	audio file	-
Announcement Sound	Periodic announcement	audio file	-
Enabled	Profile active status	On/Off	On

Timing Guidelines

Setting	Recommended	Purpose
Timeout	3600 (1 hour)	Request expires after
Retry Interval	300 (5 min)	Time between attempts
Max Attempts	3	Total tries before fail

---

5. Callback Workflow

Complete Flow Diagram

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              Callback on Hold Flow                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  CAPTURE PHASE (queue_callback_capture.lua)                     │
│  ─────────────────────────────────────────                      │
│  1. Caller in queue presses DTMF key (e.g., "1")               │
│  2. Break out of queue, play confirm sound                      │
│  3. Collect callback number (or use caller ID)                 │
│  4. Validate number (min 7 digits)                              │
│  5. Check rate limit (max 5/hour default)                      │
│  6. Register callback in public.call_center_callbacks          │
│  7. Play thanks sound                                           │
│  8. Hang up caller                                              │
│                                                                 │
│  DISPATCH PHASE (queue_callback_dispatcher.lua)                 │
│  ───────────────────────────────────────────                    │
│  1. Periodic service checks for pending callbacks              │
│  2. Lock record (FOR UPDATE SKIP LOCKED)                       │
│  3. Update status to 'calling'                                 │
│  4. Originate call to callback number                          │
│  5. On answer → connect to queue or agent                      │
│  6. On no answer → schedule retry or mark failed               │
│                                                                 │
│  ANSWER PHASE (queue_callback_answer_handler.lua)               │
│  ────────────────────────────────────────────                   │
│  1. Play announcement to caller                                │
│  2. Connect to original queue                                  │
│  3. Wait for agent                                             │
│  4. On completion → mark callback as completed                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Status Flow

Plaintext

pending → calling → completed
    ↓         ↓
 expired    failed (if max attempts reached)
    ↑         ↓
    └── pending (retry scheduled)

---

6. Strategies

Strategy Comparison

Strategy	Description	Best For
same-queue	Return caller to original queue	Standard callback
overflow	Route to overflow destination	High volume
any-agent	Route to any available agent	Fastest answer

Strategy Details

Same Queue (default)

Caller returns to the same queue they left
Respects original tier/priority settings
Best for maintaining queue order

Overflow

Routes to overflow destination
Used when original queue is still busy
Requires overflow configuration

Any Agent

Routes to first available agent system-wide
Fastest connection
May bypass queue logic

---

7. Common Scenarios & Examples

Scenario 1: Standard Queue Callback

Profile: "Support Callback"

Setting	Value
DTMF Key	1
Strategy	same-queue
Timeout	3600 sec
Retry Interval	300 sec
Max Attempts	3

Flow: Caller presses 1, system calls back and connects to Support queue.

Scenario 2: Fast Callback

Profile: "Express Callback"

Setting	Value
DTMF Key	1
Strategy	any-agent
Timeout	1800 sec
Retry Interval	120 sec
Max Attempts	5

Flow: Frequent retries, connect to any available agent.

Scenario 3: VIP Callback

Profile: "VIP Callback"

Setting	Value
DTMF Key	1
Strategy	same-queue
Timeout	7200 sec
Retry Interval	180 sec
Max Attempts	10

Flow: Longer validity, more retry attempts for VIP customers.

---

8. Limitations & Important Notes

Technical Notes

NOTE

Rate Limiting: Default 5 callbacks per caller per hour to prevent abuse.

WARNING

Audio Files: Ensure confirm/thanks audio files exist in language paths.

Best Practices

Test Audio: Verify all audio files play correctly
Set Reasonable Timeout: 1-2 hours typical
Retry Interval: 5 minutes prevents overwhelming the system
Monitor Completion: Check callback completion rates
Handle Failures: Review failed callbacks for patterns

---

9. Troubleshooting Tips

Common Issues

Symptom	Possible Cause	Solution
DTMF not captured	Wrong key binding	Check queue callback profile assignment
No callback received	Profile not assigned	Assign profile to queue
Callback expired	Timeout too short	Increase timeout
Too many retries	Max attempts too high	Reduce max attempts
Rate limit	Caller exceeded limit	Wait 1 hour or increase limit

Diagnostic SQL

List callback profiles:

Sql

SELECT id, name, enabled, max_attempts, retry_interval, timeout
FROM public.call_center_callback_profiles
WHERE domain_id = [domain_id];

Check pending callbacks:

Sql

SELECT id, queue_name, callback_number_norm, status, attempt_count, 
       next_attempt_at, expires_at
FROM public.call_center_callbacks
WHERE domain_id = [domain_id]
  AND status = 'pending'
ORDER BY next_attempt_at;

Check queue callback profile assignments:

Sql

SELECT q.name as queue, cp.name as callback_profile
FROM public.call_center_queues q
JOIN public.call_center_callback_profiles cp ON q.callback_profile_id = cp.id
WHERE q.domain_id = [domain_id]
  AND q.callback_profile_id IS NOT NULL;

---

10. Glossary

Term	Definition
Callback Profile	Reusable callback policy configuration
DTMF Key	Keypress to trigger callback request
Strategy	How callback is routed (same-queue, overflow, any-agent)
Timeout	How long callback request stays valid
Retry Interval	Time between retry attempts
Max Attempts	Maximum number of callback tries
Rate Limiting	Prevents excessive callback requests

---

Lua Script Status ✅

All Scripts Already Correct

Script	Status
`queue_callback_capture.lua`	✅ Uses utilities with correct schema
`queue_callback_utils.lua`	✅ Uses `public.call_center_queues`, `public.call_center_callback_profiles`, `public.call_center_callbacks`
`queue_callback_dispatcher.lua`	✅ Uses utilities
`queue_callback_answer_handler.lua`	✅ Uses utilities

No Lua fixes needed!

---

Documentation last updated: January 2026

Callback Profiles Module Documentation

Table of Contents

1. Module Overview (Technical)

What Are Callback 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?

Administrator Workflow

Queue Integration

Caller Experience

Quick Tips

4. Configuration Fields Reference

Callback Profile Fields

Timing Guidelines

5. Callback Workflow

Complete Flow Diagram

Status Flow

6. Strategies

Strategy Comparison

Strategy Details

7. Common Scenarios & Examples

Scenario 1: Standard Queue Callback

Scenario 2: Fast Callback

Scenario 3: VIP Callback

8. Limitations & Important Notes

Technical Notes

Best Practices

9. Troubleshooting Tips

Common Issues

Diagnostic SQL

10. Glossary

Lua Script Status ✅

All Scripts Already Correct