--- title: "Hot Desking Module Documentation" description: "Documentation for Hot Desking" --- ## 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. [Configuration Fields Reference](#4-configuration-fields-reference) 5. [Call Flow / Logic Explanation](#5-call-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 Hot Desking? Hot Desking is a telephony feature that allows a **shared physical device** (IP phone) to be temporarily associated with a **user's extension**. The device can be used by different users throughout the day without requiring hardware reconfiguration. ### Architecture ``` ┌─────────────────────────────────────────────────────────────────┐ │ Hot Desking System │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ ┌───────────────┐ ┌──────────────┐ ┌─────────────────┐ │ │ │ SIP Device │───→│ Feature │───→│ Lua Handler │ │ │ │ (type= │ │ Code *80 │ │ hotdesking.lua │ │ │ │ hotdesk) │ └──────────────┘ └────────┬────────┘ │ │ └───────────────┘ │ │ │ ▼ │ │ ┌──────────────────────┐ │ │ │ Database Updates │ │ │ │ ├─ sip_devices │ │ │ │ │ (extension_id) │ │ │ │ └─ hot_desk │ │ │ │ (session log) │ │ │ └──────────────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────────┐ │ │ │ XML Regeneration │ │ │ │ generate_sip_device │ │ │ │ _xml() │ │ │ └──────────────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────────┐ │ │ │ Telephony Server │ │ │ │ reloadxml │ │ │ │ Device re-registers │ │ │ └──────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Telephony Server Integration - **Feature Code**: `*80` triggers `hotdesking.lua` - **Login Flow**: User enters extension + feature password → device associates with extension - **Logout Flow**: Same code `*80` when logged in → device disassociates - **XML Handling**: Device XML is **regenerated synchronously** to avoid race conditions - **Registration**: After login/logout, `reloadxml` forces device re-registration with new settings --- ## 🎯 User Roles & Key Capabilities | User Role | Key Capabilities & Permissions | |-----------|--------------------------------| | **PBX Super Admin** | Provision hot desk physical SIP devices, assign SIP profiles, configure E911 dispatch locations, and oversee system-wide hot desk sessions. | | **Domain Administrator** | Create and configure domain-specific hot desk hardware, manage device passwords and codec preferences, and audit active user logins. | | **Shift Supervisor / Floor Manager** | Track active hot desk assignments across physical workstations and verify agent presence during shift changeovers. | | **Mobile Worker / Shift Worker** | Approach any physical hot desk SIP phone, dial `*80`, enter extension number and feature PIN to activate their personal extension, contacts, and BLF keys. Dial `*80` again to log out. | --- ## 2. Module Overview (Commercial/Business) ### Business Value Hot Desking addresses several enterprise needs: | Need | Solution | |------|----------| | **Shared Workspaces** | Multiple shifts share the same physical phones | | **Cost Reduction** | Fewer phones needed; 100 users can share 50 devices | | **Flexibility** | Employees can sit anywhere and get their calls | | **Security** | Automatic logout prevents unauthorized access | | **Audit Trail** | Login/logout history for compliance and billing | ### Target Markets 1. **Call Centers**: Agents on rotating shifts share desks 2. **Healthcare**: Doctors/nurses move between stations 3. **Coworking Spaces**: Hot desk members use any available phone 4. **Retail**: Staff use phones in different areas throughout the day 5. **Enterprises with Hybrid Work**: Employees don't have permanent desks ### Licensing Considerations - Each **Hot Desk Device** can be counted separately from regular extensions - The **Extension** maintains its licensed features regardless of which device it uses - Consider offering this as a **premium feature** for enterprise customers --- ## 3. Module Overview (End User/Administrator) ### What Can You Do? As an administrator, you can: 1. **Create Hot Desk Devices** — Physical phones designated for shared use 2. **Manage Device Settings** — SIP credentials, codecs, DTMF mode 3. **Monitor Sessions** — See who is logged in to which device 4. **Configure Extensions for Hot Desking** — Mark extensions as `type='hotdesk'` or `type='none'` ### User Workflow ``` ┌─────────────────────────────────────────────────────────────────┐ │ End User Experience │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Morning: Employee arrives at work │ │ ├─ Picks any available hot desk phone │ │ ├─ Dials *80 │ │ ├─ Enters their extension number (e.g., 1001) │ │ ├─ Enters their feature password (e.g., 1234) │ │ └─ ✅ Phone now acts as extension 1001 │ │ • Incoming calls ring this phone │ │ • Caller ID shows as 1001 │ │ • Voicemail accessible │ │ • BLF keys work │ │ │ │ Evening: Employee leaves │ │ ├─ Dials *80 (no prompts, instant logout) │ │ └─ ✅ Phone returns to basic hot desk mode │ │ • Ready for the next user │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Quick Tips > [!TIP] > **For Administrators**: Create hot desk devices with descriptive names like `HD-FLOOR2-01` to make identification easy. > [!TIP] > **For Users**: Always dial `*80` before leaving to ensure your extension is logged out. --- ## 4. Configuration Fields Reference ### Device Information FormBox (`HotDeskingDeviceInfoBox`) The Hot Desking device form provides a unified 4-column layout configuring the shared hardware endpoint: | Field | Technical Description | User-Friendly Tooltip | Example | Notes | |-------|----------------------|----------------------|---------|-------| | **Username \*** | SIP authentication username in `sip_devices.username`. | The unique SIP identifier for this physical phone. | `HD-100`, `hotdesk-lobby` | Must be unique within the domain. Immutable in edit mode. | | **Description** | Human-readable label in `sip_devices.description`. | A friendly name identifying the physical desk or station. | `Floor 2 Hot Desk`, `Lobby Station 1` | Recommended for asset inventory management. | | **Password \*** | SIP digest password in `sip_devices.password`. | Security password used by the IP phone to register. | `SecureP@ss2026` | 8-15 characters recommended. Includes auto-generate PIN tool. | | **SIP Profile** | Links to `sip_devices.sip_profile_id`. Sofia profile handling SIP traffic. | The network profile this phone uses to connect. | `internal` | Typically `internal` for LAN endpoints. | | **E911 Location** | Links to `dispatch_locations.id`. Physical address for emergency dispatch. | Physical dispatchable location for E911 compliance (RAY BAUM's Act). | `Building B - Floor 2 East` | Bound to emergency 911 calls made from this shared physical unit. | | **Max Registrations** | Maximum simultaneous REGISTER bindings allowed. | How many devices can register with this username at once. | `1` | Usually 1 to ensure single hardware binding per station. | | **DTMF Mode** | DTMF signaling method (`rfc4733`, `inband`, `info`, `auto`). | How the phone sends touch-tone digits. | `rfc4733` | RFC 4733 is the recommended industry standard. | | **Language** | Voice prompt language when no user is logged in. | Language for voice prompts when the phone is in idle hot desk mode. | `en-us-emma`, `es-us-paloma` | Prompts for extension & password during `*80` login. | | **Codecs** | Synchronized audio/video codec preference list. | Audio quality settings applied to calls through this physical phone. | `PCMU,PCMA,G722` | Single selector configuring both inbound and outbound codec preferences. | | **Enabled** | Master toggle for device functionality in `sip_devices.enabled`. | Turn this phone on or off without deleting it. | `true` | Inactive devices cannot register or dial `*80`. | --- ## 5. Call Flow / Logic Explanation ### Login Flow (User Dials `*80`) ``` ┌─────────────────────────────────────────────────────────────────┐ │ Hot Desk Login Flow │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ 1. User dials *80 from hot desk device │ │ │ │ │ ▼ │ │ 2. hotdesking.lua verifies device type = 'hotdesk' │ │ │ │ │ ├─ ❌ Not hotdesk → Play error, hang up │ │ │ │ │ ▼ │ │ 3. Check if device has current extension_id │ │ │ │ │ ├─ Yes → Logout flow (see below) │ │ │ │ │ ▼ │ │ 4. Prompt: "Please enter your extension number" │ │ │ │ │ ▼ │ │ 5. User enters extension (e.g., 1001#) │ │ │ │ │ ▼ │ │ 6. Validate extension exists in sip_extensions │ │ ├─ Type must be 'hotdesk', 'none', or empty │ │ ├─ Extension must be enabled │ │ │ │ │ ├─ ❌ Invalid → Play error, hang up │ │ │ │ │ ▼ │ │ 7. Prompt: "Please enter your feature password" │ │ │ │ │ ▼ │ │ 8. User enters password (e.g., 1234#) │ │ │ │ │ ▼ │ │ 9. Validate password against extension's features_password │ │ │ │ │ ├─ ❌ Wrong → Play "invalid password", hang up │ │ │ │ │ ▼ │ │ 10. UPDATE sip_devices SET extension_id = [ext_id] │ │ │ │ │ ▼ │ │ 11. UPDATE sip_devices SET xml_config = generate_sip_device_xml │ │ │ ⚡ Synchronous regeneration (avoids race condition) │ │ │ │ │ ▼ │ │ 12. INSERT INTO hot_desk (login session record) │ │ │ │ │ ▼ │ │ 13. Telephony Server: reloadxml │ │ │ │ │ ▼ │ │ 14. Device re-registers with new XML │ │ ├─ Gets extension's caller ID │ │ ├─ Gets extension's voicemail │ │ ├─ Gets extension's BLF entries │ │ │ │ │ ▼ │ │ 15. Play: "Hot desk login successful" │ │ │ │ │ ▼ │ │ ✅ User can now make/receive calls as their extension │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Logout Flow (User Dials `*80` When Logged In) ``` ┌─────────────────────────────────────────────────────────────────┐ │ Hot Desk Logout Flow │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ 1. User dials *80 from hot desk device (already logged in) │ │ │ │ │ ▼ │ │ 2. hotdesking.lua detects extension_id is set │ │ │ │ │ ▼ │ │ 3. UPDATE sip_devices SET extension_id = NULL │ │ │ │ │ ▼ │ │ 4. UPDATE sip_devices SET xml_config = generate_sip_device_xml │ │ │ (XML now in basic hot desk mode) │ │ │ │ │ ▼ │ │ 5. UPDATE hot_desk SET enabled = FALSE, logout_time = NOW() │ │ │ │ │ ▼ │ │ 6. Telephony Server: reloadxml │ │ │ │ │ ▼ │ │ 7. Device re-registers with basic hot desk XML │ │ │ │ │ ▼ │ │ 8. Play: "Hot desk logout successful" │ │ │ │ │ ▼ │ │ ✅ Device ready for next user │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` --- ## 6. Common Scenarios & Examples ### Scenario 1: Call Center Shift Change **Context**: Morning shift ends at 2 PM, afternoon shift starts. ``` 14:00 - Sarah (ext 1001) dials *80 to logout 14:05 - Mike (ext 1002) arrives, dials *80 on same phone - Enters 1002, then 5678 (his PIN) - Phone now rings for Mike's extension 14:06 - Customer calls 1002 → rings on the hot desk phone ``` **Configuration**: - Device: `HD-STATION-01` (type: hotdesk) - Extensions 1001, 1002: type: hotdesk or none ### Scenario 2: Healthcare Nursing Station **Context**: Nurses share phones at station but need personal extensions for call tracking. ``` Nurse Amy logs in at Station A (ext 3001) - Receives pages to ext 3001 - Voicemails go to her personal mailbox Amy moves to Station B at lunch - Logs out of Station A (*80) - Logs into Station B (*80 + 3001 + PIN) - Calls now follow her to Station B Amy's shift ends - Logs out of Station B - Nurse Bob logs in with ext 3002 ``` ### Scenario 3: Coworking Space **Context**: Members rent hot desks and need a phone for the day. ``` Monday: - John logs in to Phone #5 → ext 7001 - Makes client calls showing 7001 as CLI - Logs out at 5 PM Tuesday: - Jane logs in to Phone #5 → ext 7002 - Different caller ID, different voicemail - No trace of John's activity ``` --- ## 7. Model Context Protocol (MCP) AI Integration The **Hot Desking Module** is fully integrated into the **Ring2All PBX Model Context Protocol (MCP)** server (`@ring2all/api`). This enables the AI Copilot and external automated tools to query shared physical device fleets, inspect currently occupied desks, create or configure hot desk devices, and programmatically bind (login) or release (logout) extension sessions. ### MCP Lifecycle & Synchronization Whenever an MCP tool creates, modifies, logs in, or logs out a Hot Desking device: 1. **Relational Database Synchronization**: Updates `public.sip_devices` (linking or unlinking `extension_id`), and logs historical session timestamps in `public.hot_desk`. 2. **Synchronous XML Regeneration & Cache Invalidation**: Executes `reloadxml` via Telephony Event Socket (ESL) to ensure the telephony engine directory reflects the new user binding immediately without requiring manual operator intervention. 3. **Collision Safety**: Logging in an extension to a device automatically terminates any prior session on that device as well as any other device where that extension was currently signed in. --- ### Registered MCP Tools for Hot Desking | Tool Name | Operation | Description | Key Parameters | | :--- | :--- | :--- | :--- | | `list_hotdesk_devices` | Read / Inventory | Lists all physical Hot Desk devices, their description, enabled state, and currently logged-in extension sessions. | `search` (str, optional) | | `get_hotdesk_status` | Read / Telemetry | Checks whether a specific physical device (`deviceUsername`) or an extension number is currently engaged in an active Hot Desk session. | `identifier` (str, required) | | `create_hotdesk_device` | Write / Provisioning | Provisions a new physical Hot Desk device profile for shared office phones or floating desks. | `username` (str, req), `description` (str), `password` (str), `sipProfileId` (num) | | `update_hotdesk_device` | Write / Configuration | Updates description, SIP password, or enabled state for a Hot Desk device. | `username` (str, req), `description`, `password`, `enabled` | | `delete_hotdesk_device` | Delete / Maintenance | Deletes a Hot Desk device profile and releases any active bindings. | `username` (str, required) | | `login_hotdesk_session` | Telephony Control | Logs an extension into a physical Hot Desk phone, routing all calls for that extension to the station. | `deviceUsername` (str, req), `extension` (str, req) | | `logout_hotdesk_session` | Telephony Control | Logs out any active extension session from a physical Hot Desk device, returning the station to available state. | `deviceUsername` (str, required) | --- ### Tool Schemas & Payloads #### 1. Checking Device Fleet & Occupied Desks ```json // Tool Call: list_hotdesk_devices { "search": "Floor 2" } ``` **Sample Output Response:** ```json { "success": true, "data": { "total": 3, "occupiedCount": 1, "devices": [ { "id": 105, "username": "desk_fl2_01", "description": "Floor 2 - Station 01 (Window)", "enabled": true, "isOccupied": true, "activeExtension": "2002", "activeUserName": "David Cuadra", "loginTime": "2026-09-08T08:15:22.000Z" }, { "id": 106, "username": "desk_fl2_02", "description": "Floor 2 - Station 02", "enabled": true, "isOccupied": false, "activeExtension": null, "activeUserName": null, "loginTime": null } ] } } ``` #### 2. Querying Status of a Specific Desk or Extension ```json // Tool Call: get_hotdesk_status { "identifier": "desk_lobby_01" } ``` **Sample Output Response:** ```json { "success": true, "data": { "found": true, "deviceUsername": "desk_lobby_01", "description": "Main Lobby - Reception Desk", "isOccupied": true, "activeSession": { "extension": "1001", "userName": "Reception Frontdesk", "loginTime": "2026-09-08T07:45:00.000Z" } } } ``` #### 3. Logging an Extension into a Shared Phone ```json // Tool Call: login_hotdesk_session { "deviceUsername": "desk_fl2_02", "extension": "2005" } ``` **Sample Output Response:** ```json { "success": true, "data": { "message": "Extension 2005 (\"Carlos Mendoza\") is now logged in to Hot Desk station \"desk_fl2_02\"!", "deviceUsername": "desk_fl2_02", "extension": "2005", "userName": "Carlos Mendoza", "status": "ACTIVE_HOTDESK_SESSION" } } ``` #### 4. Releasing / Logging Out a Station ```json // Tool Call: logout_hotdesk_session { "deviceUsername": "desk_fl2_02" } ``` **Sample Output Response:** ```json { "success": true, "data": { "message": "Hot Desk station \"desk_fl2_02\" has been logged out and is now available for other users.", "deviceUsername": "desk_fl2_02", "status": "AVAILABLE" } } ``` --- ### Conversational Prompts & Chatbot Workflows Operators, facility managers, and supervisors can interact directly with the Copilot to manage hot desking: - **Station Availability & Auditing**: - *"¿Cuáles teléfonos de Hot Desking están libres en el Piso 2?"* ➔ `list_hotdesk_devices({ search: 'Floor 2' })` - *"¿Quién está usando el teléfono desk_lobby_01?"* ➔ `get_hotdesk_status({ identifier: 'desk_lobby_01' })` - *"¿En qué estación física está conectado Carlos Mendoza o la extensión 2005?"* ➔ `get_hotdesk_status({ identifier: '2005' })` - **Session Assignment & Roaming Users**: - *"Asigna la extensión 2002 al teléfono desk_fl2_02."* ➔ `login_hotdesk_session({ deviceUsername: 'desk_fl2_02', extension: '2002' })` - *"Cierra la sesión del teléfono de recepción desk_lobby_01."* ➔ `logout_hotdesk_session({ deviceUsername: 'desk_lobby_01' })` - **Provisioning Shared Devices**: - *"Crea una estación de Hot Desking llamada desk_conf_3 con descripción 'Sala de Juntas 3'."* ➔ `create_hotdesk_device({ username: 'desk_conf_3', description: 'Sala de Juntas 3' })` --- ## 8. Limitations & Important Notes ### Technical Limitations > [!WARNING] > **Extension Types**: Only extensions with `type='hotdesk'`, `type='none'`, or empty type can be used for hot desking. Standard SIP extensions (`type='sip'`) cannot log into hot desk devices. > [!WARNING] > **Single Device per Extension**: An extension can only be logged into **one hot desk device** at a time. Logging into a second device does not automatically log out from the first. > [!IMPORTANT] > **XML Regeneration**: The system uses **synchronous XML regeneration** to avoid race conditions. This adds ~5-10ms per login/logout but guarantees consistency. ### Best Practices 1. **Feature Password Required**: Always configure a feature password on hotdesk-compatible extensions 2. **Regular Audits**: Review `hot_desk` table for abandoned sessions 3. **Naming Convention**: Use consistent prefixes like `HD-` for hot desk devices 4. **Max Registrations = 1**: Prevent credential sharing by limiting to 1 registration ### Security Considerations > [!CAUTION] > **Idle Timeout**: Consider implementing `auto_logout_interval` for unattended hot desks to prevent unauthorized access. > [!CAUTION] > **Password Policy**: Feature passwords should be unique per user, not shared defaults like "1234". --- ## 9. Troubleshooting Tips ### Common Issues | Symptom | Possible Cause | Solution | |---------|---------------|----------| | "Feature not allowed" on *80 | Device type is not 'hotdesk' | Edit device and set type = hotdesk | | Extension not found | Extension type is 'sip' (not hotdesk/none) | Change extension type to 'hotdesk' or 'none' | | Invalid password | Feature password mismatch | Verify extension's features_password column | | Device doesn't re-register after login | Telephony Server didn't reload XML | Check fs_cli: `reloadxml` manually | | BLF keys don't work after login | Extension_blf entries not configured | Add BLF entries to the extension | | Login audio doesn't play | Sounds path incorrect or missing | Verify language directory exists | ### Diagnostic Commands **Check device association:** ```sql SELECT id, username, extension_id, type FROM public.sip_devices WHERE type = 'hotdesk'; ``` **Check hot desk sessions:** ```sql SELECT hd.*, e.extension, d.username FROM public.hot_desk hd JOIN public.sip_extensions e ON hd.sip_extension_id = e.id JOIN public.sip_devices d ON hd.device_id = d.id WHERE hd.enabled = TRUE; ``` **Force logout a device:** ```sql UPDATE public.sip_devices SET extension_id = NULL WHERE id = [device_id]; UPDATE public.sip_devices SET xml_config = public.generate_sip_device_xml(id) WHERE id = [device_id]; UPDATE public.hot_desk SET enabled = FALSE, logout_time = NOW() WHERE device_id = [device_id] AND enabled = TRUE; ``` ### Log Locations - **Telephony Server logs**: `/var/log/freeswitch/freeswitch.log` (search for `[hotdesking]`) - **Lua logs**: Enabled via `settings.log("DEBUG", ...)` in hotdesking.lua --- ## 10. Glossary | Term | Definition | |------|------------| | **Hot Desk Device** | A SIP phone configured as `type='hotdesk'` that can be temporarily associated with different extensions | | **Feature Code** | A special dial code (`*80`) that triggers a telephony feature rather than placing a call | | **Feature Password** | A PIN stored on the extension (`features_password`) required to log into a hot desk device | | **XML Config** | Pre-generated Telephony Server directory XML containing all device/extension settings | | **Synchronous Regeneration** | Explicit XML update that waits for completion before proceeding (avoids race conditions) | | **reloadxml** | Telephony Server API command that refreshes the in-memory directory configuration | | **Extension Association** | Linking a device's `extension_id` to a specific extension, inheriting all its settings | | **BLF (Busy Lamp Field)** | Phone feature showing other extensions' status via LED lights | | **Session Log** | Record in `hot_desk` table tracking login/logout times for auditing | --- *Documentation last updated: January 2026*