Extension Status Module Documentation

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

---

1. Module Overview (Technical)

What Is Extension Status?

Extension Status is a monitoring and quick-configuration dashboard that displays all extensions with their call forwarding status at a glance. Administrators can quickly toggle forwarding features on/off directly from the grid without navigating to individual extension settings.

Architecture

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                 Extension Status System                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │               STATUS GRID VIEW                           │   │
│  ├──────────────────────────────────────────────────────────┤   │
│  │  Extension  │ Boss │ PA │ FM │ DND │ CFI │ CFB │ CFN │CFU │   │
│  │  1001 John  │  ●   │ ●  │ ✓  │  ●  │  ●  │  ✓  │  ✓  │ ● │   │
│  │  1002 Jane  │  ✓   │ ●  │ ●  │  ●  │  ●  │  ●  │  ✓  │ ● │   │
│  │     ...                                                  │   │
│  └──────────────────────────────────────────────────────────┘   │
│                           │                                     │
│        ┌──────────────────┼──────────────────┐                  │
│        ▼                  ▼                  ▼                  │
│  ┌──────────┐      ┌──────────┐      ┌──────────────┐          │
│  │ Toggle   │      │ Devices  │      │ Edit Modal   │          │
│  │ On/Off   │      │ Modal    │      │ (Full Config)│          │
│  └──────────┘      └──────────┘      └──────────────┘          │
│        │                  │                  │                  │
│        ▼                  ▼                  ▼                  │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                    API Layer                             │   │
│  │  GET /extension-status        - List with status        │   │
│  │  PATCH /extension-status/:id/toggle        - Toggle     │   │
│  │  GET /extension-status/:id/details  - Full details      │   │
│  │  GET /extension-status/:id/devices  - Device status     │   │
│  │  PUT /extension-status/:id          - Update settings   │   │
│  └─────────────────────────────────────────────────────────┘    │
│                           │                                     │
│                           ▼                                     │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │              FreeSWITCH ESL                              │   │
│  │  sofia status profile internal reg [extension]          │   │
│  │  → Returns device registrations in real-time            │   │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

Table	Purpose
`public.sip_extensions`	Extension data with enabled/disabled status
`public.call_forwardings`	Call forwarding configuration per extension
`public.personal_assistants`	Personal Assistant key mappings
`public.time_groups`	Time-based forwarding schedules

FreeSWITCH Integration

The module queries FreeSWITCH via ESL to get real-time device registration status:

Lua

sofia status profile internal reg [extension_username]

This returns:

Device IP address and port
User-Agent string (phone model)
Registration status (Registered/Reachable/Unknown)

Key Files

File	Description
`admin/apps/api/src/modules/telephony/extension-status/service.ts`	Backend service with toggle/update logic
`admin/apps/web/src/modules/extensionStatus/ExtensionStatusPage.tsx`	Main dashboard grid
`admin/apps/web/src/modules/extensionStatus/EditStatusModal.tsx`	Detailed configuration modal
`admin/apps/web/src/modules/extensionStatus/DevicesModal.tsx`	Device registration viewer

---

2. Module Overview (Commercial/Business)

Business Value

Extension Status provides operational visibility that reduces support calls:

Without Extension Status	With Extension Status
Users call IT: "My calls aren't coming through"	Admin checks grid: "DND is enabled"
Time to diagnose: 10-15 minutes	Time to diagnose: 5 seconds
Requires accessing individual extension	All statuses visible at once

Use Cases

Helpdesk Support

- Quickly verify if a user has forwarding enabled

- Toggle off accidental DND without editing extension

Supervisor Oversight

- Monitor team's availability status

- Ensure critical extensions are not forwarding away

Compliance Auditing

- Verify call recording and completion settings

- Document extension configurations

Device Troubleshooting

- View which devices are registered

- Check User-Agent for phone model information

Feature Highlights

One-Click Toggle: Enable/disable any forwarding type directly from grid
Visual Status: Green checkmarks vs gray circles instantly show state
Bulk Visibility: See all extensions' status without navigation
Device Info: View registered phones and their network details
Time-Based Rules: Configure forwarding by time groups

---

3. Module Overview (End User/Administrator)

What Can You Do?

View Status Grid: See all extensions with their forwarding status
Toggle Features: Click any status indicator to enable/disable
View Devices: See which phones are registered for each extension
Edit Details: Open modal for full forwarding configuration

User Workflow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                    Administrator Workflow                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. Open Extension Status page                                  │
│     └─ Grid displays all extensions with forwarding status     │
│                                                                 │
│  2. Identify issue at a glance                                  │
│     └─ Extension 1001 has DND enabled (green checkmark)        │
│                                                                 │
│  3. Quick Toggle                                                │
│     ├─ Click the DND indicator for 1001                        │
│     └─ ✓ Indicator changes gray → user can receive calls      │
│                                                                 │
│  4. View Devices (Click phone icon)                             │
│     ├─ Shows: Grandstream GXP2170 @ 192.168.1.45:5060          │
│     └─ Status: Registered ✓                                    │
│                                                                 │
│  5. Edit Full Settings (Click edit icon)                        │
│     ├─ Configure forwarding destinations                       │
│     ├─ Set time groups for conditional forwarding              │
│     └─ Save changes                                            │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Tips

TIP

Color Coding: Green checkmark (✓) = enabled, Gray circle (○) = disabled. Click to toggle!

TIP

Search: Use the search bar to find extensions by number or name.

CAUTION

Toggle Effects Are Immediate: Clicking a status indicator immediately enables/disables that feature—there's no confirmation dialog.

---

4. Status Indicators Reference

Forwarding Types

Abbreviation	Full Name	Description	When Calls Forward
Boss/Secretary	Boss/Secretary Mode	Routes calls through a secretary extension first	All incoming calls
PA	Personal Assistant	IVR menu that asks caller to press keys for different actions	When enabled
FM	Follow-Me	Rings additional destinations (mobile, home) after the extension	After primary ring timeout
DND	Do Not Disturb	Rejects or forwards all calls immediately	All incoming calls
CFI	Call Forward Immediate	Always forwards to a destination	All incoming calls immediately
CFB	Call Forward Busy	Forwards when extension is on a call	When busy
CFN	Call Forward No Answer	Forwards after ring timeout	After [X] seconds no answer
CFU	Call Forward Unreachable	Forwards when device is not registered	When device offline
CC	Call Completion	Enables callback when called extension becomes available	When target was busy/unavailable

Status Indicator States

Visual	State	Meaning
✓ (Green)	Enabled	Feature is active—calls will be affected
○ (Gray)	Disabled	Feature is off—no effect on calls
↻ (Spinning)	Loading	Toggle request in progress

Forwarding Priority

When multiple forwarding types are enabled, they are processed in this order:

Plaintext

1. DND (highest priority - rejects/forwards immediately)
2. CFI (forwards immediately if DND not active)
3. Boss/Secretary (routes through secretary)
4. Personal Assistant (plays IVR if enabled)
5. Follow-Me (additional ring destinations)
6. CFB (if busy)
7. CFN (if no answer after timeout)
8. CFU (if device unreachable)

IMPORTANT

If DND or CFI is enabled, calls bypass most other forwarding logic.

---

5. Operation Flow / Logic Explanation

Toggle Operation Flow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                 Toggle Forwarding Flow                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. Admin clicks status indicator (e.g., DND for ext 1001)      │
│     │                                                           │
│     ▼                                                           │
│  2. Frontend shows loading spinner on that cell                 │
│     │                                                           │
│     ▼                                                           │
│  3. API call: PATCH /extension-status/1001/toggle               │
│     { "forwardType": "dnd", "enabled": true }                   │
│     │                                                           │
│     ▼                                                           │
│  4. Backend updates call_forwardings table:                     │
│     UPDATE call_forwardings                                     │
│     SET dnd_enabled = true, updated_at = NOW()                  │
│     WHERE sip_extension_id = 1001                               │
│     │                                                           │
│     ▼                                                           │
│  5. Returns success response                                    │
│     │                                                           │
│     ▼                                                           │
│  6. Frontend updates grid cell to show new state                │
│     ○ → ✓ (gray to green)                                       │
│     │                                                           │
│     ▼                                                           │
│  7. Toast notification: "Status updated"                        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Device Registration Query Flow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│               Device Registration Query                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. Open Devices Modal for extension 1001                       │
│     │                                                           │
│     ▼                                                           │
│  2. API call: GET /extension-status/1001/devices                │
│     │                                                           │
│     ▼                                                           │
│  3. Backend sends ESL command to FreeSWITCH:                    │
│     sofia status profile internal reg 1001                      │
│     │                                                           │
│     ▼                                                           │
│  4. FreeSWITCH returns registration data:                       │
│     Registrations:                                              │
│     user@domain	sip:1001@192.168.1.45:5060	Registered  │
│     │                                                           │
│     ▼                                                           │
│  5. Backend parses output and returns:                          │
│     [{                                                          │
│       username: "1001",                                         │
│       host: "192.168.1.45",                                     │
│       port: 5060,                                               │
│       status: "Registered",                                     │
│       userAgent: "Grandstream GXP2170/1.0.5.15"                 │
│     }]                                                          │
│     │                                                           │
│     ▼                                                           │
│  6. Modal displays device information                           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

---

6. Common Scenarios & Examples

Scenario 1: User Can't Receive Calls

Issue: User reports "my phone doesn't ring"

Plaintext

1. Open Extension Status
2. Search for user's extension (e.g., 1001)
3. Check status indicators:
   ├─ DND: ✓ (enabled!) → Click to disable
   ├─ CFI: ○ (ok)
   └─ All others: ○ (ok)
4. DND now disabled → user receives calls

Scenario 2: Verify Device Registration

Issue: User's phone may be offline

Plaintext

1. Open Extension Status
2. Find extension 1001
3. Click Phone icon (Devices Modal)
4. Modal shows:
   ├─ Device: Yealink T46U
   ├─ IP: 192.168.1.100:5060
   └─ Status: "Unregistered" ⚠️
5. Diagnose network/phone issue

Scenario 3: Configure After-Hours Forwarding

Issue: Executive needs calls forwarded to mobile after 6 PM

Plaintext

1. Open Extension Status
2. Find executive's extension
3. Click Edit icon
4. Configure CFN (Forward No Answer):
   ├─ Enabled: ✓
   ├─ Destination: +1-555-123-4567
   └─ Time Group: "After Hours (6PM-8AM)"
5. Save → Calls forward to mobile only after hours

---

7. Limitations & Important Notes

Technical Limitations

WARNING

Real-Time Registration Only: Device status is queried live from FreeSWITCH. If ESL connection is down, device status won't display.

WARNING

Toggle History: There's no built-in audit log of toggle changes. Consider enabling general audit logging for compliance.

IMPORTANT

Time Groups Required: For conditional forwarding (by time of day), you must first create Time Groups in the Time Groups module.

Best Practices

Train Users: Explain what each forwarding type does to avoid accidental self-lockouts
Check DND First: 90% of "can't receive calls" issues are DND enabled
Use Time Groups: Instead of manually toggling, use time-based rules
Document Changes: Note why forwarding was enabled for future reference

Security Considerations

CAUTION

Sensitive Data: The Devices modal shows internal IP addresses. Restrict access to trusted administrators.

---

8. Troubleshooting Tips

Common Issues

Symptom	Possible Cause	Solution
Toggle doesn't update	Database constraint	Check call_forwardings table has row for extension
"Devices not found"	ESL connection failed	Verify FreeSWITCH is running and ESL port accessible
Status shows enabled but calls don't forward	Destination not configured	Open Edit modal and verify destination is set
All statuses gray	extension_id mismatch	Verify call_forwardings.sip_extension_id matches

Diagnostic SQL

Check forwarding configuration:

Sql

SELECT 
  e.extension,
  cf.dnd_enabled,
  cf.cfi_enabled, cf.cfi_destination,
  cf.cfb_enabled, cf.cfb_destination,
  cf.cfn_enabled, cf.cfn_destination,
  cf.cfu_enabled, cf.cfu_destination
FROM public.sip_extensions e
LEFT JOIN public.call_forwardings cf ON cf.sip_extension_id = e.id
WHERE e.extension = '1001';

Check if call_forwardings row exists:

Sql

SELECT COUNT(*) 
FROM public.call_forwardings 
WHERE sip_extension_id = [extension_id];
-- Should be 1. If 0, row needs to be created

Manual toggle via SQL (emergency):

Sql

UPDATE public.call_forwardings
SET dnd_enabled = false, updated_at = NOW()
WHERE sip_extension_id = [extension_id];

ESL Diagnostic Commands

Bash

# Check registration directly from fs_cli
fs_cli -x "sofia status profile internal reg 1001"

# Reload directory after changes
fs_cli -x "reloadxml"

---

9. Glossary

Term	Definition
DND	Do Not Disturb - blocks all incoming calls
CFI	Call Forward Immediate - unconditionally forwards all calls
CFB	Call Forward Busy - forwards when extension is on a call
CFN	Call Forward No Answer - forwards after ring timeout
CFU	Call Forward Unreachable - forwards when device is offline
Follow-Me	Rings additional destinations (mobile, etc.) after the primary phone
Personal Assistant	IVR menu for callers to choose where to route their call
Boss/Secretary	Routes calls through a secretary before reaching the boss
Call Completion	Automatically calls back when a previously busy extension becomes free
Time Group	Schedule definition for when forwarding rules apply (e.g., "After Hours")
ESL	Event Socket Library - FreeSWITCH API for real-time commands
User-Agent	String identifying the phone model (e.g., "Grandstream GXP2170/1.0.5.15")

---

10. Suggested UI Improvements

Column	Current Tooltip	Suggested Tooltip
CFI	"CFI"	"Call Forward Immediate - Forwards ALL calls unconditionally. Use with caution!"
CFB	"CFB"	"Call Forward Busy - Forwards calls when you're already on another call."
CFN	"CFN"	"Call Forward No Answer - Forwards if you don't answer within the ring timeout."
CFU	"CFU"	"Call Forward Unreachable - Forwards if your phone is offline or not registered."
DND	"DND"	"Do Not Disturb - Blocks ALL incoming calls. Your phone won't ring."

UX Enhancements

Confirmation for DND/CFI: Add confirmation dialog before enabling these (they have major impact)

Batch Toggle: Select multiple extensions and toggle a feature for all at once

Status Legend: Add a legend/key explaining what each abbreviation means

Last Changed: Show timestamp of when status was last modified

Destination Preview: Show forwarding destination on hover without opening modal

Export Status: Button to export grid as CSV for auditing

Column Visibility Defaults

Consider defaulting some less common columns to hidden:

Call Completion (rarely used)
Boss/Secretary (enterprise feature)

Users can show them via column toggle if needed.

Color Enhancements

Current	Suggested	Reason
Green for enabled	Red for DND enabled	DND is a "block" action, should feel different
Same green for all	Orange for CFI	CFI is unconditional forward, warrants attention

---

Glossary

Term	Definition
Extension Status	Real-time registration and call state of a SIP endpoint

---

Lua Script Status ℹ️

Integration Module

Component	Status	Notes
Extension Status	ℹ️ Configuration module	Registration status retrieved via ESL/Event Socket

--- Documentation last updated: January 2026

Extension Status Module Documentation

Table of Contents

1. Module Overview (Technical)

What Is Extension Status?

Architecture

Key Tables

FreeSWITCH Integration

Key Files

2. Module Overview (Commercial/Business)

Business Value

Use Cases

Feature Highlights

3. Module Overview (End User/Administrator)

What Can You Do?

User Workflow

Quick Tips

4. Status Indicators Reference

Forwarding Types

Status Indicator States

Forwarding Priority

5. Operation Flow / Logic Explanation

Toggle Operation Flow

Device Registration Query Flow

6. Common Scenarios & Examples

Scenario 1: User Can't Receive Calls

Scenario 2: Verify Device Registration

Scenario 3: Configure After-Hours Forwarding

7. Limitations & Important Notes

Technical Limitations

Best Practices

Security Considerations

8. Troubleshooting Tips

Common Issues

Diagnostic SQL

ESL Diagnostic Commands

9. Glossary

10. Suggested UI Improvements

Tooltip Improvements

UX Enhancements

Column Visibility Defaults

Color Enhancements

Glossary

Lua Script Status ℹ️

Integration Module