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
Model Context Protocol (MCP) AI Integration
Limitations & Important Notes
Troubleshooting Tips
Glossary

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

┌─────────────────────────────────────────────────────────────────┐
│                 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   │   │
│  └─────────────────────────────────────────────────────────┘    │
│                           │                                     │
│                           ▼                                     │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │              Telephony Event Socket (ESL)                              │   │
│  │  sofia status profile internal reg [extension]          │   │
│  │  → Returns device registrations in real-time            │   │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Telephony Server Integration

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

sofia status profile internal reg [extension_username]

This returns:

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

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

┌─────────────────────────────────────────────────────────────────┐
│                    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:

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

┌─────────────────────────────────────────────────────────────────┐
│                 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

┌─────────────────────────────────────────────────────────────────┐
│               Device Registration Query                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. Open Devices Modal for extension 1001                       │
│     │                                                           │
│     ▼                                                           │
│  2. API call: GET /extension-status/1001/devices                │
│     │                                                           │
│     ▼                                                           │
│  3. Backend sends ESL command to Telephony Server:                    │
│     sofia status profile internal reg 1001                      │
│     │                                                           │
│     ▼                                                           │
│  4. Telephony Server 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”

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

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

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. Model Context Protocol (MCP) AI Integration

The Extension Status Module serves as the central live observation and call-control dashboard for the Ring2All PBX. Through native Model Context Protocol (MCP) integration, AI Copilots, NOC supervisors, and automated operations bots can monitor live SIP endpoints, detect offline devices, and programmatically toggle call forwarding or Do Not Disturb states without manual UI interaction.

MCP Monitoring Capabilities & Data Sources

The MCP server connects to both relational data stores and the active Telephony Server runtime:

Real-Time SIP Presence & Registration: Queries sofia status profile internal reg via ESL to pull active network IP, port, User-Agent, and lease expiration.
Relational Forwarding Matrix: Inspects and updates public.call_forwardings for immediate (CFI), busy (CFB), and no-answer (CFN) routing destinations.
Do Not Disturb (DND) Control: Reads and updates DND state directly, instantly modifying dialplan behavior in Telephony Server.

Registered MCP Tools for Extension Status

Tool Name	Operation	Description	Key Parameters
`list_extensions`	Directory / Bulk Audit	Returns extension overview with live registration and forwarding status flags. Can filter exclusively for extensions with active forwarding (`forwardingOnly: true`) or DND active (`dndOnly: true`).	`search`, `limit`, `registeredOnly`, `forwardingOnly`, `dndOnly`
`get_extension_status`	Deep Telemetry	Returns live SIP device telemetry (IP address, port, phone model / User-Agent, NAT status, expires) alongside complete forwarding matrix and presence notes.	`extension` (str, required)
`set_extension_forwarding`	Telephony Control	Programmatically activates, updates, or deactivates unconditional (`all`), busy (`busy`), or no-answer (`no_answer`) call forwarding.	`extension` (str, req), `enabled` (bool, req), `destination` (str), `forwardType` (‘all’\|‘busy’\|‘no_answer’)
`set_extension_dnd`	Telephony Control	Programmatically toggles Do Not Disturb (DND) state for an extension.	`extension` (str, req), `enabled` (bool, req)

Tool Schemas & Payloads

1. Inspecting Live SIP Endpoint & Forwarding Matrix

// Tool Call: get_extension_status
{
  "extension": "2001"
}

Sample Output Response:

{
  "success": true,
  "data": {
    "found": true,
    "extension": "2001",
    "name": "Sarah Johnson",
    "contactEmail": "sarah.j@enterprise.com",
    "voicemailEmail": "sarah.j@enterprise.com",
    "enabled": true,
    "type": "sip",
    "ringTimeout": 30,
    "liveRegistration": {
      "status": "ONLINE",
      "ip": "192.168.10.45",
      "port": "5060",
      "userAgent": "Yealink SIP-T46U 108.86.0.70",
      "expires": "3540"
    },
    "callForwarding": {
      "forwardAll": null,
      "onBusy": "2002",
      "noAnswer": "2005"
    },
    "dnd": false,
    "presence": {
      "status": "available",
      "note": null
    }
  }
}

2. Auditing All Extensions with DND Active

// Tool Call: list_extensions
{
  "dndOnly": true
}

Sample Output Response:

{
  "success": true,
  "data": {
    "total": 1,
    "registeredCount": 1,
    "forwardingCount": 0,
    "dndCount": 1,
    "extensions": [
      {
        "extension": "2003",
        "name": "Executive Boardroom",
        "contactEmail": null,
        "voicemailEmail": null,
        "enabled": true,
        "type": "sip",
        "isRegistered": true,
        "registrationIp": "192.168.10.88",
        "userAgent": "Polycom Trio 8800",
        "dnd": true,
        "forwarding": {
          "all": null,
          "busy": null,
          "noAnswer": null,
          "hasActiveForward": false
        },
        "presence": "busy"
      }
    ]
  }
}

3. Toggling Call Forwarding on No Answer (CFN)

// Tool Call: set_extension_forwarding
{
  "extension": "2002",
  "forwardType": "no_answer",
  "destination": "15552345678",
  "enabled": true
}

Sample Output Response:

{
  "success": true,
  "data": {
    "message": "Call forwarding [On No Answer (CFN)] for extension 2002 set to destination 15552345678",
    "extension": "2002",
    "forwardType": "no_answer",
    "forwardingEnabled": true,
    "destination": "15552345678"
  }
}

Conversational Prompts & Chatbot Workflows

Troubleshooting “Can’t Receive Calls”:
- “¿Por qué la extensión 2003 no recibe llamadas?” ➔ get_extension_status({ extension: '2003' })
  - Copilot analysis: “La extensión 2003 tiene el modo No Molestar (DND) activado. ¿Deseas que lo desactive ahora?”
- “Sí, desactívalo por favor.” ➔ set_extension_dnd({ extension: '2003', enabled: false })
Fleet Registration & Endpoint Auditing:
- “Muéstrame cuáles extensiones están registradas y qué teléfonos IP están usando.” ➔ list_extensions({ registeredOnly: true, limit: 20 })
- “¿Cuántas extensiones tienen desvíos de llamada activos?” ➔ list_extensions({ forwardingOnly: true })
Emergency & Remote Office Forwarding:
- “Desvía las llamadas si no contesta la extensión 2001 al número celular 15559876543.” ➔ set_extension_forwarding({ extension: '2001', forwardType: 'no_answer', destination: '15559876543', enabled: true })
- “Cancela todos los desvíos de la extensión 2001.” ➔ set_extension_forwarding({ extension: '2001', forwardType: 'all', enabled: false })

8. Limitations & Important Notes

Technical Limitations

[!WARNING] Real-Time Registration Only: Device status is queried live from Telephony Server. 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.

9. 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 Telephony Server 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:

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:

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):

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

ESL Diagnostic Commands

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

# Reload directory after changes
fs_cli -x "reloadxml"

10. 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 - Telephony Server API for real-time commands
User-Agent	String identifying the phone model (e.g., “Grandstream GXP2170/1.0.5.15”)

Documentation last updated: January 2026

Extension Status Module Documentation

Table of Contents

1. Module Overview (Technical)

What Is Extension Status?

Architecture

Telephony Server Integration

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. Model Context Protocol (MCP) AI Integration

MCP Monitoring Capabilities & Data Sources

Registered MCP Tools for Extension Status

Tool Schemas & Payloads

1. Inspecting Live SIP Endpoint & Forwarding Matrix

2. Auditing All Extensions with DND Active

3. Toggling Call Forwarding on No Answer (CFN)

Conversational Prompts & Chatbot Workflows

8. Limitations & Important Notes

Technical Limitations

Best Practices

Security Considerations

9. Troubleshooting Tips

Common Issues

Diagnostic SQL

ESL Diagnostic Commands

10. Glossary