Hot Desking Module Documentation

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

---

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

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                     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()              │ │
│                                        └──────────────────────┘ │
│                                                    │            │
│                                                    ▼            │
│                                        ┌──────────────────────┐ │
│                                        │  FreeSWITCH          │ │
│                                        │  reloadxml           │ │
│                                        │  Device re-registers │ │
│                                        └──────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

Key Tables

Table	Purpose
`public.sip_devices`	Stores hot desk devices with `type='hotdesk'` and dynamic `extension_id`
`public.sip_extensions`	Extensions with `type='hotdesk'` or `type='none'` that can be used for hot desking
`public.hot_desk`	Session log tracking login/logout times for auditing

FreeSWITCH 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

Key Files

File	Description
`telephony/freeswitch/lua/main/xml_handlers/hotdesking/hotdesking.lua`	Main Lua handler for login/logout
`admin/apps/api/src/modules/telephony/hot-desking/services/hotDeskingService.ts`	Backend service for CRUD operations
`admin/apps/web/src/modules/hotDesking/HotDeskingFormView.tsx`	Frontend form component
`databases/telephony/schema.sql`	Database schema (hot_desk table)

---

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

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

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:

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' or type='none'

User Workflow

Plaintext

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

Field	Technical Description	User-Friendly Tooltip	Example	Notes
Username	SIP authentication username. Used for device registration with FreeSWITCH.	The unique ID for this phone. Users will see this in the device list.	`HD-100`, `hotdesk-lobby`	Must be unique within the domain. Use prefixes like `HD-` for easy identification.
Password	SIP password for REGISTER authentication.	Security password the phone uses to connect. Keep it secure.	`SecureP@ss2024`	8-15 characters recommended. Changed during provisioning.
Description	Human-readable label for the device.	A friendly name to help you identify this phone (e.g., "Reception Desk 1").	`Floor 2 Hot Desk`, `Lobby Phone`	Optional but highly recommended for management.
SIP Profile	FreeSWITCH sofia profile that handles this device's SIP traffic.	The network profile this phone uses to connect.	`internal`, `default`	Typically `internal` for LAN devices, select based on network topology.

Field	Technical Description	User-Friendly Tooltip	Example	Notes
Max Registrations	Maximum simultaneous REGISTER bindings allowed for this username.	How many devices can use this username at once. Usually 1 for hot desks.	`1`, `2`	Set to `1` to ensure only one physical device uses this credential.
DTMF Mode	Method for transmitting touch-tone digits.	How the phone sends button presses (like dialing during a call).	`rfc2833`, `info`, `inband`	`rfc2833` is the standard; use `info` for legacy equipment.
Outbound Codecs	Preferred audio codecs for outgoing calls, comma-separated.	Audio quality settings for calls you make from this phone.	`PCMU,PCMA`, `OPUS,G722`	Order matters—first codec is preferred.
Inbound Codecs	Preferred audio codecs for incoming calls, comma-separated.	Audio quality settings for calls coming to this phone.	`PCMU,PCMA`, `G729`	Should match outbound for consistency unless specific requirements.
Language	Default language for prompts when no extension is logged in.	Language for voice prompts when the phone is in idle hot desk mode.	`en-us-emma`, `es-us-paloma`	Used only before a user logs in; after login, user's extension language is used.
Enabled	Master toggle for device functionality.	Turn this phone on or off without deleting it.	`Yes`, `No`	Disabled devices cannot register or make calls.

---

4. Configuration Fields Reference

Device Information Section

Field Technical Description User-Friendly Tooltip Example Notes
Username SIP authentication username. Used for device registration with FreeSWITCH. The unique ID for this phone. Users will see this in the device list. HD-100, hotdesk-lobby Must be unique within the domain. Use prefixes like HD- for easy identification.
Password SIP password for REGISTER authentication. Security password the phone uses to connect. Keep it secure. SecureP@ss2024 8-15 characters recommended. Changed during provisioning.
Description Human-readable label for the device. A friendly name to help you identify this phone (e.g., "Reception Desk 1"). Floor 2 Hot Desk, Lobby Phone Optional but highly recommended for management.
SIP Profile FreeSWITCH sofia profile that handles this device's SIP traffic. The network profile this phone uses to connect. internal, default Typically internal for LAN devices, select based on network topology.
Advanced Settings Section

Field Technical Description User-Friendly Tooltip Example Notes
Max Registrations Maximum simultaneous REGISTER bindings allowed for this username. How many devices can use this username at once. Usually 1 for hot desks. 1, 2 Set to 1 to ensure only one physical device uses this credential.
DTMF Mode Method for transmitting touch-tone digits. How the phone sends button presses (like dialing during a call). rfc2833, info, inband rfc2833 is the standard; use info for legacy equipment.
Outbound Codecs Preferred audio codecs for outgoing calls, comma-separated. Audio quality settings for calls you make from this phone. PCMU,PCMA, OPUS,G722 Order matters—first codec is preferred.
Inbound Codecs Preferred audio codecs for incoming calls, comma-separated. Audio quality settings for calls coming to this phone. PCMU,PCMA, G729 Should match outbound for consistency unless specific requirements.
Language Default language for prompts when no extension is logged in. Language for voice prompts when the phone is in idle hot desk mode. en-us-emma, es-us-paloma Used only before a user logs in; after login, user's extension language is used.
Enabled Master toggle for device functionality. Turn this phone on or off without deleting it. Yes, No Disabled devices cannot register or make calls.
---
5. Call Flow / Logic Explanation

Login Flow (User Dials `80`)

Plaintext

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

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	FreeSWITCH 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

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 FreeSWITCH directory XML containing all device/extension settings
Synchronous Regeneration	Explicit XML update that waits for completion before proceeding (avoids race conditions)
reloadxml	FreeSWITCH 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

Current Label	Suggested Label	Reason
"Username"	"Device ID"	Less confusing—users aren't people here
"Description"	"Location / Label"	Suggests practical naming
"Max Registrations"	"Max Simultaneous Phones"	Clearer for non-technical users

Field	Current Tooltip	Suggested Tooltip
Username	"Unique username for SIP authentication"	"The unique ID for this hot desk phone. Use a naming convention like 'HD-FLOOR1-01' for easy identification."
Password	"SIP authentication password"	"Security password the phone uses to connect to the PBX. This is configured in the phone's settings, not entered by users."
Max Registrations	"Maximum number of simultaneous registrations"	"How many physical phones can use this device ID at once. Set to 1 to ensure only one phone uses these credentials."
Enabled	"Enable or disable this device"	"When disabled, this phone cannot connect to the PBX. Use this to temporarily take a device offline."

Field	Current Default	Suggested Default
Max Registrations	5	1 (hot desks typically single-device)
DTMF Mode	(none)	rfc2833
Outbound Codecs	PCMU,PCMA	PCMU,PCMA
Enabled	Yes	Yes

Component	Status	Location
Hot Desking	✅ Active	`app/hotdesking/hotdesking.lua`

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

Feature Password Required: Always configure a feature password on hotdesk-compatible extensions

Regular Audits: Review hot_desk table 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

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".

---

8. 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 FreeSWITCH 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

FreeSWITCH logs: /var/log/freeswitch/freeswitch.log (search for [hotdesking])

Lua logs: Enabled via settings.log("DEBUG", ...) in hotdesking.lua

---

9. 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 FreeSWITCH directory XML containing all device/extension settings
Synchronous Regeneration Explicit XML update that waits for completion before proceeding (avoids race conditions)
reloadxml FreeSWITCH 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
---
10. Suggested UI Improvements

Field Label & Tooltip Improvements

Current Label Suggested Label Reason
"Username" "Device ID" Less confusing—users aren't people here
"Description" "Location / Label" Suggests practical naming
"Max Registrations" "Max Simultaneous Phones" Clearer for non-technical users
Tooltip Improvements

Field Current Tooltip Suggested Tooltip
Username "Unique username for SIP authentication" "The unique ID for this hot desk phone. Use a naming convention like 'HD-FLOOR1-01' for easy identification."
Password "SIP authentication password" "Security password the phone uses to connect to the PBX. This is configured in the phone's settings, not entered by users."
Max Registrations "Maximum number of simultaneous registrations" "How many physical phones can use this device ID at once. Set to 1 to ensure only one phone uses these credentials."
Enabled "Enable or disable this device" "When disabled, this phone cannot connect to the PBX. Use this to temporarily take a device offline."
UX Enhancements

Add "Current Session" indicator: Show which extension is currently logged into each device

Bulk Logout Action: Allow administrators to force-logout all sessions

Session History Tab: Show login/logout history from hot_desk table

QR Code Generation: Generate QR codes for device provisioning with credentials

Status Column Enhancement: Show "Idle" vs "In Use (ext 1001)" instead of just "Enabled"

Default Values

Field Current Default Suggested Default
Max Registrations 5 1 (hot desks typically single-device)
DTMF Mode (none) rfc2833
Outbound Codecs PCMU,PCMA PCMU,PCMA
Enabled Yes Yes
---

Lua Script Status ✅

Integration Module

Component Status Location
Hot Desking ✅ Active app/hotdesking/hotdesking.lua
---

Documentation last updated: January 2026*

Hot Desking Module Documentation

Table of Contents

1. Module Overview (Technical)

What Is Hot Desking?

Architecture

Key Tables

FreeSWITCH Integration

Key Files

2. Module Overview (Commercial/Business)

Business Value

Target Markets

Licensing Considerations

3. Module Overview (End User/Administrator)

What Can You Do?

User Workflow

Quick Tips

4. Configuration Fields Reference

Device Information Section

Advanced Settings Section

5. Call Flow / Logic Explanation

Login Flow (User Dials 80)

Logout Flow (User Dials 80 When Logged In)

6. Common Scenarios & Examples

Scenario 1: Call Center Shift Change

Scenario 2: Healthcare Nursing Station

Scenario 3: Coworking Space

7. Limitations & Important Notes

Technical Limitations

Best Practices

Security Considerations

8. Troubleshooting Tips

Common Issues

Diagnostic Commands

Log Locations

9. Glossary

10. Suggested UI Improvements

Field Label & Tooltip Improvements

Tooltip Improvements

UX Enhancements

Default Values

Lua Script Status ✅

Integration Module

Login Flow (User Dials `80`)

Logout Flow (User Dials `80` When Logged In)