Ctrl K
ring2all.com

Callback System Module Documentation

Table of Contents

  1. Module Overview (Technical)
  2. Module Overview (Commercial/Business)
  3. Module Overview (End User/Administrator)
  4. Callback Rules Configuration
  5. Callback Profiles Configuration
  6. Call Flow / Logic Explanation
  7. Common Scenarios & Examples
  8. Limitations & Important Notes
  9. Troubleshooting Tips
  10. Glossary

---

1. Module Overview (Technical)

What Is the Callback System?

The Callback System provides automated call-back functionality with two main components:

  1. Callback Rules: User-triggered callbacks via dial codes
  2. Callback Profiles: Queue-integrated callbacks (caller presses key to request callback instead of waiting)

Architecture

Plaintext
┌─────────────────────────────────────────────────────────────────┐
│                    Callback System Architecture                 │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                 CALLBACK RULES                          │    │
│  │  (User-triggered callbacks via dial codes)              │    │
│  │                                                         │    │
│  │  User dials *88 → Schedule callback to destination      │    │
│  │                   after configured delay                │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                 CALLBACK PROFILES                       │    │
│  │  (Queue-integrated callbacks)                           │    │
│  │                                                         │    │
│  │  Caller in queue → Press 1 → Exit queue, schedule       │    │
│  │                    callback when agent available        │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                 CALLBACK DISPATCHER                     │    │
│  │  (Scheduled task executor)                              │    │
│  │                                                         │    │
│  │  Polls scheduled_calls table → Executes pending         │    │
│  │  callbacks via loopback originate                       │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

TablePurpose
public.callback_rulesCallback rule definitions
public.callback_profilesQueue callback policies
public.scheduled_callsPending callback queue

Key Files

FileDescription
admin/apps/web/src/modules/callbackRules/Callback Rules frontend
admin/apps/web/src/modules/callbackProfiles/Callback Profiles frontend
telephony/freeswitch/lua/main/xml_handlers/callback/callback.luaRule trigger handler
telephony/freeswitch/lua/main/xml_handlers/callback/callback_handler.luaExecution handler
telephony/freeswitch/lua/main/services/queue_callback_dispatcher.luaQueue callback dispatcher
---

2. Module Overview (Commercial/Business)

Business Value

Callbacks improve customer experience and operational efficiency:

Without CallbacksWith Callbacks
Caller waits on holdCaller can hang up and receive callback
Frustrating hold timesFree to do other things
High abandonment ratesImproved customer satisfaction
Wasted agent timeEfficient queue management

Use Cases

  1. Queue Callbacks

- "Press 1 to receive a callback instead of waiting"

- Reduces hold times and abandonment

  1. Scheduled Callbacks

- Sales team schedules follow-up calls

- Service reminders

  1. Emergency Callbacks

- Quick dial to request immediate callback

- VIP customer service

  1. External Integration

- Web form triggers callback

- CRM-initiated callbacks

Feature Highlights

FeatureBenefit
Delay TimerSchedule callback after X seconds
Retry LogicAutomatic retry if no answer
CoS RestrictionLimit who can use callbacks
NotificationsEmail/API confirmation
Queue IntegrationSeamless queue callback option
---

3. Module Overview (End User/Administrator)

What Can You Do?

Callback Rules:
  • Create dial codes that trigger callbacks
  • Set delay before callback execution
  • Configure retry attempts and timeouts
  • Restrict usage by Class of Service

Callback Profiles:
  • Create reusable callback policies for queues
  • Configure DTMF key to request callback
  • Set timeout and retry intervals
  • Assign profiles to queues

Administrator Workflow (Callback Rule)

Plaintext
┌─────────────────────────────────────────────────────────────────┐
│                 Creating a Callback Rule                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Step 1: General Information                                    │
│  ├─ Callback Number: *88                                       │
│  ├─ Name: "Sales Callback"                                     │
│  └─ Description: "Request callback from sales team"            │
│                                                                 │
│  Step 2: Destination                                            │
│  ├─ Destination Module: Queue                                  │
│  └─ Destination Value: sales_queue                             │
│                                                                 │
│  Step 3: Settings                                               │
│  ├─ Delay Before Callback: 30 seconds                          │
│  ├─ Retry Count: 3                                             │
│  ├─ Max Wait Time: 60 seconds                                  │
│  └─ Dial Prefix: 9 (for external)                              │
│                                                                 │
│  Step 4: Access Control                                         │
│  ├─ Class of Service: None (all users)                         │
│  └─ Allowed Callers: (any)                                     │
│                                                                 │
│  Step 5: Enable and Save                                        │
│                                                                 │
│  Result: Dial *88 → Callback from sales queue in 30 seconds    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Tips

TIP
Delay Seconds: Short delay (10-30s) for immediate response, longer (300s+) for scheduled callbacks.
TIP
Retry Count: Set 2-3 retries to handle missed calls.
CAUTION
CoS Restriction: Always restrict if callback incurs costs (external numbers).

---

4. Callback Rules Configuration

Fields Reference

FieldDescriptionExampleRequired
Callback NumberDial code to trigger88, #99Yes
NameFriendly nameSales CallbackYes
Destination ModuleType of destinationQueue, Extension, ExternalYes
Destination ValueTarget identifiersales_queue, 1001Yes
Delay (seconds)Wait before callback30Yes
Retry CountRetry attempts3Yes
Max Wait TimeRing time per attempt60Yes
Dial PrefixPrefix for dialing9No
Class of ServiceAccess restrictionStandardNo
Allowed CallersPermitted extensions1001, 1002No
Record CallbackRecord the callOn/OffNo
Hangup AfterAuto hangup when doneOn/OffNo

Destination Modules

ModuleDescription
ExtensionCall back to specific extension
QueueRoute to call queue
ExternalCall external number
Ring GroupRoute to ring group
IVRSend to IVR menu

Callback Strategies

StrategyDescription
ImmediateExecute callback right away (after delay)
ScheduledSchedule for specific time
QueuePlace in queue dispatcher
---

5. Callback Profiles Configuration

What Are Callback Profiles?

Callback Profiles are reusable policies attached to queues. When enabled, callers in queue can press a DTMF key to request a callback instead of waiting.

Fields Reference

FieldDescriptionExample
Profile NameIdentifierStandard Callback
DTMF KeyKey to request callback1
Confirm SoundConfirmation audiocallback_confirm.wav
Thanks SoundAcknowledgment audiocallback_thanks.wav
Timeout (seconds)How long request is valid3600
Retry IntervalTime between retries300
Max AttemptsMaximum retry count3
StrategyRouting strategysame-queue, overflow, any-agent
Announcement SoundPre-callback audiocallback_announce.wav
EnabledActive statusOn/Off

Strategies

StrategyDescription
same-queueReturn caller to the same queue
overflowUse overflow queue if primary full
any-agentRoute to first available agent
---

6. Call Flow / Logic Explanation

Callback Rule Flow

Plaintext
┌─────────────────────────────────────────────────────────────────┐
│                    Callback Rule Flow                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. User dials *88 (callback rule code)                         │
│     │                                                           │
│     ▼                                                           │
│  2. Look up callback rule                                       │
│     ├─ Found & enabled → Continue                              │
│     └─ Not found → "Feature not available"                     │
│     │                                                           │
│     ▼                                                           │
│  3. Check access (CoS, allowed callers)                         │
│     ├─ Allowed → Continue                                      │
│     └─ Denied → "Not authorized"                               │
│     │                                                           │
│     ▼                                                           │
│  4. Play announcement (if configured)                           │
│     │                                                           │
│     ▼                                                           │
│  5. Schedule callback in scheduled_calls table                  │
│     ├─ Set execution time = NOW() + delay_seconds              │
│     └─ Store destination, retries, etc.                        │
│     │                                                           │
│     ▼                                                           │
│  6. Play "callback scheduled" confirmation                      │
│     │                                                           │
│     ▼                                                           │
│  7. Hang up initial call                                        │
│     │                                                           │
│     ▼                                                           │
│  8. Dispatcher picks up scheduled callback                      │
│     │                                                           │
│     ▼                                                           │
│  9. Execute loopback call to destination                        │
│     ├─ Answered → Call connected                               │
│     └─ No answer → Retry (up to max retries)                   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Queue Callback Flow

Plaintext
┌─────────────────────────────────────────────────────────────────┐
│                    Queue Callback Flow                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. Caller enters queue, hears: "Press 1 for callback"          │
│     │                                                           │
│     ▼                                                           │
│  2. Caller presses 1                                            │
│     │                                                           │
│     ▼                                                           │
│  3. Play confirmation: "You will receive a callback"            │
│     │                                                           │
│     ▼                                                           │
│  4. Caller exits queue, callback request stored                 │
│     │                                                           │
│     ▼                                                           │
│  5. When agent becomes available:                               │
│     ├─ Strategy: same-queue → Present to queue agent           │
│     ├─ Strategy: any-agent → First available                   │
│     └─ Strategy: overflow → Try overflow queue                 │
│     │                                                           │
│     ▼                                                           │
│  6. Agent takes callback, system calls customer                 │
│     │                                                           │
│     ▼                                                           │
│  7. Customer answers → Connected to agent                       │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

---

7. Common Scenarios & Examples

Scenario 1: Sales Callback Request

Callback Rule:
SettingValue
Callback Number88
NameSales Callback
DestinationQueue: sales_queue
Delay30 seconds
Retry Count3
Result: Dial 88 → In 30 seconds, receive call from sales queue.

Scenario 2: Queue Callback Option

Profile attached to support queue:
SettingValue
DTMF Key1
Strategysame-queue
Max Attempts3
Retry Interval300 seconds
Result: Callers in support queue can press 1 to exit and receive callback.

Scenario 3: VIP Callback Line

Callback Rule with CoS restriction:
SettingValue
Callback Number99
NameVIP Callback
DestinationExtension: 5000 (VIP line)
Class of ServiceVIP
Delay0 (immediate)
Result: Only VIP extensions can trigger immediate callback to VIP line.

---

8. Limitations & Important Notes

Technical Limitations

WARNING
Dispatcher Running: Callback dispatcher service must be running for scheduled callbacks to execute.
WARNING
External Costs: Callbacks to external numbers incur call costs—restrict with CoS if needed.
IMPORTANT
Retry Limits: After max retries, callback is marked as failed.

Best Practices

  1. Reasonable Delays: 10-60 seconds for immediate, 300+ for scheduled
  2. Limit Retries: 2-3 retries is usually sufficient
  3. Restrict External: Use CoS for external number callbacks
  4. Monitor Failed: Check failed callbacks regularly
  5. Test Thoroughly: Verify callbacks work before production

---

9. Troubleshooting Tips

Common Issues

SymptomPossible CauseSolution
Callback not triggeredRule disabledEnable the rule
"Not authorized"CoS mismatchCheck Class of Service
No callback receivedDispatcher not runningStart dispatcher service
Callback loopsWrong destinationVerify destination config
All retries failedDestination unreachableCheck destination availability

Diagnostic SQL

List callback rules:

Sql
SELECT callback_number, name, destination_module, 
       destination_value, delay_seconds, enabled
FROM public.callback_rules
WHERE domain_id = [domain_id];

Check pending callbacks:

Sql
SELECT * FROM public.scheduled_calls
WHERE executed = FALSE AND scheduled_time <= NOW()
ORDER BY scheduled_time;

---

10. Glossary

TermDefinition
Callback RuleConfiguration that triggers callback when dial code is used
Callback ProfileReusable callback policy for queues
DispatcherService that executes scheduled callbacks
DTMF KeyPhone key pressed to request callback (1, 2, etc.)
Delay SecondsTime to wait before executing callback
Retry CountNumber of callback attempts if no answer
LoopbackFreeSWITCH mechanism to originate internal calls
Scheduled CallCallback request stored for future execution
---

Lua Script Status ✅

Integration Module

ComponentStatusLocation
Callback Handler✅ Activeapp/callback/callback_system.lua
--- Documentation last updated: January 2026
AI Assistant

👋 Hello! I'm your Ring2All documentation assistant. I can help you find information about configuring and using the Ring2All PBX platform.

How can I help you today?