Ring Groups Module Documentation

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

---

1. Module Overview (Technical)

What Are Ring Groups?

Ring Groups distribute incoming calls to multiple destinations based on configurable strategies. When a call reaches a ring group extension, the system rings members simultaneously, sequentially, or in other patterns until someone answers or timeout occurs.

Architecture

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                   Ring Group System                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Caller dials Ring Group extension (e.g., 2000)                 │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              Load Ring Group                             │   │
│  │  SELECT * FROM public.ring_groups                        │   │
│  │  WHERE extension = '2000' AND enabled = TRUE             │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              Load Members                                │   │
│  │  SELECT extension, delay, timeout                        │   │
│  │  FROM public.ring_group_members                          │   │
│  │  ORDER BY order_index                                    │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              Apply Strategy                              │   │
│  │                                                          │   │
│  │  Simultaneous: Ring all at once                          │   │
│  │  Sequence: Ring one by one                               │   │
│  │  Enterprise: Cascade with delays                         │   │
│  │  Random: Random order                                    │   │
│  │  Rollover: First available                               │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼                                                         │
│  Member answers OR Timeout → Fallback Destination               │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

Table	Purpose
`public.ring_groups`	Ring group definitions
`public.ring_group_members`	Member extensions and settings
`public.ring_group_settings`	Additional configuration

Key Files

File	Description
`admin/apps/web/src/modules/ringGroups/`	Frontend module
`admin/apps/web/src/i18n/en/ringGroups.json`	Translations
`telephony/freeswitch/lua/main/xml_handlers/ring_group/ring_group.lua`	Main handler
`telephony/freeswitch/lua/main/xml_handlers/routing/ring_group.lua`	Routing handler

---

2. Module Overview (Commercial/Business)

Business Value

Ring Groups enable team-based call handling:

Without Ring Groups	With Ring Groups
Single-line per person	Team shares one number
Missed calls frequent	Multiple coverage
No routing control	Flexible strategies
Manual call forwarding	Automatic distribution

Use Cases

Sales Teams

- All sales reps ring simultaneously

- First available takes the call

Support Departments

- Sequential ringing by priority

- Escalation through tiers

After-Hours Coverage

- Ring primary, then backup

- Fallback to voicemail

Reception Backup

- Reception rings first

- After 15 sec, add backup staff

Feature Highlights

Feature	Benefit
5 Strategies	Simultaneous, Sequence, Enterprise, Random, Rollover
Skip Busy	Avoid disrupting calls in progress
Caller ID Prefix	Identify call source
Per-Member Delay/Timeout	Granular timing control
Call Screening	Require confirmation
Recording	Record all group calls
Follow-Me	Respect member forwarding
Fallback Destination	Route unanswered calls

---

3. Module Overview (End User/Administrator)

What Can You Do?

Create ring groups with extensions
Add members with individual timing
Configure ring strategies
Set caller ID prefixes
Enable call recording
Configure timeout destinations

Administrator Workflow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              Creating a Ring Group                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Step 1: Basic Information                                      │
│  ├─ Group Name: "Sales Team"                                   │
│  ├─ Extension: 2000                                            │
│  └─ Strategy: Simultaneous                                     │
│                                                                 │
│  Step 2: Caller Experience                                      │
│  ├─ Greeting: sales_greeting.wav                               │
│  ├─ Ringback: Music on Hold                                    │
│  └─ Caller ID Prefix: "Sales:"                                 │
│                                                                 │
│  Step 3: Members                                                │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ Member 1: 101 (Alice) | Delay: 0s | Timeout: 20s          │  │
│  │ Member 2: 102 (Bob)   | Delay: 0s | Timeout: 20s          │  │
│  │ Member 3: 103 (Carol) | Delay: 0s | Timeout: 20s          │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
│  Step 4: Timeout Destination                                    │
│  └─ Module: Voicemail | Destination: 101                       │
│                                                                 │
│  Step 5: Save                                                   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Tips

TIP

Strategy Choice: Use Simultaneous for small teams, Sequence for escalation.

TIP

Caller ID Prefix: Add "Sales:" so members know call origin.

CAUTION

No Members = Fast Busy: Always have at least one member.

---

4. Configuration Fields Reference

Ring Group Fields

Field	Description	Example
Group Name	Unique identifier	`Sales Team`
Extension	Dialable number	`2000`
Strategy	Call distribution method	Simultaneous
Ring Timeout	Seconds per round	`30`
Skip Busy	Skip busy members	On/Off
Timeout Destination	Where to route unans calls	Voicemail/IVR
Enabled	Group active status	On/Off

Caller Experience Fields

Field	Description
Greeting	Audio played before ringing
Ringback	What caller hears while waiting
Caller ID Name Prefix	Prefix for caller ID name
Caller ID Number Prefix	Prefix for caller ID number
Distinctive Ring	Custom ring pattern

Behavior Fields

Field	Description
Call Screen	Require member key press
Call Forward	Respect user's CF settings
Follow Me	Respect Follow-Me configs
Missed Call Action	Email/SMS on missed
Record	Record group calls

---

5. Ring Strategies

Strategy Comparison

Strategy	Behavior	Best For
Simultaneous	Ring all members at once	Small teams, fast answer
Sequence	Ring one at a time, in order	Escalation, priority
Enterprise	Cascade with configurable delays	Mixed availability
Random	Random member selection	Load balancing
Rollover	First available member	Simple backup

Visual Comparison

Plaintext

Simultaneous:
─────────────────────────────
  101 ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
  102 ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
  103 ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
       0────────────────────→ time

Sequence:
─────────────────────────────
  101 ▓▓▓▓▓▓▓░░░░░░░░░░░░░░
  102 ░░░░░░░▓▓▓▓▓▓▓░░░░░░░
  103 ░░░░░░░░░░░░░░▓▓▓▓▓▓▓
       0────────────────────→ time

Enterprise (with delays):
─────────────────────────────
  101 ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
  102 ░░░░▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
  103 ░░░░░░░░▓▓▓▓▓▓▓▓▓▓▓▓▓
       0────────────────────→ time

---

6. Member Configuration

Member Fields

Field	Description	Example
Destination	Extension or dial string	`101`
Order	Sequence priority	1, 2, 3...
Delay (sec)	Wait before ringing	`0`, `5`, `10`
Timeout (sec)	Per-member ring time	`20`
Confirm Prompt	Require key press	None/Confirm
Enabled	Member active status	On/Off

Delay Examples

Immediate Ring All:

Member	Delay	Effect
101	0	Rings immediately
102	0	Rings immediately
103	0	Rings immediately

Cascading Ring:

Member	Delay	Effect
101	0	Rings immediately
102	5	Joins after 5 sec
103	10	Joins after 10 sec

---

7. Common Scenarios & Examples

Scenario 1: Sales Team (Simultaneous)

Configuration:

Extension: 5000
Strategy: Simultaneous
Timeout: 20 sec

Members:

Order	Extension	Timeout
1	201	20
2	202	20
3	203	20

Result: All 3 ring at once. First answer wins.

Scenario 2: Tiered Support (Sequence)

Configuration:

Extension: 5001
Strategy: Sequence
Timeout: 60 sec

Members:

Order	Extension	Timeout	Description
1	301	15	Tier 1
2	302	15	Tier 2
3	303	15	Supervisor

Result: Rings 301 for 15s, then 302 for 15s, then 303.

Scenario 3: Cascading Reception (Enterprise)

Configuration:

Extension: 5002
Strategy: Enterprise

Members:

Order	Extension	Delay	Timeout	Description
1	100	0	30	Primary Receptionist
2	101	10	20	Backup 1
3	102	15	15	Backup 2

Result: 100 rings immediately. After 10s, 101 joins. After 15s, 102 joins.

---

8. Limitations & Important Notes

Technical Limitations

WARNING

Member Limit: Performance may degrade with 20+ simultaneous members.

WARNING

External Destinations: External numbers may have carrier delays.

Best Practices

Reasonable Timeouts: 15-30 sec per member
Skip Busy: Enable to avoid disruption
Fallback Required: Always set timeout destination
Test Strategies: Verify behavior before production
Monitor Usage: Check CDR for answer rates

---

9. Troubleshooting Tips

Common Issues

Symptom	Possible Cause	Solution
No ringing	No members	Add members
Fast busy	Group disabled	Enable group
Wrong order	Order not set	Reorder members
Caller hears silence	Ringback not set	Configure ringback
Calls not answered	Timeout too short	Increase timeout

Diagnostic SQL

List ring groups:

Sql

SELECT id, extension, name, strategy, ring_timeout, enabled
FROM public.ring_groups
WHERE domain_id = [domain_id];

Check members:

Sql

SELECT m.extension, m.order_index, m.delay, m.timeout, m.enabled
FROM public.ring_group_members m
WHERE m.ring_group_id = [ring_group_id]
ORDER BY m.order_index;

---

10. Glossary

Term	Definition
Ring Group	Collection of extensions sharing calls
Strategy	Algorithm for distributing calls
Delay	Wait time before member starts ringing
Timeout	Max ring time per member
Fallback	Destination for unanswered calls
Skip Busy	Ignore members on other calls
Call Screen	Require member confirmation
Cascade	Gradually add ringing members

---

Lua Script Status ✅

Fixed Issues

Issue	Before	After
Schema	`core.ring_groups`	`public.ring_groups`
Domain lookup	`core.tenants`	`public.domains`
Members table	`core.ring_group_members`	`public.ring_group_members`
Settings table	`core.ring_group_settings`	`public.ring_group_settings`
Variable naming	`tenant_id`	`domain_id`

--- Documentation last updated: January 2026

Ring Groups Module Documentation

Table of Contents

1. Module Overview (Technical)

What Are Ring Groups?

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

Quick Tips

4. Configuration Fields Reference

Ring Group Fields

Caller Experience Fields

Behavior Fields

5. Ring Strategies

Strategy Comparison

Visual Comparison

6. Member Configuration

Member Fields

Delay Examples

7. Common Scenarios & Examples

Scenario 1: Sales Team (Simultaneous)

Scenario 2: Tiered Support (Sequence)

Scenario 3: Cascading Reception (Enterprise)

8. Limitations & Important Notes

Technical Limitations

Best Practices

9. Troubleshooting Tips

Common Issues

Diagnostic SQL

10. Glossary

Lua Script Status ✅

Fixed Issues