--- title: "Voicemail Broadcast Groups Module Documentation" description: "Documentation for Voicemail Broadcast" --- ## Table of Contents 1. [Module Overview (Technical)](#1-module-overview-technical) 2. [Module Overview (Commercial/Business)](#2-module-overview-commercialbusiness) 3. [Module Overview (End User/Administrator)](#3-module-overview-end-useradministrator) 4. [Configuration Fields Reference](#4-configuration-fields-reference) 5. [Call Flow / Logic Explanation](#5-call-flow--logic-explanation) 6. [Common Scenarios & Examples](#6-common-scenarios--examples) 7. [Model Context Protocol (MCP) AI Integration](#7-model-context-protocol-mcp-ai-integration) 8. [Limitations & Important Notes](#8-limitations--important-notes) 9. [Troubleshooting Tips](#9-troubleshooting-tips) 10. [Glossary](#10-glossary) --- ## 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 ``` ┌─────────────────────────────────────────────────────────────────┐ │ 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 │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Storage Paths | Location | Purpose | |----------|---------| | `/var/lib/freeswitch/storage/voicemail_broadcast/` | Broadcast recordings | | `/var/lib/freeswitch/storage/voicemail/default/{ext}/` | Destination folders | --- ## 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 1. **Company Announcements** - Office closures, policy changes - HR updates, benefits information 2. **Emergency Notifications** - Building evacuations - Weather-related closures 3. **Team Updates** - Daily standup summaries - Project status updates 4. **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 designated member extensions. - Protect broadcast initiation with security PIN codes. - Restrict broadcast transmission to authorized origin extensions. - Configure recording options (audio formats, duration limits, prompt skipping). - Set up real-time delivery notifications via Email, Webhook API, or System Event. ### Navigation 1. In the main navigation bar, select **PBX Engine → Applications → Voicemail Broadcast** (or navigate directly to `/pbx/applications/voicemail-broadcast`). 2. The **list view** displays all configured voicemail broadcast groups, highlighting the dialable Code, Group Name, Context, Member Count, and active Status (Enabled/Disabled). 3. Click the **+ Add** button in the upper action toolbar to create a new broadcast group. 4. Click any existing record row or edit icon to open the configuration form. ![Voicemail Broadcast List View](/screenshots/pbx/applications/voicemail-broadcast-list.png) ### Administrator Workflow ``` ┌─────────────────────────────────────────────────────────────────┐ │ Creating a Voicemail Broadcast Group │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Step 1: General Information │ │ ├─ Code: *88 (dial code) │ │ ├─ Name: "Corporate All-Hands Announcement" │ │ ├─ Password: **** (PIN protection) │ │ └─ Skip Instructions: Enabled (fast recording mode) │ │ │ │ Step 2: Delivery & Distribution Settings │ │ ├─ Distribution Mode: Parallel (simultaneous distribution) │ │ ├─ Max Record Time: 300 seconds │ │ ├─ Record Format: WAV (uncompressed audio quality) │ │ └─ Playback Volume: 5 (balanced amplification) │ │ │ │ Step 3: Group Members & Authorized Origins │ │ ├─ Select member extensions via multi-select modal │ │ └─ Configure notification alert (Email / API / Event) │ │ │ │ Step 4: Enable and Save Form │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ### User Workflow (Recording a Broadcast) ``` 1. Dial the assigned broadcast group code (e.g. *88) from an authorized extension. 2. If a password is configured, enter the PIN followed by '#' when prompted. 3. Listen to instructions (or immediately hear the recording beep if "Skip Instructions" is active). 4. Speak the message clearly into the handset and press '#' when finished. 5. The PBX automatically processes and places the message into all member voicemail boxes simultaneously. ``` ### Quick Tips > [!TIP] > **Allowed Origins**: When configured, only callers originating from the specified extensions can dial the broadcast code. This prevents unauthorized callers from triggering announcements. > [!TIP] > **Skip Instructions**: Enable this toggle for experienced department heads so they can start dictating immediately after the tone. > [!CAUTION] > **Max Record Time**: Set an appropriate limit (e.g., 180–300 seconds) to prevent accidental continuous recording that consumes server storage. --- ## 4. Configuration Fields Reference ![Voicemail Broadcast Configuration Form](/screenshots/pbx/applications/voicemail-broadcast-form.png) ### General Information Box | Field | Description | UI Tooltip | Example | Notes | |-------|-------------|------------|---------|-------| | **Code \*** | Dialable shortcode for this broadcast group | Dialable shortcode used by callers to record and trigger the broadcast | `*88`, `8060` | Must be unique across PBX dialables. Required. | | **Name \*** | Administrative display label | Friendly name identifying this broadcast group | `Corporate All-Hands Announcement` | Required. | | **Password** | Security PIN code required to authenticate before recording | Optional PIN code required by callers before recording a broadcast message | `1234`, `8899` | Numeric PIN. Optional. | | **Skip Instructions** | Bypass pre-recording audio guidance | Bypass voice instructions and prompt directly with a beep for recording | `Enabled` / `Disabled` | Toggle. Default: `Disabled`. | | **Enabled** | Master operational status | Master toggle to activate or deactivate this broadcast group | `Enabled` / `Disabled` | Toggle. Default: `Enabled`. | ### Settings & Distribution Box | Field | Description | UI Tooltip | Default | Options / Range | |-------|-------------|------------|---------|-----------------| | **Announcement Path** | Introductory prompt played before recording or to recipients | Custom voice announcement played prior to recording or playback | None (Default beep) | Dropdown selection from system Audio Recordings library. | | **Distribution Mode** | Delivery strategy for placing voicemails | How audio payloads are distributed to member mailboxes | `Parallel` | `Parallel` (Simultaneous delivery to all mailboxes), `Sequential` (Delivered one mailbox at a time), `Active Only` (Delivered only to registered/online devices). | | **Notification Method** | Alert mechanism sent when distribution completes | Delivery mechanism for broadcast completion notifications | `None` | `None`, `Email`, `API` (HTTP Webhook POST), `Event` (Internal PBX event bus). | | **Notification Target** | Destination address for completion alerts | Target recipient email address or HTTP webhook URL | None | Required when Notification Method is not `None`. Example: `admin@ring2all.com` or `https://crm.company.com/webhooks/vm`. | | **Max Record Time** | Maximum recording duration in seconds | Maximum allowable length for the recorded announcement in seconds | `300` | Integer: `10` to `3600` seconds. | | **Max Retry** | Retry delivery attempts upon temporary lock | Maximum retry attempts if a target mailbox is locked or busy | `3` | Integer: `0` to `10`. | | **Record Format** | Audio codec container for the stored message | Audio file encoding format for the broadcast recording | `WAV` | `WAV` (PCM uncompressed, 8kHz/16kHz), `MP3` (MPEG audio), `OGG` (Vorbis compressed). | | **Delete After Broadcast** | Purge master spool file after distribution | Automatically delete master recording from temporary broadcast spool once distributed | `Disabled` | Toggle. Keeps individual mailbox copies intact while freeing master spool storage. | | **Announce Group Name** | Speak group name prefix before message audio | Play the broadcast group's recorded title before playing the broadcast payload | `Disabled` | Toggle. Useful when users belong to multiple broadcast groups. | | **Playback Volume** | Audio gain amplification for recipients | Volume amplification level for recipients when listening to the message | `5` | Interactive slider: `1` (Quiet) to `10` (Maximum amplification). | | **Group Members / Allowed Origins** | Extensions authorized to trigger and receive broadcasts | Select member extensions that receive the voicemail broadcast and are permitted to initiate recordings | All Extensions | Interactive multi-select button opening search modal with extension name and numbering. | --- ## 5. Call Flow / Logic Explanation ### Broadcast Flow ``` ┌─────────────────────────────────────────────────────────────────┐ │ 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. Model Context Protocol (MCP) AI Integration Ring2All exposes comprehensive Model Context Protocol (MCP) tools for **Voicemail Broadcast Groups**, empowering AI voice agents and Copilots to query broadcast distribution groups, inspect subscribed member extensions, and provision or adjust announcement groups while enforcing domain-level numbering isolation. ### Available MCP Tools | Tool Name | Description | Key Parameters | |:---|:---|:---| | `list_voicemail_broadcast_groups` | Lists all voicemail broadcast groups in the domain, including dial codes, group names, descriptions, and member counts. | `search` (optional string) | | `get_voicemail_broadcast_group_status` | Retrieves full group configuration and the list of destination extension mailboxes for a specific broadcast code. | `code` (required) | | `create_voicemail_broadcast_group` | Creates a new broadcast group with a dial code, group name, description, and an initial array of recipient extensions. | `code`, `name`, `description`, `members` (array of extension numbers) | | `update_voicemail_broadcast_group` | Modifies broadcast group parameters such as name, description, membership list, or enabled status. | `currentCode`, `newCode`, `name`, `description`, `members`, `enabled` | | `delete_voicemail_broadcast_group` | Deletes a voicemail broadcast group and de-registers its dial code from the PBX dialplan. | `code` (required) | ### Strict Domain Numbering Safeguards When an AI agent executes `create_voicemail_broadcast_group` or `update_voicemail_broadcast_group`, Ring2All runs `validateNumberUniqueness(code, domain.id, 'voicemail_broadcast')`. The code is checked against `sip_extensions`, `public.dialplan_registry`, and `public.direct_routes`. A broadcast dial code (e.g. `*85` or `8060`) can never collide with an existing extension, paging group, speed dial, or conference room in the same domain. ### AI Agent Operational Examples #### Inspecting Voicemail Broadcast Group Details ```json { "tool": "get_voicemail_broadcast_group_status", "arguments": { "code": "8060" } } ``` #### Provisioning an Emergency Department Voicemail Broadcast Group ```json { "tool": "create_voicemail_broadcast_group", "arguments": { "code": "8070", "name": "Warehouse Leads Broadcast", "description": "Mass announcement drop for logistics leads", "members": ["1001", "1002", "1005"] } } ``` ### Recommended Natural Language Prompts - *"List all voicemail broadcast groups and tell me how many recipient extensions each one has."* - *"Create a voicemail broadcast group with code 8080 named 'Emergency Response' sending to extensions 101, 102, and 103."* - *"Show me which extensions receive broadcasts when dialing code 8060."* --- ## 8. 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 1. **Limit Allowed Origins**: Prevent unauthorized broadcasts 2. **Use PINs**: Add layer of security for sensitive groups 3. **Keep Messages Short**: Respectful of recipient time 4. **Regular Cleanup**: Enable delete_after_broadcast for temporary messages 5. **Test First**: Create a small test group before company-wide rollout --- ## 9. 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]; ``` --- ## 10. 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 | --- *Documentation last updated: January 2026*