Conferences 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 Conferences?

The Conferences module provides audio and video conferencing capabilities within the PBX. It consists of two main components:

Conference Rooms — Virtual meeting spaces with specific extensions, PINs, and behaviors
Conference Profiles — Reusable templates defining audio/video settings and DTMF controls

Architecture

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                    Conference System                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              CONFERENCE PROFILES                         │   │
│  │  (Reusable templates for audio/video/DTMF settings)     │   │
│  │  ├─ default                                              │   │
│  │  ├─ video-enabled                                        │   │
│  │  └─ moderator-only                                       │   │
│  └──────────────────────────────────────────────────────────┘   │
│                           │                                     │
│                           ▼                                     │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              CONFERENCE ROOMS                            │   │
│  │  (Individual meeting spaces)                             │   │
│  │  ├─ Extension: 8000 → Sales Weekly                       │   │
│  │  ├─ Extension: 8001 → Engineering Standup                │   │
│  │  └─ Extension: 8002 → Board Meeting                      │   │
│  └──────────────────────────────────────────────────────────┘   │
│                           │                                     │
│                           ▼                                     │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              FreeSWITCH mod_conference                   │   │
│  │  ├─ Audio mixing                                         │   │
│  │  ├─ Video layout                                         │   │
│  │  ├─ Recording                                            │   │
│  │  └─ DTMF controls                                        │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

Table	Purpose
`public.conferences`	Conference room definitions (extension, name, settings)
`public.conference_profiles`	Reusable profile templates
`public.conference_members`	Active participants (runtime)
`public.conference_recordings`	Recording metadata

FreeSWITCH Integration

Module: mod_conference
Dialplan: Conference extension triggers conference application
Commands: conference list, conference [name] kick all, etc.
Events: Conference events published via ESL for real-time monitoring

Key Files

File	Description
`admin/apps/api/src/modules/telephony/conferences/services/conferencesService.ts`	Backend service for rooms
`admin/apps/api/src/modules/telephony/conference-profiles/services/conferenceProfileService.ts`	Backend service for profiles
`admin/apps/web/src/modules/conferences/ConferenceFormView.tsx`	Room configuration form
`admin/apps/web/src/i18n/en/conferences.json`	English translations
`admin/apps/web/src/i18n/en/conferenceProfiles.json`	Profile translations

---

2. Module Overview (Commercial/Business)

Business Value

Integrated conferencing eliminates the need for third-party services:

External Service	Built-In Conferences
Monthly fees per user/room	No additional cost
Separate dial-in numbers	Uses PBX extensions
Limited integration	Full CDR, recording, presence
Data leaves your network	Everything stays internal

Use Cases

Recurring Team Meetings

- Permanent room with extension 8000

- Wait for moderator to start

- Auto-record for minutes

Customer Calls

- Participant PIN for security

- Announce participant count

- End when moderator leaves

Webinars & Training

- Mute on entry for attendees

- Moderator controls for Q&A

- Video layouts for presentations

Executive Board Meetings

- Separate moderator/participant PINs

- Recording to secure location

- Lock conference after start

Feature Highlights

Feature	Benefit
Moderator PIN	Control who can start/manage meetings
Wait for Moderator	Hold participants in music until host joins
Mute on Entry	Reduce background noise in large meetings
Video Modes	Support for video conferences with layouts
Recording	Automatic or on-demand recording
DTMF Controls	Participants can mute/unmute via keypad

---

3. Module Overview (End User/Administrator)

What Can You Do?

Conference Rooms:

Create permanent or scheduled conference rooms
Assign extension numbers for dialing
Set moderator and participant PINs
Configure audio, video, and recording settings

Conference Profiles:

Create reusable templates for common settings
Define DTMF key mappings (0=mute, #=hangup, etc.)
Set default audio quality and video layouts
System profiles cannot be deleted

User Workflow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                 Creating a Conference Room                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Step 1: Basic Information                                      │
│  ├─ Extension: 8000                                            │
│  ├─ Name: "Weekly Sales Meeting"                               │
│  ├─ Description: "Every Monday 9 AM"                           │
│  └─ Language: English                                          │
│                                                                 │
│  Step 2: Access & Security                                      │
│  ├─ Moderator PIN: 1234                                        │
│  ├─ Participant PIN: 5678                                      │
│  └─ Wait for Moderator: ✓                                      │
│                                                                 │
│  Step 3: Audio & Behavior                                       │
│  ├─ Max Participants: 25                                       │
│  ├─ Mute on Entry: ✓                                           │
│  ├─ Announce Name: ✓                                           │
│  └─ End on Moderator Exit: ✓                                   │
│                                                                 │
│  Step 4: Recording                                              │
│  ├─ Recording Enabled: ✓                                       │
│  ├─ Format: WAV                                                │
│  └─ Announce Recording: ✓                                      │
│                                                                 │
│  Step 5: Save → Extension 8000 is ready                        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                      Joining a Conference                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  User dials 8000                                                │
│      │                                                          │
│      ▼                                                          │
│  "Enter your PIN, followed by pound"                            │
│      │                                                          │
│      ▼                                                          │
│  User enters 1234# (moderator PIN)                              │
│      │                                                          │
│      ├─ If first → Conference starts, music stops               │
│      └─ If not first → Joins existing conference                │
│      │                                                          │
│      ▼                                                          │
│  "There are now 3 people in this conference"                    │
│      │                                                          │
│      ▼                                                          │
│  User is now in the conference                                  │
│      ├─ Press 0 to mute/unmute                                 │
│      ├─ Press # to leave                                       │
│      └─ Press * to access menu                                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Tips

TIP

Use Profiles: Create a profile for common settings (audio quality, DTMF keys) and apply it to multiple rooms.

TIP

Moderator PIN Only: If you only set a moderator PIN (no participant PIN), anyone can join but only PIN holders can moderate.

CAUTION

Max Members = 0: A value of 0 means unlimited—be careful with resource usage for large conferences.

---

4. Configuration Fields Reference

Conference Room — Basic Tab

Field	Description	Example	Notes
Extension	Dialable number for the conference	`8000`	Must be unique
Name	Identifier for the room	`Sales Meeting`	Used in announcements
Description	Internal notes	`Weekly team sync`	Optional
Language	Audio prompt language	`en-us-emma`	Affects all voice prompts
Profile	Conference profile to apply	`default`	Inherits profile settings

Conference Room — Access & Security Tab

Field	Description	Example	Notes
Moderator PIN	PIN for moderator access	`1234`	Grants control features
Participant PIN	PIN for regular attendees	`5678`	Leave empty for no PIN
Wait for Moderator	Hold callers until moderator joins	On/Off	Music plays while waiting
End on Moderator Exit	Terminate when moderator leaves	On/Off	Kicks all participants
Lock Conference	Prevent new participants	On/Off	Manually lockable via DTMF

Conference Room — Audio & Behavior Tab

Field	Description	Default	Notes
Max Members	Maximum participants	`0` (unlimited)	Rejects additional callers
Announce Count	Say participant count on join	On	"There are now 5 people..."
Announce Name	Record and play joiner's name	Off	Prompts user to say name
Mute on Entry	Auto-mute new participants	Off	Great for large meetings
Deaf on Entry	Block audio to new participants	Off	Admin-only use case
Enter Sound	Audio when someone joins	tone	Set to "none" to disable
Exit Sound	Audio when someone leaves	tone	Set to "none" to disable
Energy Level	Voice activation threshold	`300`	Higher = less background noise
Music on Hold	Audio while waiting alone	`$${hold_music}`	Variable or file path

Conference Room — Recording Tab

Field	Description	Default	Notes
Recording Enabled	Enable conference recording	Off	Creates audio file
Record Format	Audio file format	WAV	WAV, MP3
Recording Path	Where to save files	`/recordings/`	With filename template
Announce Recording	Tell participants recording is on	On	Compliance requirement
On-Demand Recording	Allow moderator to start/stop	Off	Via DTMF key
Record Moderator Only	Only record moderator's audio	Off	Specific use cases

Conference Room — Video Tab

Field	Description	Options	Notes
Video Mode	Video handling mode	None, Conference, Mux, Transcode	None = audio only
Video Layout	How participants are arranged	Grid, Speaker, Filmstrip	Configurable layouts
Video Codec	Video encoding	VP8, VP9, H.264	Compatibility varies
Video Resolution	Quality level	480p, 720p, 1080p	Bandwidth tradeoff
Max Video Participants	Visible video streams	`4`, `9`	Layout dependent
Record Video	Include video in recording	On/Off	Larger files

Conference Room — Advanced Tab

Field	Description	Notes
Conference Flags	Comma-separated behavior flags	`mintwo, moderator`
Presence ID	BLF status identifier	Allows phone LEDs to show activity
DTMF Menu Key	Key to access menu	Default:
API Control	Allow ESL/API commands	For external integrations
Database Logging	Log events to database	For CDR/analytics
Conference Timeout	Auto-end after X seconds	0 = never
Member Timeout	Max time per participant	0 = unlimited

Conference Profile Fields

Field	Description	Default	Notes
Rate	Audio sample rate (Hz)	`8000`	Higher = better quality
Channels	Audio channels	`1` (mono)	2 = stereo
Comfort Noise	Background noise during silence	On	Prevents "dead air"
Enter/Exit Sounds	Join/leave audio	Tones	Customizable
DTMF Keys	Keypad mappings	0=mute, #=hangup, etc.	Per-digit configuration

---

5. Call Flow / Logic Explanation

Conference Join Flow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                   Conference Join Flow                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. User dials conference extension (8000)                      │
│     │                                                           │
│     ▼                                                           │
│  2. Dialplan matches: conference [name] [profile]               │
│     │                                                           │
│     ▼                                                           │
│  3. Check if participant PIN is required                        │
│     ├─ Yes → Prompt for PIN                                     │
│     │        ├─ Correct → Continue                              │
│     │        └─ Wrong → "Goodbye" + Hangup                      │
│     └─ No → Continue                                            │
│     │                                                           │
│     ▼                                                           │
│  4. Check if moderator PIN provided matches                     │
│     ├─ Yes → Mark as moderator                                  │
│     └─ No → Mark as participant                                 │
│     │                                                           │
│     ▼                                                           │
│  5. Check wait_for_moderator flag                               │
│     ├─ Yes + No moderator yet → Play MOH, wait                  │
│     └─ No or Moderator exists → Join conference                 │
│     │                                                           │
│     ▼                                                           │
│  6. Apply member settings                                       │
│     ├─ Mute on entry?                                          │
│     ├─ Deaf on entry?                                          │
│     └─ Announce name?                                          │
│     │                                                           │
│     ▼                                                           │
│  7. Play enter sound / announce count                           │
│     │                                                           │
│     ▼                                                           │
│  8. User is now in conference                                   │
│     ├─ Audio mixed with other participants                      │
│     └─ DTMF controls active                                    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

DTMF Control Reference

Key	Default Action	Behavior
`0`	Mute/Unmute	Toggle microphone
`1`	Volume down (talk)	Decrease your mic level
`2`	Volume reset (talk)	Reset mic to default
`3`	Volume up (talk)	Increase your mic level
`4`	Volume down (listen)	Decrease speaker level
`5`	Volume reset (listen)	Reset speaker to default
`6`	Volume up (listen)	Increase speaker level
`7`	Energy down	More sensitive to voice
`8`	Energy reset	Default sensitivity
`9`	Energy up	Less sensitive to voice
	Deaf + Mute	Can't hear or be heard
`#`	Hangup	Leave conference

---

6. Common Scenarios & Examples

Scenario 1: Weekly Team Meeting

Setup:

Plaintext

Extension: 8000
Name: Engineering Standup
Moderator PIN: 1234 (team lead)
Participant PIN: (none - anyone can join)
Wait for Moderator: Yes
Mute on Entry: No (small team)
End on Moderator Exit: Yes

Experience:

Team members dial 8000, hear music until lead joins
Lead enters 1234#, meeting starts
When lead hangs up, all participants are disconnected

Scenario 2: Large Webinar

Setup:

Plaintext

Extension: 9000
Name: Product Launch Webinar
Max Members: 200
Moderator PIN: 4567
Participant PIN: 7890
Mute on Entry: Yes
Announce Name: Off
Recording: Enabled

Experience:

Attendees join muted (can't interrupt)
Moderator can unmute for Q&A
Recording saved automatically

Scenario 3: Board Meeting (Secure)

Setup:

Plaintext

Extension: 8888
Name: Board Meeting
Moderator PIN: 9999 (CEO only)
Participant PIN: 1111
Wait for Moderator: Yes
Recording: Enabled (to secure path)
Lock Conference: (manual via DTMF)

Experience:

Members wait for CEO
CEO can lock conference after all join
Recording goes to restricted folder

---

7. Limitations & Important Notes

Technical Limitations

WARNING

Video Conferencing Resources: Video conferences use significant CPU. Plan for ~1 CPU core per 4-6 video participants.

WARNING

Recording Storage: Large conferences can generate significant disk usage. Monitor storage and implement rotation.

IMPORTANT

Codec Compatibility: Not all endpoints support video codecs. VP8 has widest compatibility; H.264 may require licensing.

Best Practices

Use Profiles: Don't duplicate settings across rooms—use profiles
Set Max Members: Prevent resource exhaustion by setting realistic limits
PIN Security: Use different PINs for different access levels
Test Recording: Verify recording path is writable before go-live
Announce Recording: Many jurisdictions require recording notification

Security Considerations

CAUTION

PIN Disclosure: Treat moderator PINs like passwords—they grant control of the conference.

CAUTION

Recording Path: Ensure recording directory has proper permissions and is not publicly accessible.

---

8. Troubleshooting Tips

Common Issues

Symptom	Possible Cause	Solution
"Conference not found"	Extension not in dialplan	Verify conference exists and is enabled
Music plays forever	No moderator + wait_for_moderator	Have moderator join with correct PIN
Recording not created	Path not writable	Check directory permissions
Video not working	Profile video mode = none	Enable video mode in room or profile
DTMF not working	Wrong caller_controls profile	Verify DTMF mappings in profile
Echo issues	Multiple devices in same room	Mute all but one physical device

Diagnostic Commands

Check active conferences:

Bash

fs_cli -x "conference list"

See conference members:

Bash

fs_cli -x "conference 8000 list"

Mute a participant:

Bash

fs_cli -x "conference 8000 mute [member_id]"

Kick all participants:

Bash

fs_cli -x "conference 8000 kick all"

Start/stop recording:

Bash

fs_cli -x "conference 8000 record /path/to/file.wav"
fs_cli -x "conference 8000 stop"

Diagnostic SQL

List conferences:

Sql

SELECT extension, name, enabled, moderator_pin, participant_pin 
FROM public.conferences 
WHERE domain_id = [domain_id]
ORDER BY extension;

Check conference profile:

Sql

SELECT name, is_system, enabled 
FROM public.conference_profiles
WHERE id = [profile_id];

---

9. Glossary

Term	Definition
Conference Room	Virtual meeting space identified by an extension number
Conference Profile	Reusable template defining audio/video/DTMF settings
Moderator	Participant with control rights (entered moderator PIN)
Participant	Regular attendee (entered participant PIN or no PIN)
Wait for Moderator	Hold participants in music until a moderator joins
Mute on Entry	Automatically mute microphone when joining
Deaf on Entry	Block audio to participant (they can't hear)
Energy Level	Voice activation threshold—higher means less sensitivity to quiet sounds
DTMF	Dual-Tone Multi-Frequency—keypad tones for in-call control
Video Layout	Visual arrangement of participant video streams (grid, spotlight, etc.)
MOH	Music on Hold—audio played while waiting
mod_conference	FreeSWITCH module providing conferencing functionality
ESL	Event Socket Library—API for external conference control

---

10. Suggested UI Improvements

The i18n tooltips in this module are already comprehensive. Minor enhancements:

Field	Suggested Improvement
maxMembers	Add warning: "0 = unlimited (use with caution)"
energyLevel	Add: "300 is recommended. Lower = more sensitive (picks up noise)"
recordPath	Add: "Ensure path exists and has write permissions"

UX Enhancements

Conference Activity Widget: Show active conferences in dashboard with participant count

Quick Actions: Add "Start Conference" button that dials the extension from WebRTC

Recording Status: Icon in conference list showing if recording is enabled

Profile Preview: When selecting a profile, show summary of key settings

Conflict Detection: Warn if extension conflicts with existing extensions

Profile Wizard

Consider adding a wizard for common profile types:

"Audio Only (Low Bandwidth)"
"Small Team (Video Enabled)"
"Webinar (Presentation Mode)"
"Open Room (No Controls)"

Lua Script Status ℹ️

Integration Module

Component	Status	Notes
Conferences	ℹ️ Configuration module	Conference sessions managed natively by FreeSWITCH mod_conference

--- Documentation last updated: January 2026

Conferences Module Documentation

Table of Contents

1. Module Overview (Technical)

What Are Conferences?

Architecture

Key Tables

FreeSWITCH Integration

Key Files

2. Module Overview (Commercial/Business)

Business Value

Use Cases

Feature Highlights

3. Module Overview (End User/Administrator)

What Can You Do?

User Workflow

Quick Tips

4. Configuration Fields Reference

Conference Room — Basic Tab

Conference Room — Access & Security Tab

Conference Room — Audio & Behavior Tab

Conference Room — Recording Tab

Conference Room — Video Tab

Conference Room — Advanced Tab

Conference Profile Fields

5. Call Flow / Logic Explanation

Conference Join Flow

DTMF Control Reference

6. Common Scenarios & Examples

Scenario 1: Weekly Team Meeting

Scenario 2: Large Webinar

Scenario 3: Board Meeting (Secure)

7. Limitations & Important Notes

Technical Limitations

Best Practices

Security Considerations

8. Troubleshooting Tips

Common Issues

Diagnostic Commands

Diagnostic SQL

9. Glossary

10. Suggested UI Improvements

The i18n tooltips in this module are already comprehensive. Minor enhancements:

UX Enhancements

Profile Wizard

Lua Script Status ℹ️

Integration Module