VIP Lists (Queues VIP) Module Documentation

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

---

1. Module Overview (Technical)

What Are VIP Lists?

VIP Lists are reusable caller identification lists that boost queue priority for matching phone numbers. When a caller's number matches a VIP list member, they receive priority treatment in the queue.

Architecture

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                    VIP List System                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  VIP List: "Premium Customers"                                  │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │ Phone Number     │ Weight │ Level │ Position │ Enabled    │ │
│  ├──────────────────┼────────┼───────┼──────────┼────────────┤ │
│  │ +15551234567     │   50   │   1   │    -     │    ✓       │ │
│  │ +15559876543     │   30   │   1   │    -     │    ✓       │ │
│  │ +15555551212     │   20   │   2   │    1     │    ✓       │ │
│  └──────────────────┴────────┴───────┴──────────┴────────────┘ │
│                                                                 │
│  Assigned to Queues:                                            │
│  ├─ Sales Queue                                                │
│  └─ Support Queue                                              │
│                                                                 │
│  When caller +15551234567 enters Sales Queue:                   │
│  → Priority score increased by weight (50)                      │
│  → Tier level forced to 1 (highest priority agents)            │
│  → Result: Caller answered faster by best agents               │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

Table	Purpose
`public.vip_lists`	VIP list definitions
`public.vip_list_members`	Phone numbers and settings
`public.call_center_queue_vip_lists`	Queue-VIP list associations

Key Files

File	Description
`admin/apps/web/src/modules/vipLists/`	Frontend module
`admin/apps/web/src/i18n/en/vipLists.json`	Translations

---

2. Module Overview (Commercial/Business)

Business Value

VIP Lists provide differentiated customer experiences:

Without VIP Lists	With VIP Lists
All callers equal priority	VIP callers prioritized
No caller recognition	Automatic identification
Manual escalation	Automatic queue boost
No tier forcing	Direct to best agents

Use Cases

Enterprise Customers

- Key account phone numbers

- Direct routing to senior agents

Premium Memberships

- Gold/Platinum member numbers

- Higher queue priority

Partner Programs

- Reseller/partner contacts

- Dedicated tier access

Account-Based Service

- Specific customer numbers

- Custom service levels

Feature Highlights

Feature	Benefit
Reusable Lists	One list, multiple queues
Weight Scoring	1-100 priority boost
Level Override	Force specific tier
Position Override	Force queue position
Per-Member Enable	Individual control
Drag-and-Drop	Easy member ordering

---

3. Module Overview (End User/Administrator)

What Can You Do?

Create named VIP lists
Add phone numbers as members
Set priority weights (1-100)
Override tier levels (force to senior agents)
Override queue positions (jump to front)
Assign lists to multiple queues

Administrator Workflow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              Creating a VIP List                                │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  General Settings                                               │
│  ├─ List Name: "Premium Customers"                             │
│  ├─ Description: "High-value enterprise accounts"              │
│  └─ Enabled: ✓                                                 │
│                                                                 │
│  VIP List Members                                               │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ ≡ +15551234567 │ Weight: 50 │ Level: 1 │ Pos: - │ ✓       │  │
│  │ ≡ +15559876543 │ Weight: 30 │ Level: 1 │ Pos: - │ ✓       │  │
│  │ ≡ +15555551212 │ Weight: 20 │ Level: 2 │ Pos: 1 │ ✓       │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
│  [+ Add Member]                                                 │
│                                                                 │
│  Save → Then assign to Queues in Queue settings                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Queue Integration

In Queue settings, select VIP Lists to associate:

Plaintext

Queue Settings → VIP List → Select "Premium Customers"

Quick Tips

TIP

Reusable Lists: Create one "VIP Customers" list and use across multiple queues.

TIP

Weight vs Override: Use weight for relative priority, overrides for absolute control.

CAUTION

Position Override = 1: This puts caller at front of queue—use sparingly.

---

4. Configuration Fields Reference

VIP List Fields

Field	Description	Example
List Name	Unique identifier	`Premium Customers`
Description	Optional description	`Enterprise accounts`
Enabled	List active status	On/Off

VIP Member Fields

Field	Description	Range	Default
Phone Number	Caller ID to match	E.164 format	Required
Weight	Priority score boost	1-100	10
Level Override	Force tier level	1-10 (1=highest)	None
Position Override	Force queue position	1-200 (1=first)	None
Enabled	Member active status	On/Off	On

Field Behaviors

Field	Effect
Weight	Adds to caller's queue score (higher = more priority)
Level Override	Forces caller to specific agent tier (1 = senior agents)
Position Override	Places caller at specific queue position (1 = front)

---

5. Priority Scoring

How VIP Scoring Works

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                  VIP Priority Flow                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. Caller enters queue                                         │
│     Caller ID: +15551234567                                     │
│                                                                 │
│  2. System checks VIP lists assigned to queue                   │
│     → Match found in "Premium Customers" list                   │
│     → Weight: 50, Level Override: 1                             │
│                                                                 │
│  3. Apply VIP settings                                          │
│     ├─ Base score: 0 (new caller)                              │
│     ├─ + Weight: 50                                            │
│     └─ = Final score: 50                                       │
│                                                                 │
│  4. Queue position determined by score                          │
│     → VIP caller (score 50) ahead of regular callers (score 0) │
│                                                                 │
│  5. Tier routing                                                │
│     → Level Override: 1 → try tier 1 agents first              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Priority Matrix

Configuration	Effect
Weight only	Relative priority boost
Level Override only	Force to specific agent tier
Position Override only	Force to specific queue position
Weight + Level	Boost + tier forcing
All three	Maximum VIP treatment

---

6. Common Scenarios & Examples

Scenario 1: Enterprise Accounts

VIP List: "Enterprise"

Phone	Weight	Level	Position
+15551234567	50	1	-
+15559876543	50	1	-
+15555551212	50	1	-

Effect: All enterprise callers get +50 priority and tier 1 agents.

Scenario 2: Tiered Service Levels

VIP List: "Premium Service"

Phone	Weight	Level	Position	Description
+15551111111	100	1	1	CEO
+15552222222	80	1	-	CFO
+15553333333	50	2	-	Directors

Effect: CEO always first, executives to tier 1, directors to tier 2.

Scenario 3: Multi-Queue VIP

VIP List: "Gold Members"

Assigned to:

Sales Queue
Support Queue
Billing Queue

Effect: Gold members get priority across all three queues.

---

7. Limitations & Important Notes

Technical Notes

NOTE

Configuration Module: VIP Lists is a configuration module. List matching occurs during queue entry via mod_callcenter integration.

WARNING

Phone Format: Use consistent format (E.164 recommended: +15551234567).

Best Practices

Use E.164 Format: +[country][number] for consistent matching
Meaningful Weights: Use ranges (10-30-50-80-100) for clear tiers
Level Override Sparingly: Reserve for true VIP
Position Override Rarely: Only for executive-level callers
Name Lists Clearly: "Enterprise Accounts" not "VIP 1"

---

8. Troubleshooting Tips

Common Issues

Symptom	Possible Cause	Solution
VIP not recognized	Phone format mismatch	Use consistent E.164 format
No priority boost	List not assigned to queue	Assign in queue settings
Member not working	Member disabled	Enable the member
List not working	List disabled	Enable the list
Wrong tier	Level override conflict	Check override values

Diagnostic SQL

List VIP lists:

Sql

SELECT id, name, description, enabled
FROM public.vip_lists
WHERE domain_id = [domain_id];

Check VIP members:

Sql

SELECT m.phone_number, m.weight, m.level_override, m.position_override, m.enabled
FROM public.vip_list_members m
JOIN public.vip_lists l ON m.vip_list_id = l.id
WHERE l.domain_id = [domain_id]
ORDER BY l.name, m.weight DESC;

Check queue VIP list assignments:

Sql

SELECT q.name as queue, v.name as vip_list
FROM public.call_center_queue_vip_lists qv
JOIN public.call_center_queues q ON qv.queue_id = q.id
JOIN public.vip_lists v ON qv.vip_list_id = v.id
WHERE q.domain_id = [domain_id];

---

9. Glossary

Term	Definition
VIP List	Collection of priority caller phone numbers
Weight	Priority score boost (1-100)
Level Override	Forces caller to specific agent tier
Position Override	Forces caller to specific queue position
E.164	International phone format (+[country][number])

---

Lua Handler Status

⚡ No Dedicated Handler Required

VIP Lists is a configuration module. The VIP matching is:

Stored in public.vip_lists and public.vip_list_members
Associated with queues via public.call_center_queue_vip_lists
Evaluated by mod_callcenter or queue entry logic during call processing

No Lua fixes needed!

---

Documentation last updated: January 2026

VIP Lists (Queues VIP) Module Documentation

Table of Contents

1. Module Overview (Technical)

What Are VIP Lists?

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

Quick Tips

4. Configuration Fields Reference

VIP List Fields

VIP Member Fields

Field Behaviors

5. Priority Scoring

How VIP Scoring Works

Priority Matrix

6. Common Scenarios & Examples

Scenario 1: Enterprise Accounts

Scenario 2: Tiered Service Levels

Scenario 3: Multi-Queue VIP

7. Limitations & Important Notes

Technical Notes

Best Practices

8. Troubleshooting Tips

Common Issues

Diagnostic SQL

9. Glossary

Lua Handler Status

⚡ No Dedicated Handler Required