--- title: "Extension Status Module Documentation" description: "Documentation for Extension Status" --- ## Table of Contents 1. [Module Overview (Technical)](#1-module-overview-technical) 2. [Module Overview (Commercial/Business)](#2-module-overview-commercialbusiness) 3. [Module Overview (End User/Administrator)](#3-module-overview-end-useradministrator) 4. [Status Indicators Reference](#4-status-indicators-reference) 5. [Operation Flow / Logic Explanation](#5-operation-flow--logic-explanation) 6. [Common Scenarios & Examples](#6-common-scenarios--examples) 7. [Model Context Protocol (MCP) AI Integration](#7-model-context-protocol-mcp-ai-integration) 8. [Limitations & Important Notes](#8-limitations--important-notes) 9. [Troubleshooting Tips](#9-troubleshooting-tips) 10. [Glossary](#10-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**: ```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) --- ## 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 1. **Helpdesk Support** - Quickly verify if a user has forwarding enabled - Toggle off accidental DND without editing extension 2. **Supervisor Oversight** - Monitor team's availability status - Ensure critical extensions are not forwarding away 3. **Compliance Auditing** - Verify call recording and completion settings - Document extension configurations 4. **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? 1. **View Status Grid**: See all extensions with their forwarding status 2. **Toggle Features**: Click any status indicator to enable/disable 3. **View Devices**: See which phones are registered for each extension 4. **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 ```json // Tool Call: get_extension_status { "extension": "2001" } ``` **Sample Output Response:** ```json { "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 ```json // Tool Call: list_extensions { "dndOnly": true } ``` **Sample Output Response:** ```json { "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) ```json // Tool Call: set_extension_forwarding { "extension": "2002", "forwardType": "no_answer", "destination": "15552345678", "enabled": true } ``` **Sample Output Response:** ```json { "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 1. **Train Users**: Explain what each forwarding type does to avoid accidental self-lockouts 2. **Check DND First**: 90% of "can't receive calls" issues are DND enabled 3. **Use Time Groups**: Instead of manually toggling, use time-based rules 4. **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:** ```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" ``` --- ## 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*