Voicemail Broadcast Groups 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
Lua Script Status

---

1. Module Overview (Technical)

What Are Voicemail Broadcast Groups?

Voicemail Broadcast Groups allow users to record a message once and have it delivered to multiple voicemail boxes simultaneously. This is ideal for company announcements, emergency notifications, or team updates.

Architecture

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              Voicemail Broadcast System                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  User dials: 8060 (broadcast group code)                        │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              Broadcast Group Lookup                      │   │
│  │  SELECT * FROM public.voicemail_broadcast_groups         │   │
│  │  WHERE code = '8060' AND enabled = true                  │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              Access Control                              │   │
│  │                                                          │   │
│  │  1. Check allowed_origins (if caller permitted)          │   │
│  │  2. Prompt for PIN (if password set)                     │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              Record Message                              │   │
│  │                                                          │   │
│  │  - Play instructions (unless skip_instructions)          │   │
│  │  - Record up to max_record_time seconds                  │   │
│  │  - Store in voicemail_broadcast storage                  │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              Distribute to Members                       │   │
│  │                                                          │   │
│  │  For each member extension:                              │   │
│  │  ├─ Copy message to member's voicemail folder           │   │
│  │  └─ Mark as new message                                  │   │
│  │                                                          │   │
│  │  Distribution modes:                                     │   │
│  │  ├─ Parallel: Send to all immediately                   │   │
│  │  ├─ Sequential: One by one                              │   │
│  │  └─ Active Only: Only registered extensions             │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼                                                         │
│  Send notification (email/API/event) if configured              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

Table	Purpose
`public.voicemail_broadcast_groups`	Group definitions
`public.voicemail_broadcast_group_members`	Member extensions
`public.sip_extensions`	Extension details for members

Storage Paths

Location	Purpose
`/var/lib/freeswitch/storage/voicemail_broadcast/`	Broadcast recordings
`/var/lib/freeswitch/storage/voicemail/default/{ext}/`	Destination folders

Key Files

File	Description
`admin/apps/web/src/modules/voicemailsBroadcastGroups/`	Frontend
`admin/apps/web/src/i18n/en/voicemailsBroadcastGroups.json`	Translations
`telephony/freeswitch/lua/main/xml_handlers/voicemail_broadcast/voicemail_broadcast.lua`	Lua handler

---

2. Module Overview (Commercial/Business)

Business Value

Voicemail Broadcast enables efficient mass communication:

Without Broadcast	With Broadcast
Leave individual voicemails	Record once, deliver to many
Call each person	One dial, all receive
Time-consuming	Instant distribution

Use Cases

Company Announcements

- Office closures, policy changes

- HR updates, benefits information

Emergency Notifications

- Building evacuations

- Weather-related closures

Team Updates

- Daily standup summaries

- Project status updates

Sales Teams

- New product information

- Pricing changes

Feature Highlights

Feature	Benefit
PIN Protection	Control who can broadcast
Skip Instructions	Faster recording for experienced users
Distribution Modes	Parallel, sequential, or active-only
Notifications	Email/API confirmation after broadcast
Allowed Origins	Restrict who can initiate broadcasts

---

3. Module Overview (End User/Administrator)

What Can You Do?

Create broadcast groups with specific extensions
Control access via PIN and allowed origins
Configure recording options (format, duration)
Set up notifications after broadcast completion

Administrator Workflow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│            Creating a Voicemail Broadcast Group                 │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Step 1: General Information                                    │
│  ├─ Code: 8060 (dial code)                                     │
│  ├─ Name: "All Staff"                                          │
│  └─ Description: "Company-wide announcements"                  │
│                                                                 │
│  Step 2: Access Control                                         │
│  ├─ Password: 1234 (optional PIN)                              │
│  ├─ Allowed Origins: 1001, 1002 (who can broadcast)            │
│  └─ Skip Instructions: ✓                                       │
│                                                                 │
│  Step 3: Recording Settings                                     │
│  ├─ Max Record Time: 120 seconds                               │
│  ├─ Record Format: WAV                                         │
│  └─ Delete After Broadcast: ✗                                  │
│                                                                 │
│  Step 4: Distribution                                           │
│  ├─ Distribution Mode: Parallel                                │
│  ├─ Notification: Email                                        │
│  └─ Notification Target: admin@company.com                     │
│                                                                 │
│  Step 5: Add Members (Extensions)                               │
│  ├─ 1001, 1002, 1003, 1004                                    │
│  └─ ... (all staff extensions)                                 │
│                                                                 │
│  Step 6: Enable and Save                                        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

User Workflow (Recording a Broadcast)

Plaintext

1. Dial 8060 (broadcast group code)
2. Enter PIN if prompted: 1234
3. Hear instructions (or skip if configured)
4. Record message (press # to stop)
5. Message delivered to all member voicemail boxes

Quick Tips

TIP

Allowed Origins: Limit who can initiate broadcasts to prevent abuse.

TIP

Skip Instructions: Enable for users who broadcast frequently.

CAUTION

Max Record Time: Keep reasonable to avoid very long messages.

---

4. Configuration Fields Reference

General Section

Field	Description	Example	Required
Code	Dialable group code	`8060`, `40`	Yes
Name	Display name	`All Staff`	Yes
Description	Optional notes	`Company-wide`	No
Password	Access PIN	`1234`	No
Skip Instructions	Skip recording prompt	On/Off	No
Enabled	Active status	On/Off	Yes

Recording Settings

Field	Description	Default	Options
Max Record Time	Max duration (seconds)	120	10-3600
Record Format	Audio file format	WAV	WAV, MP3, OGG
Delete After Broadcast	Remove original after delivery	Off	On/Off
Playback Volume	Volume for recipients	5	1-10
Announce Group Name	Say group name before message	Off	On/Off

Distribution Settings

Field	Description
Distribution Mode	How messages are delivered
Allowed Origins	Extensions permitted to broadcast

Distribution Modes:

Mode	Behavior
Parallel	Send to all members simultaneously
Sequential	Send one at a time in order
Active Only	Send only to registered/online extensions

Notification Settings

Field	Description
Notification Method	How to notify after broadcast
Notification Target	Destination (email, URL, event)

Notification Methods:

Method	Target Example
None	No notification
Email	admin@company.com
API	https://api.example.com/webhook
Event	broadcast_completed

---

5. Call Flow / Logic Explanation

Broadcast Flow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                    Broadcast Recording Flow                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. User dials 8060 (broadcast group code)                      │
│     │                                                           │
│     ▼                                                           │
│  2. Look up broadcast group                                     │
│     ├─ Found & enabled → Continue                              │
│     └─ Not found → "Feature not available"                     │
│     │                                                           │
│     ▼                                                           │
│  3. Check allowed_origins (if configured)                       │
│     ├─ Caller in list → Continue                               │
│     ├─ List empty → Anyone can broadcast                       │
│     └─ Caller NOT in list → "Not authorized"                   │
│     │                                                           │
│     ▼                                                           │
│  4. Prompt for PIN (if password set)                            │
│     ├─ Correct PIN → Continue                                  │
│     └─ Wrong PIN → "Not authorized"                            │
│     │                                                           │
│     ▼                                                           │
│  5. Play recording instructions (unless skip_instructions)      │
│     │                                                           │
│     ▼                                                           │
│  6. Record message (up to max_record_time, # to stop)           │
│     │                                                           │
│     ▼                                                           │
│  7. Save recording to broadcast storage                         │
│     │                                                           │
│     ▼                                                           │
│  8. Distribute to members based on distribution_mode            │
│     ├─ Copy to each member's voicemail folder                  │
│     └─ Mark as new message with MWI update                     │
│     │                                                           │
│     ▼                                                           │
│  9. Send notification (if configured)                           │
│     │                                                           │
│     ▼                                                           │
│  10. Delete original (if delete_after_broadcast = true)         │
│     │                                                           │
│     ▼                                                           │
│  11. Play "Message saved" confirmation                          │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

---

6. Common Scenarios & Examples

Scenario 1: Company-Wide Announcements

Setup:

Setting	Value
Code	8060
Name	All Staff
Password	1234
Allowed Origins	1001 (CEO), 1002 (HR)
Members	All employee extensions
Distribution	Parallel
Notification	Email to hr@company.com

Scenario 2: Emergency Broadcast

Setup:

Setting	Value
Code	911
Name	Emergency Alert
Password	(none - quick access)
Allowed Origins	Security team only
Skip Instructions	✓
Announce Group Name	✓

Scenario 3: Sales Team Updates

Setup:

Setting	Value
Code	8070
Name	Sales Team
Password	(none)
Allowed Origins	Sales manager only
Members	Sales team extensions
Delete After Broadcast	✓ (temporary updates)

---

7. Limitations & Important Notes

Technical Limitations

WARNING

Voicemail Required: Members must have voicemail enabled on their extensions.

WARNING

Storage Space: Long broadcasts to large groups consume significant disk space.

IMPORTANT

MWI Updates: Message Waiting Indicator may have slight delay after broadcast.

Best Practices

Limit Allowed Origins: Prevent unauthorized broadcasts
Use PINs: Add layer of security for sensitive groups
Keep Messages Short: Respectful of recipient time
Regular Cleanup: Enable delete_after_broadcast for temporary messages
Test First: Create a small test group before company-wide rollout

---

8. Troubleshooting Tips

Common Issues

Symptom	Possible Cause	Solution
"Not authorized"	Not in allowed_origins	Add caller to list
No message in VM	Member has no voicemail	Enable voicemail for extension
Recording too short	max_record_time too low	Increase limit
No MWI light	MWI not configured	Check extension voicemail settings

Diagnostic SQL

List broadcast groups:

Sql

SELECT code, name, enabled, 
       (SELECT COUNT(*) FROM public.voicemail_broadcast_group_members 
        WHERE voicemail_broadcast_group_id = g.id) as member_count
FROM public.voicemail_broadcast_groups g
WHERE domain_id = [domain_id];

Check group members:

Sql

SELECT e.extension, e.description
FROM public.voicemail_broadcast_group_members m
JOIN public.sip_extensions e ON m.sip_extension_id = e.id
WHERE m.voicemail_broadcast_group_id = [group_id];

---

9. Glossary

Term	Definition
Broadcast Group	Collection of extensions to receive broadcast messages
Broadcast	One message delivered to multiple voicemail boxes
Allowed Origins	Extensions permitted to initiate broadcasts
Distribution Mode	How messages are delivered (parallel/sequential)
MWI	Message Waiting Indicator (voicemail light on phone)
Skip Instructions	Skip the "record your message" prompt

---

10. Lua Script Status

Current Implementation Review

The Lua script at telephony/freeswitch/lua/main/xml_handlers/voicemail_broadcast/voicemail_broadcast.lua has been reviewed.

Issues Identified

Issue	Current	Should Be
Schema	`core.` tables	`public.` tables
Lookup field	`WHERE name = ?`	`WHERE code = ?`
Record time	Hardcoded 30s	Use `settings.max_record_time`
Format	Hardcoded .wav	Use `settings.record_format`
Allowed origins	Not implemented	Check `settings.allowed_origins`
Distribution mode	Not implemented	Implement parallel/sequential
Notifications	Not implemented	Implement email/API/event

Recommended Fixes

See the updated Lua script in the corrections below.

---

Documentation last updated: January 2026

Voicemail Broadcast Groups Module Documentation

Table of Contents

1. Module Overview (Technical)

What Are Voicemail Broadcast Groups?

Architecture

Key Tables

Storage Paths

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 (Recording a Broadcast)

Quick Tips

4. Configuration Fields Reference

General Section

Recording Settings

Distribution Settings

Notification Settings

5. Call Flow / Logic Explanation

Broadcast Flow

6. Common Scenarios & Examples

Scenario 1: Company-Wide Announcements

Scenario 2: Emergency Broadcast

Scenario 3: Sales Team Updates

7. Limitations & Important Notes

Technical Limitations

Best Practices

8. Troubleshooting Tips

Common Issues

Diagnostic SQL

9. Glossary

10. Lua Script Status

Current Implementation Review

Issues Identified

Recommended Fixes