Parking Lots 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 Are Parking Lots?

Parking Lots provide call holding zones where calls can be "parked" on numbered slots and retrieved by anyone who knows the slot number. Unlike regular hold, parked calls can be picked up from any phone in the system.

Architecture

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                    Parking Lot System                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  PARKING A CALL                                                 │
│  ─────────────────                                              │
│  User on call → Transfers to *70 (park) → Call parked          │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              Parking Lot "Main" (Extension 700)          │   │
│  │                                                          │   │
│  │  Slot 701: [Occupied] - Caller: +1-555-1234 (60s)       │   │
│  │  Slot 702: [Available]                                   │   │
│  │  Slot 703: [Available]                                   │   │
│  │  Slot 704: [Occupied] - Caller: +1-555-5678 (15s)       │   │
│  │  Slot 705: [Available]                                   │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
│  RETRIEVING A CALL                                              │
│  ─────────────────                                              │
│  Any user → Dials 701 → Connected to parked caller              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

Table	Purpose
`public.parking_lots`	Lot definitions (extension, slots, settings)
(runtime)	FreeSWITCH valet_parking module manages active slots

Slot Numbering

If lot extension is 700 with 5 positions:

Slot 701, 702, 703, 704, 705

Key Files

File	Description
`admin/apps/web/src/modules/parkingLots/`	Frontend module
`admin/apps/web/src/i18n/en/parkingLots.json`	English translations
`telephony/freeswitch/conf/dialplan/valet_parking/`	Parking dialplan

---

2. Module Overview (Commercial/Business)

Business Value

Parking Lots enable flexible call routing:

Without Parking	With Parking
Transfer to specific person	Park and announce slot
Caller waits for specific person	Anyone can retrieve
Tied to one extension	Available system-wide

Use Cases

Reception Workflow

- "I have John Smith on line 701"

- Anyone can dial 701 to take the call

Warehouse/Retail

- Park call, page location over PA

- Employee picks up from nearest phone

Customer Service

- Park caller while researching answer

- Return to same caller easily

Multi-Location

- Park call at one location

- Retrieve at another location

Feature Highlights

Feature	Benefit
Multiple Slots	Handle many parked calls simultaneously
Timeout Callback	Parked call returns if not answered
Position Announcement	Caller hears their slot number
Music on Hold	Professional hold experience
Timeout Routing	Route to voicemail/IVR if not retrieved

---

3. Module Overview (End User/Administrator)

What Can You Do?

Create parking lots with assigned extension ranges
Configure parking behavior (timeout, music, announcements)
Set timeout destinations (voicemail, IVR, extension)
Monitor active parked calls

Administrator Workflow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                 Creating a Parking Lot                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Step 1: General Tab                                            │
│  ├─ Name: "Main Parking"                                       │
│  ├─ Extension: 700 (slots will be 701-710)                     │
│  └─ Total Positions: 10                                        │
│                                                                 │
│  Step 2: Behavior Tab                                           │
│  ├─ Parking Time: 120 seconds                                  │
│  ├─ Comeback Time: 30 seconds                                  │
│  ├─ Find Slot: Next Available                                  │
│  ├─ Announce Position: ✓                                       │
│  └─ Music on Hold: Default                                     │
│                                                                 │
│  Step 3: Advanced Tab                                           │
│  ├─ Return to Originator: ✓                                    │
│  ├─ Timeout Module: Voicemail                                  │
│  └─ Timeout Destination: 1000 (operator voicemail)             │
│                                                                 │
│  Step 4: Enable and Save                                        │
│  └─ Enabled: ✓                                                 │
│                                                                 │
│  Result: Users can transfer to 700, slots 701-710 available    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

User Workflow (Parking a Call)

Plaintext

1. While on a call, user transfers to 700
2. System announces: "Parked at slot 703"
3. User hangs up (or is returned to call)
4. User pages: "John Smith, you have a call on 703"
5. John dials 703 → Connected to caller

Quick Tips

TIP

Announce Position: Enable this so the parker knows which slot to communicate.

TIP

Return to Originator: Enable this to return timeout calls to the person who parked.

CAUTION

Parking Time: If too short, calls return before they can be retrieved.

---

4. Configuration Fields Reference

General Tab

Field	Description	Example	Required
Name	Lot name	`Main Parking`	Yes
Extension	Base extension (slots start here +1)	`700`	Yes
Total Positions	Number of parking slots (1-99)	`10`	Yes
Enabled	Active/inactive	On/Off	Yes

Behavior Tab

Field	Description	Default	Range
Parking Time	Seconds before callback	120	5-300
Comeback Time	Delay before redirect after timeout	30	5-300
Find Slot	Slot assignment policy	Next Available	Next / Random
Announce Position	Tell caller their slot number	Off	On/Off
Courtesy Tone	Tone played to parked party	Caller	Caller / None
Music on Hold Class	MOH to play while parked	Default	Default / Calm / Business

Advanced Tab

Field	Description	Default
Return to Originator	Return timeout call to parker	On
Call Transfer	Allow transfer while parked	On
Call Reparking	Allow re-park from same lot	On
Call Hangup	Hang up if no timeout destination	Off
Record Parked Call	Record while parked	Off

Timeout Destination

Field	Description
Timeout Module	Where to route after timeout
Timeout Destination	Target within the module

Module	Destination Example
--------	-------------------
Voicemail	Extension number
IVR	IVR name
Extension	Extension number
Group	Ring group ID
None	Hang up

---

5. Call Flow / Logic Explanation

Parking Flow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                    Parking Flow                                 │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. User transfers active call to 700 (parking lot extension)  │
│     │                                                           │
│     ▼                                                           │
│  2. Find available slot                                         │
│     ├─ Next Available: Check 701, 702, 703...                  │
│     └─ Random: Pick random available slot                       │
│     │                                                           │
│     ▼                                                           │
│  3. Found slot 703                                              │
│     │                                                           │
│     ▼                                                           │
│  4. If announcePosition = true:                                 │
│     → Play "Parked at slot 7-0-3"                              │
│     │                                                           │
│     ▼                                                           │
│  5. Place caller on hold at slot 703                            │
│     ├─ Play music on hold                                       │
│     └─ Start parking timer (120 seconds)                        │
│     │                                                           │
│     ▼                                                           │
│  6. Parker's call ends (they can work on other things)          │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Retrieval Flow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                    Retrieval Flow                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. Any user dials 703 (parked slot)                            │
│     │                                                           │
│     ▼                                                           │
│  2. Check if slot 703 is occupied                               │
│     ├─ Yes → Continue                                          │
│     └─ No → "Slot empty" or dial tone                          │
│     │                                                           │
│     ▼                                                           │
│  3. Bridge user with parked caller                              │
│     │                                                           │
│     ▼                                                           │
│  4. Slot 703 marked as available                                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Timeout Flow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                    Timeout Flow                                 │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. Parking timer (120s) expires                                │
│     │                                                           │
│     ▼                                                           │
│  2. Check returnToOriginator                                    │
│     ├─ Yes → Ring the original parker (who parked the call)    │
│     │   ├─ If answered → Connected                             │
│     │   └─ If not answered → Wait comebackTime (30s)           │
│     └─ No → Skip to step 3                                     │
│     │                                                           │
│     ▼                                                           │
│  3. Route to timeout destination                                │
│     ├─ Voicemail: Send to VM of specified extension            │
│     ├─ IVR: Transfer to IVR menu                               │
│     ├─ Extension: Ring specified extension                      │
│     └─ None + callHangup: Hang up the call                     │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

---

6. Common Scenarios & Examples

Scenario 1: Reception Parking

Setup:

Setting	Value
Name	Main Parking
Extension	700
Total Positions	5
Parking Time	180 seconds
Announce Position	✓
Return to Originator	✓
Timeout Module	Voicemail
Timeout Destination	1000 (reception VM)

Usage:

Reception transfers caller to 700
System: "Parked at slot 703"
Reception pages: "John, call on 703"
John dials 703 → Connected

Scenario 2: Department-Specific Lots

Setup multiple lots:

Lot	Extension	Positions	Timeout Destination
Sales Parking	710	5	Sales VM
Support Parking	720	10	Support Queue
Executive Parking	730	3	Admin Assistant

Scenario 3: Warehouse with PA System

Setup:

Setting	Value
Name	Warehouse
Extension	800
Total Positions	10
Parking Time	300 seconds (5 min)
Announce Position	✓
Return to Originator	✗
Timeout Module	IVR
Timeout Destination	main_menu

Usage:

Office parks call at 800
System: "Parked at slot 805"
PA announcement: "Shipping, line 805"
Warehouse employee picks up nearest phone, dials 805

---

7. Limitations & Important Notes

Technical Limitations

WARNING

Slot Range: Slots start at extension+1. Extension 700 = slots 701-710 (for 10 positions).

WARNING

Single Retrieval: Only one person can retrieve a parked call—first dial wins.

IMPORTANT

MOH Duration: Music on Hold loops if parking time exceeds MOH file length.

Best Practices

Plan Extension Ranges: Don't overlap parking slots with real extensions
Reasonable Timeouts: 2-3 minutes is typical; too short causes premature callbacks
Enable Announcements: Users need to know which slot to communicate
Return to Originator: Safer than sending to general queue on timeout
Document Your Lots: Train staff on which lots to use for which purposes

Security Considerations

CAUTION

Anyone Can Retrieve: Any user who dials the slot can pick up the call. Consider this for sensitive calls.

---

8. Troubleshooting Tips

Common Issues

Symptom	Possible Cause	Solution
No available slots	All slots full	Increase totalPositions
Call returns immediately	Parking time too short	Increase parkingTime
Can't retrieve call	Wrong slot number	Verify slot dialed
No slot announcement	announcePosition = false	Enable announcement
Call goes to wrong VM	Wrong timeout destination	Check destination config

Diagnostic SQL

List parking lots:

Sql

SELECT name, extension, total_positions, parking_time, enabled
FROM public.parking_lots
WHERE domain_id = [domain_id]
ORDER BY extension;

FreeSWITCH Commands

Check active parked calls:

Bash

fs_cli -x "valet_parking status"

Check specific lot:

Bash

fs_cli -x "valet_parking list 700"

Manually retrieve parked call:

Bash

fs_cli -x "valet_parking retrieve 703"

---

9. Glossary

Term	Definition
Parking Lot	A collection of hold slots for parking calls
Slot	An individual parking position (e.g., 701, 702)
Park	Place a call on hold in a numbered slot
Retrieve	Pick up a parked call by dialing its slot
Parking Time	How long before a parked call times out
Comeback Time	Delay before routing after timeout
Return to Originator	Send timeout call back to the parker
Valet Parking	FreeSWITCH module that handles parking
MOH	Music on Hold played while parked
Position	Same as slot—a numbered parking space

---

10. Suggested UI Improvements

The existing i18n tooltips are comprehensive.

UX Enhancements

Real-Time Status: Show which slots are currently occupied (already in Positions tab)

Quick Park Button: One-click park from active call display

Slot Notifications: Alert when parked call is about to timeout

Usage Analytics: Show parking lot utilization over time

Retrieve Preview: Show caller ID before retrieving

Visual Improvements

Current	Suggested
Plain slot list	Visual slot grid with occupied/available colors
Text timer	Countdown progress bar for parked calls
Simple numbers	Caller ID preview on hover

---

Lua Script Status ℹ️

Integration Module

Component	Status	Notes
Parking Lots	ℹ️ Configuration module	Call parking managed natively by FreeSWITCH mod_valet_parking

--- Documentation last updated: January 2026

Parking Lots Module Documentation

Table of Contents

1. Module Overview (Technical)

What Are Parking Lots?

Architecture

Key Tables

Slot Numbering

Key Files

2. Module Overview (Commercial/Business)

Business Value

Use Cases

Feature Highlights

3. Module Overview (End User/Administrator)

What Can You Do?

Administrator Workflow

User Workflow (Parking a Call)

Quick Tips

4. Configuration Fields Reference

General Tab

Behavior Tab

Advanced Tab

Timeout Destination

5. Call Flow / Logic Explanation

Parking Flow

Retrieval Flow

Timeout Flow

6. Common Scenarios & Examples

Scenario 1: Reception Parking

Scenario 2: Department-Specific Lots

Scenario 3: Warehouse with PA System

7. Limitations & Important Notes

Technical Limitations

Best Practices

Security Considerations

8. Troubleshooting Tips

Common Issues

Diagnostic SQL

FreeSWITCH Commands

9. Glossary

10. Suggested UI Improvements

The existing i18n tooltips are comprehensive.

UX Enhancements

Visual Improvements

Lua Script Status ℹ️

Integration Module