Queue Callback Report Module Documentation

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

---

1. Module Overview (Technical)

What Is Queue Callback Report?

Queue Callback Report is a management and reporting interface for queue callback requests. It displays all scheduled, pending, and completed callbacks, allowing supervisors to monitor callback status, cancel requests, force retries, and delete old records.

Architecture

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│               Queue Callback Report Architecture                │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Queue                                                          │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        queue.lua                                         │   │
│  │                                                          │   │
│  │  Caller requests callback                                │   │
│  │  ├─ Store in queue_callbacks table                      │   │
│  │  ├─ Set status = pending                                │   │
│  │  └─ Schedule next attempt                               │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        queue_callback_dispatcher.lua                     │   │
│  │                                                          │   │
│  │  Scheduled job attempts callback                         │   │
│  │  ├─ Update status = calling                             │   │
│  │  ├─ Originate call to caller                            │   │
│  │  ├─ On answer: status = completed                       │   │
│  │  ├─ On fail: increment attempts, reschedule             │   │
│  │  └─ On max attempts: status = failed                    │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        public.queue_callbacks                            │   │
│  │                                                          │   │
│  │  id | queue_id | callback_number | status | attempts    │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ Displayed in Report                                     │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        Queue Callback Report Page                        │   │
│  │                                                          │   │
│  │  [Filters] [Refresh]                                     │   │
│  │                                                          │   │
│  │  ┌─────────────────────────────────────────────────────┐ │   │
│  │  │Queue │Caller  │Status  │Attempts│Next    │Actions  │ │   │
│  │  ├──────┼────────┼────────┼────────┼────────┼─────────┤ │   │
│  │  │Sales │555-1234│Pending │ 0/3    │12:30:00│[Cancel] │ │   │
│  │  │Supp  │555-5678│Complete│ 1/3    │   -    │[Delete] │ │   │
│  │  └─────────────────────────────────────────────────────┘ │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

Table	Purpose
`public.queue_callbacks`	Callback requests and status

Key Files

File	Description
`modules/queueCallbackReport/`	Frontend report
`modules/queueCallbackReport/api/queueCallbackApi.ts`	API calls

---

2. Module Overview (Commercial/Business)

Business Value

Queue Callback Report provides callback visibility and control:

Without Report	With Report
Unknown callback status	Full visibility
No intervention	Cancel/retry control
Hidden failures	Track failed attempts
Manual tracking	Automated reporting

Use Cases

Callback Monitoring

- Track pending callbacks

- View completed callbacks

Intervention

- Cancel incorrect requests

- Force immediate retry

Failure Analysis

- Identify failed callbacks

- Review hangup causes

Cleanup

- Delete old records

- Manage queue capacity

Feature Highlights

Feature	Benefit
Status Tracking	See callback state
Attempt Counter	Monitor retry progress
Queue Filter	Filter by queue
Date Filter	Historical queries
Cancel Action	Stop unwanted callbacks
Retry Action	Force immediate retry
Delete Action	Remove old records

---

3. Module Overview (End User/Administrator)

What Can You Do?

View all callback requests
Filter by queue and status
Filter by date range
Monitor attempt progress
Cancel pending callbacks
Force immediate retry
Delete old records

Queue Callback Report Interface

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              Queue Callback Report                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  View and manage queue callback requests                        │
│                                                                 │
│  Filters:                                                       │
│  ├─ Queue: [All Queues ▼]                                      │
│  ├─ Status: [All Statuses ▼]                                   │
│  ├─ From: [01/01/2026]  To: [01/16/2026]                       │
│  └─ [Apply Filters] [Clear Filters] [🔄 Refresh]               │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │Queue │ Caller     │ Status   │Atts│ Next Att │  Actions  │  │
│  ├──────┼────────────┼──────────┼────┼──────────┼───────────┤  │
│  │Sales │ 555-1234   │🟡Pending │ 0/3│ 12:30:00 │[⟲][🚫][🗑]│  │
│  │Supp  │ 555-5678   │📞Calling │ 1/3│    -     │           │  │
│  │Sales │ 555-9012   │✅Complete│ 1/3│    -     │     [🗑]  │  │
│  │Supp  │ 555-3456   │❌Failed  │ 3/3│    -     │  [⟲] [🗑]│  │
│  │Sales │ 555-7890   │⏰Expired │ 2/3│    -     │     [🗑]  │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
│  Actions: ⟲ = Retry | 🚫 = Cancel | 🗑 = Delete                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Tips

TIP

Retry: Force immediate retry for failed callbacks.

TIP

Cancel: Cancel pending callbacks before they execute.

CAUTION

Delete: Deleting is permanent - use for cleanup only.

---

4. Report Fields Reference

Display Columns

Column	Description
ID	Unique callback ID
Queue	Queue name
Caller ID	Original caller number
Callback Number	Number to call back
Status	Current callback state
Attempts	Current/Max attempts
Next Attempt	Scheduled retry time
Expires At	When callback expires
Created At	Request creation time
Last Result	Last hangup cause
Actions	Available actions

Available Actions

Action	Description	Available When
Retry	Force immediate retry	Failed, Expired
Cancel	Cancel callback	Pending, Scheduled
Delete	Delete record	Any completed state

---

5. Callback Statuses

Status Types

Status	Icon	Description
Pending	🟡	Waiting for first attempt
Calling	📞	Currently calling caller
Scheduled	📅	Scheduled for retry
Completed	✅	Callback successful
Failed	❌	All attempts exhausted
Cancelled	🚫	Manually cancelled
Expired	⏰	Expired before completion

Status Flow

Plaintext

Pending → Calling → Completed ✅
    │         │
    │         └─→ Scheduled → Calling → ...
    │                   │
    │                   └─→ Failed ❌ (max attempts)
    │                   └─→ Expired ⏰ (time limit)
    │
    └─→ Cancelled 🚫 (manual)

---

6. Common Scenarios & Examples

Scenario 1: Monitor Pending Callbacks

Set Status filter to "Pending"
View pending queue
Monitor for stuck callbacks

Scenario 2: Retry Failed Callback

Filter by "Failed" status
Find callback record
Click Retry action
Monitor new attempt

Scenario 3: Cancel Incorrect Request

Search for caller number
Find pending callback
Click Cancel action
Confirm cancellation

Scenario 4: Cleanup Old Records

Set date filter to old range
Filter by "Completed"
Delete unneeded records

---

7. Limitations & Important Notes

Technical Notes

NOTE

Queue Dependency: Callbacks are tied to specific queues.

NOTE

Attempt Limits: Max attempts configured per queue.

WARNING

Timing: Callbacks respect scheduled times.

Best Practices

Regular Monitoring: Check for stuck callbacks
Handle Failures: Retry or cancel failed callbacks
Cleanup: Delete old completed records
Watch Expiry: Monitor expired callbacks
Check Last Result: Diagnose why callbacks fail

Common Hangup Causes

Cause	Meaning
NORMAL_CLEARING	Success
NO_ANSWER	No answer
USER_BUSY	Line busy
CALL_REJECTED	Rejected
ORIGINATOR_CANCEL	Caller hung up

---

8. Troubleshooting Tips

Common Issues

Symptom	Possible Cause	Solution
Stuck pending	Dispatcher not running	Check dispatcher job
All failing	Bad number format	Check callback number
High failures	Network issues	Check trunks
Not retrying	Max attempts reached	Manually retry
Expired	Took too long	Adjust expiry settings

Diagnostic SQL

Callback summary by status:

Sql

SELECT 
  status,
  COUNT(*) as count
FROM public.queue_callbacks
WHERE created_at >= NOW() - INTERVAL '24 hours'
GROUP BY status;

Failed callbacks with reason:

Sql

SELECT 
  id, callback_number, attempt_count, 
  last_hangup_cause, updated_at
FROM public.queue_callbacks
WHERE status = 'failed'
ORDER BY updated_at DESC
LIMIT 20;

---

9. Glossary

Term	Definition
Callback	Return call to waiting caller
Attempt	Single callback try
Pending	Waiting for first attempt
Scheduled	Queued for retry
Expired	Time limit exceeded
Hangup Cause	Call termination reason

---

Lua Script Status ℹ️

No Dedicated Handler Required

Component	Status
Queue Callback Report	ℹ️ Reporting module - reads from `public.queue_callbacks`

Queue Callback Report is a frontend reporting/management interface. Callbacks are managed by queue.lua and queue_callback_dispatcher.lua. This module only reads and manages records.

---

Documentation last updated: January 2026

Queue Callback Report Module Documentation

Table of Contents

1. Module Overview (Technical)

What Is Queue Callback Report?

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 Callback Report Interface

Quick Tips

4. Report Fields Reference

Display Columns

Available Actions

5. Callback Statuses

Status Types

Status Flow

6. Common Scenarios & Examples

Scenario 1: Monitor Pending Callbacks

Scenario 2: Retry Failed Callback

Scenario 3: Cancel Incorrect Request

Scenario 4: Cleanup Old Records

7. Limitations & Important Notes

Technical Notes

Best Practices

Common Hangup Causes

8. Troubleshooting Tips

Common Issues

Diagnostic SQL

9. Glossary

Lua Script Status ℹ️

No Dedicated Handler Required