Pickup Groups Module Documentation

Module Overview (Technical)
Module Overview (Commercial/Business)
Module Overview (End User/Administrator)
Configuration Fields Reference
Call Flow / Logic Explanation
Common Scenarios & Examples
Limitations & Important Notes
Troubleshooting Tips
Glossary
Suggested UI Improvements

---

1. Module Overview (Technical)

What Are Pickup Groups?

Pickup Groups allow extensions to intercept (pick up) calls ringing at other extensions in the same group. When a call rings at extension 1001, extension 1002 can dial a pickup code to answer it.

Architecture

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                    Pickup Group System                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Incoming call rings at Extension 1001                          │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              1001 is ringing...                          │   │
│  │              (part of "Sales" pickup group)              │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
│  Extension 1002 (also in "Sales" group) dials *8                │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              Pickup Logic                                │   │
│  │                                                          │   │
│  │  1. Find pickup groups where 1002 has allowPickup=true   │   │
│  │  2. Check if any member in those groups is ringing       │   │
│  │  3. Found: 1001 is ringing                               │   │
│  │  4. Check skipBusy, DND override, etc.                   │   │
│  │  5. Intercept call → Bridge to 1002                      │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼                                                         │
│  1002 is now connected to the caller                            │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

Table	Purpose
`public.pickup_groups`	Group definitions (name, settings)
`public.pickup_group_members`	Extension memberships with permissions

Member Permissions

Permission	Description
isMember	Extension belongs to the group (calls can be picked up FROM this extension)
allowPickup	Extension can pick up calls FROM other group members

Key Files

File	Description
`admin/apps/web/src/modules/pickupGroups/`	Frontend module
`admin/apps/web/src/i18n/en/pickupGroups.json`	English translations
`telephony/freeswitch/lua/main/pickup/`	Pickup handlers

---

2. Module Overview (Commercial/Business)

Business Value

Pickup Groups enable collaborative call handling:

Without Pickup Groups	With Pickup Groups
Missed calls when away from desk	Coworker can answer
Need to forward to coworker	Simply pick up ringing call
Caller waits or hangs up	Faster response time

Use Cases

Team Coverage

- Sales team can pick up each other's calls

- Support team covers during breaks

Reception Backup

- Any front desk staff can answer reception

Department Isolation

- Sales can only pick up Sales calls

- Support can only pick up Support calls

Manager Assistance

- Executive assistant can pick up boss's calls

Feature Highlights

Feature	Benefit
Skip Busy	Don't interrupt ongoing calls
DND Override	Pick up even if target is in DND
Pickup Tone	Audio confirmation of pickup
Confirmation	Require DTMF to confirm pickup
Priority	Control which group is checked first

---

3. Module Overview (End User/Administrator)

What Can You Do?

Create pickup groups with member extensions
Define who can pick up calls vs. who can only be picked up
Configure pickup behavior (tones, timeout, confirmations)
Set priority for conflict resolution

Administrator Workflow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                 Creating a Pickup Group                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Step 1: General Tab                                            │
│  ├─ Name: "Sales Team"                                         │
│  ├─ Description: "Sales department pickup group"               │
│  └─ Priority: 10                                               │
│                                                                 │
│  Step 2: Settings Tab                                           │
│  ├─ Skip Busy: ✓ (don't interrupt active calls)                │
│  ├─ DND Override: ✗ (respect DND settings)                     │
│  ├─ Pickup Tone: Beep                                          │
│  └─ Pickup Timeout: 30 seconds                                 │
│                                                                 │
│  Step 3: Members Tab                                            │
│  ├─ Extension 1001: isMember ✓, allowPickup ✓                  │
│  ├─ Extension 1002: isMember ✓, allowPickup ✓                  │
│  ├─ Extension 1003: isMember ✓, allowPickup ✓                  │
│  └─ Extension 1004: isMember ✓, allowPickup ✗ (pickup target)  │
│                                                                 │
│  Step 4: Enable and Save                                        │
│  └─ Enabled: ✓                                                 │
│                                                                 │
│  Result: 1001-1003 can pick up each other's calls + 1004's     │
│          1004 can be picked up but cannot pick up others       │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Tips

TIP

allowPickup = false: Use this for extensions that should only be "pickup targets" (e.g., lobby phone that anyone can answer).

TIP

Skip Busy: Always enable unless you specifically want to interrupt active calls.

CAUTION

Multiple Groups: An extension can be in multiple groups. Priority determines which group is checked first.

---

4. Configuration Fields Reference

General Tab

Field	Description	Example	Required
Name	Group name	`Sales Team`	Yes
Description	Internal notes	`Sales department`	No
Context	Dialplan context	Auto-generated	No
Priority	Conflict resolution order	10 (lower = higher priority)	Yes
Enabled	Active/inactive	On/Off	Yes

Settings Tab

Field	Description	Default	Options
Skip Busy	Skip busy extensions	On	On/Off
DND Override	Override Do Not Disturb	Off	On/Off
Pickup Tone	Confirmation sound	Default	Default, Beep, Short Beep, None
Ringback	Ringback while picking up	Local	Local, US Ring, UK Ring, None
Require Confirmation	DTMF to confirm	Off	On/Off
Pickup Timeout	Max wait time (seconds)	30	5-120

Members Tab

Field	Description
Extension	The extension number
isMember	Calls to this extension can be picked up by others
allowPickup	This extension can pick up calls from group members

Member Permission Matrix

isMember	allowPickup	Result
✓	✓	Full participant—can pick up and be picked up
✓	✗	Target only—can be picked up but cannot pick up others
✗	✓	Picker only—can pick up but cannot be picked up
✗	✗	(Invalid—effectively not in the group)

---

5. Call Flow / Logic Explanation

Pickup Flow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                    Group Pickup Flow (*8)                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. User 1002 dials *8 (group pickup)                           │
│     │                                                           │
│     ▼                                                           │
│  2. Find pickup groups where 1002 has allowPickup = true        │
│     │                                                           │
│     ▼                                                           │
│  3. For each group (in priority order):                         │
│     ├─ Find members with isMember = true                        │
│     ├─ Check if any member is currently ringing                 │
│     ├─ If skipBusy = true, skip busy members                   │
│     └─ If found ringing member → Step 4                        │
│     │                                                           │
│     ▼                                                           │
│  4. Check additional conditions                                 │
│     ├─ If target has DND and dndOverride = false → Skip        │
│     └─ If confirmation required → Prompt DTMF                  │
│     │                                                           │
│     ▼                                                           │
│  5. Intercept the ringing call                                  │
│     ├─ Stop ringing at original extension                       │
│     ├─ Play pickup tone                                         │
│     └─ Bridge caller to 1002                                   │
│     │                                                           │
│     ▼                                                           │
│  6. Call connected between caller and 1002                      │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Direct Pickup Flow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                 Direct Pickup Flow (**1001)                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. User 1002 dials **1001 (direct pickup)                      │
│     │                                                           │
│     ▼                                                           │
│  2. Check if 1002 is in a group where 1001 is also a member     │
│     ├─ Yes → Check if 1002 has allowPickup = true              │
│     └─ No → "Pickup not allowed"                               │
│     │                                                           │
│     ▼                                                           │
│  3. Check if 1001 is currently ringing                          │
│     ├─ Yes → Intercept call                                    │
│     └─ No → "No call to pick up"                               │
│     │                                                           │
│     ▼                                                           │
│  4. Call connected                                              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

---

6. Common Scenarios & Examples

Scenario 1: Sales Team Full Coverage

Setup:

Member	isMember	allowPickup
1001 (Sales Rep 1)	✓	✓
1002 (Sales Rep 2)	✓	✓
1003 (Sales Rep 3)	✓	✓

Result: All three can pick up each other's calls.

Scenario 2: Reception Backup

Setup:

Member	isMember	allowPickup	Notes
1000 (Reception)	✓	✗	Can be picked up but not pick up
2001 (Admin 1)	✓	✓	Can pick up reception
2002 (Admin 2)	✓	✓	Can pick up reception

Result: Admins can answer reception calls; reception cannot pick up others.

Scenario 3: Executive Assistant

Setup:

Member	isMember	allowPickup	Notes
5000 (CEO)	✓	✗	CEO can be picked up
5001 (Assistant)	✗	✓	Assistant can pick up CEO

Result: Only the assistant can pick up the CEO's calls; CEO's calls don't affect the assistant's line.

Scenario 4: Priority Between Groups

Problem: Extension 2000 is in both "Sales" (priority 10) and "Support" (priority 20) groups. When 2000 dials 8:
Check "Sales" group first (priority 10)

If no ringing calls, check "Support" group (priority 20)

Pick up first ringing call found

---

7. Limitations & Important Notes

Technical Limitations

WARNING
Single Ringing Call: If multiple extensions are ringing, only one call is picked up per 8 dial.

WARNING

Priority Matters: Lower priority number = checked first. Plan your priorities carefully.

IMPORTANT

Pickup Codes: Default codes are 8 (group) and (direct). These are configured in Feature Codes.

Symptom	Possible Cause	Solution
"No call to pick up"	No ringing call in group	Verify member is actually ringing
Can't pick up specific ext	allowPickup = false	Check member permissions
Wrong call picked up	Priority order	Adjust group priorities
Pickup not working	Feature code disabled	Check 8 is enabled
DND blocking pickup	dndOverride = false	Enable DND override if needed

Term	Definition
Pickup Group	A set of extensions that can intercept each other's ringing calls
Group Pickup	Dialing 8 to pick up any ringing call in your groups
Direct Pickup	Dialing 1001 to pick up a specific extension's call
isMember	Permission that allows calls TO this extension to be picked up
allowPickup	Permission that allows this extension to pick up others' calls
Skip Busy	Don't interrupt extensions on active calls
DND Override	Allow pickup even if target has Do Not Disturb enabled
Priority	Order in which groups are checked (lower = first)
Pickup Tone	Audio confirmation when pickup is successful
Intercept	Technical term for picking up another extension's call

Best Practices

Use Descriptive Names: "Sales Team" not "Group 1"

Set Appropriate Priorities: Consider which groups should be checked first

Enable Skip Busy: Unless you need to interrupt active calls

Test Permissions: Verify who can pick up whom

Review Regularly: Remove departed employees from groups

Security Considerations

CAUTION
Privacy: Pickup groups allow anyone in the group to intercept calls. Consider confidentiality needs.

---

8. Troubleshooting Tips

Common Issues

Symptom Possible Cause Solution
"No call to pick up" No ringing call in group Verify member is actually ringing
Can't pick up specific ext allowPickup = false Check member permissions
Wrong call picked up Priority order Adjust group priorities
Pickup not working Feature code disabled Check 8 is enabled
DND blocking pickup dndOverride = false Enable DND override if needed
Diagnostic SQL
List pickup groups:
Sql
SELECT pg.name, pg.priority, pg.enabled, COUNT(m.id) as member_count FROM public.pickup_groups pg LEFT JOIN public.pickup_group_members m ON pg.id = m.pickup_group_id WHERE pg.domain_id = [domain_id] GROUP BY pg.id ORDER BY pg.priority;

Check extension's groups:
Sql
SELECT pg.name, pgm.is_member, pgm.allow_pickup FROM public.pickup_group_members pgm JOIN public.pickup_groups pg ON pgm.pickup_group_id = pg.id WHERE pgm.extension = '1001' AND pg.domain_id = [domain_id];

Find ringing extensions (runtime):
Bash
fs_cli -x "show channels" | grep RINGING

---

9. Glossary

Term Definition
Pickup Group A set of extensions that can intercept each other's ringing calls
Group Pickup Dialing 8 to pick up any ringing call in your groups
Direct Pickup Dialing 1001 to pick up a specific extension's call
isMember Permission that allows calls TO this extension to be picked up
allowPickup Permission that allows this extension to pick up others' calls
Skip Busy Don't interrupt extensions on active calls
DND Override Allow pickup even if target has Do Not Disturb enabled
Priority Order in which groups are checked (lower = first)
Pickup Tone Audio confirmation when pickup is successful
Intercept Technical term for picking up another extension's call
---
10. Suggested UI Improvements

The existing i18n tooltips are comprehensive.

UX Enhancements

Visual Permission Matrix: Show grid of who can pick up whom

Quick Test: "Test pickup" button to verify configuration

Member Suggestions: Show frequently called extensions as suggested members

Conflict Detection: Warn if extension is in multiple groups with same priority

Active Indicator: Show which members are currently ringing (real-time)

Current	Suggested
Plain member list	Permission badges (Can Pick Up / Target Only)
Priority number	Priority label (High / Medium / Low)
Simple toggle	Color-coded enabled/disabled

Component	Status	Notes
Pickup Groups	ℹ️ Configuration module	Call pickup managed natively by FreeSWITCH core

Visual Improvements

Current Suggested
Plain member list Permission badges (Can Pick Up / Target Only)
Priority number Priority label (High / Medium / Low)
Simple toggle Color-coded enabled/disabled
---

Lua Script Status ℹ️

Integration Module

Component Status Notes
Pickup Groups ℹ️ Configuration module Call pickup managed natively by FreeSWITCH core
---

Documentation last updated: January 2026*

Pickup Groups Module Documentation

Table of Contents

1. Module Overview (Technical)

What Are Pickup Groups?

Architecture

Key Tables

Member Permissions

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

General Tab

Settings Tab

Members Tab

Member Permission Matrix

5. Call Flow / Logic Explanation

Pickup Flow

Direct Pickup Flow

6. Common Scenarios & Examples

Scenario 1: Sales Team Full Coverage

Scenario 2: Reception Backup

Scenario 3: Executive Assistant

Scenario 4: Priority Between Groups

7. Limitations & Important Notes

Technical Limitations

Best Practices

Security Considerations

8. Troubleshooting Tips

Common Issues

Diagnostic SQL

9. Glossary

10. Suggested UI Improvements

The existing i18n tooltips are comprehensive.

UX Enhancements

Visual Improvements

Lua Script Status ℹ️

Integration Module