Hot Desking Module Documentation
Table of Contents
Section titled “Table of Contents”- Module Overview (Technical)
- Module Overview (Commercial/Business)
- Module Overview (End User/Administrator)
- Configuration Fields Reference
- Call Flow / Logic Explanation
- Common Scenarios & Examples
- Model Context Protocol (MCP) AI Integration
- Limitations & Important Notes
- Troubleshooting Tips
- Glossary
1. Module Overview (Technical)
Section titled “1. Module Overview (Technical)”What Is Hot Desking?
Section titled “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
Section titled “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
Section titled “Telephony Server Integration”- Feature Code:
*80triggershotdesking.lua - Login Flow: User enters extension + feature password → device associates with extension
- Logout Flow: Same code
*80when logged in → device disassociates - XML Handling: Device XML is regenerated synchronously to avoid race conditions
- Registration: After login/logout,
reloadxmlforces device re-registration with new settings
🎯 User Roles & Key Capabilities
Section titled “🎯 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)
Section titled “2. Module Overview (Commercial/Business)”Business Value
Section titled “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
Section titled “Target Markets”- Call Centers: Agents on rotating shifts share desks
- Healthcare: Doctors/nurses move between stations
- Coworking Spaces: Hot desk members use any available phone
- Retail: Staff use phones in different areas throughout the day
- Enterprises with Hybrid Work: Employees don’t have permanent desks
Licensing Considerations
Section titled “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)
Section titled “3. Module Overview (End User/Administrator)”What Can You Do?
Section titled “What Can You Do?”As an administrator, you can:
- Create Hot Desk Devices — Physical phones designated for shared use
- Manage Device Settings — SIP credentials, codecs, DTMF mode
- Monitor Sessions — See who is logged in to which device
- Configure Extensions for Hot Desking — Mark extensions as
type='hotdesk'ortype='none'
User Workflow
Section titled “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
Section titled “Quick Tips”[!TIP] For Administrators: Create hot desk devices with descriptive names like
HD-FLOOR2-01to make identification easy.
[!TIP] For Users: Always dial
*80before leaving to ensure your extension is logged out.
4. Configuration Fields Reference
Section titled “4. Configuration Fields Reference”Device Information FormBox (HotDeskingDeviceInfoBox)
Section titled “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
Section titled “5. Call Flow / Logic Explanation”Login Flow (User Dials *80)
Section titled “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)
Section titled “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
Section titled “6. Common Scenarios & Examples”Scenario 1: Call Center Shift Change
Section titled “Scenario 1: Call Center Shift Change”Context: Morning shift ends at 2 PM, afternoon shift starts.
14:00 - Sarah (ext 1001) dials *80 to logout14:05 - Mike (ext 1002) arrives, dials *80 on same phone - Enters 1002, then 5678 (his PIN) - Phone now rings for Mike's extension14:06 - Customer calls 1002 → rings on the hot desk phoneConfiguration:
- Device:
HD-STATION-01(type: hotdesk) - Extensions 1001, 1002: type: hotdesk or none
Scenario 2: Healthcare Nursing Station
Section titled “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 3002Scenario 3: Coworking Space
Section titled “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 activity7. Model Context Protocol (MCP) AI Integration
Section titled “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
Section titled “MCP Lifecycle & Synchronization”Whenever an MCP tool creates, modifies, logs in, or logs out a Hot Desking device:
- Relational Database Synchronization: Updates
public.sip_devices(linking or unlinkingextension_id), and logs historical session timestamps inpublic.hot_desk. - Synchronous XML Regeneration & Cache Invalidation: Executes
reloadxmlvia Telephony Event Socket (ESL) to ensure the telephony engine directory reflects the new user binding immediately without requiring manual operator intervention. - 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
Section titled “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
Section titled “Tool Schemas & Payloads”1. Checking Device Fleet & Occupied Desks
Section titled “1. Checking Device Fleet & Occupied Desks”// Tool Call: list_hotdesk_devices{ "search": "Floor 2"}Sample Output Response:
{ "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
Section titled “2. Querying Status of a Specific Desk or Extension”// Tool Call: get_hotdesk_status{ "identifier": "desk_lobby_01"}Sample Output Response:
{ "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
Section titled “3. Logging an Extension into a Shared Phone”// Tool Call: login_hotdesk_session{ "deviceUsername": "desk_fl2_02", "extension": "2005"}Sample Output Response:
{ "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
Section titled “4. Releasing / Logging Out a Station”// Tool Call: logout_hotdesk_session{ "deviceUsername": "desk_fl2_02"}Sample Output Response:
{ "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
Section titled “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' })
- “¿Cuáles teléfonos de Hot Desking están libres en el Piso 2?” ➔
-
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' })
- “Asigna la extensión 2002 al teléfono desk_fl2_02.” ➔
-
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' })
- “Crea una estación de Hot Desking llamada desk_conf_3 con descripción ‘Sala de Juntas 3’.” ➔
8. Limitations & Important Notes
Section titled “8. Limitations & Important Notes”Technical Limitations
Section titled “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
Section titled “Best Practices”- Feature Password Required: Always configure a feature password on hotdesk-compatible extensions
- Regular Audits: Review
hot_desktable for abandoned sessions - Naming Convention: Use consistent prefixes like
HD-for hot desk devices - Max Registrations = 1: Prevent credential sharing by limiting to 1 registration
Security Considerations
Section titled “Security Considerations”[!CAUTION] Idle Timeout: Consider implementing
auto_logout_intervalfor 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
Section titled “9. Troubleshooting Tips”Common Issues
Section titled “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
Section titled “Diagnostic Commands”Check device association:
SELECT id, username, extension_id, typeFROM public.sip_devicesWHERE type = 'hotdesk';Check hot desk sessions:
SELECT hd.*, e.extension, d.usernameFROM public.hot_desk hdJOIN public.sip_extensions e ON hd.sip_extension_id = e.idJOIN public.sip_devices d ON hd.device_id = d.idWHERE hd.enabled = TRUE;Force logout a device:
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
Section titled “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
Section titled “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