Announcements Module Documentation

Module Overview (Technical)
Module Overview (Commercial/Business)
Module Overview (End User/Administrator)
Configuration Fields Reference
Destination Routing
Common Scenarios & Examples
Limitations & Important Notes
Troubleshooting Tips
Glossary

---

1. Module Overview (Technical)

What Are Announcements?

Announcements are audio playback elements that play a recorded message to callers and then optionally route to a destination. They're used for greetings, information messages, hold messages, or any pre-recorded content.

Architecture

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                  Announcement Flow                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Call enters (via inbound route, IVR, etc.)                     │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                 announcement.lua                         │   │
│  │                                                          │   │
│  │  1. Lookup announcement in public.announcements          │   │
│  │  2. Get recording path from public.voice_recordings      │   │
│  │  3. Answer call                                          │   │
│  │  4. Play audio (streamFile)                              │   │
│  │  5. Route to destination or hangup                       │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ├── Has Destination? ────────────────────────────────►    │
│       │       Yes → Route to extension/IVR/queue/etc.          │
│       │                                                         │
│       └── No Destination ──────────────────────────────────►    │
│               Hangup (NORMAL_CLEARING)                          │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

Table	Purpose
`public.announcements`	Announcement definitions
`public.voice_recordings`	Audio file references

Key Files

File	Description
`admin/apps/web/src/modules/announcements/`	Frontend module
`admin/apps/web/src/i18n/en/announcements.json`	Translations
`telephony/freeswitch/lua/main/xml_handlers/routing/announcement.lua`	Main handler

---

2. Module Overview (Commercial/Business)

Business Value

Announcements enable professional audio messaging:

Without Announcements	With Announcements
No welcome message	Professional greeting
Manual information	Automated notices
No after-hours message	After-hours recording
Generic experience	Branded audio experience

Use Cases

Welcome Greeting

- "Thank you for calling ABC Company"

- Play before IVR or queue

After-Hours Message

- "Our office is closed. Leave a message..."

- Route to voicemail

Holiday Notice

- "We are closed for the holiday..."

- Hangup or route to on-call

Queue Position

- "You are caller #3 in line..."

- Continue to hold

Legal Disclaimers

- "This call may be recorded..."

- Route to agent

Feature Highlights

Feature	Benefit
Audio Playback	Play any recording
Optional Destination	Route after playback
Multiple Modules	Route to extension, IVR, queue, etc.
Repeat Option	Play multiple times
Interrupt Option	Allow DTMF skip
Post-Delay	Pause before routing

---

3. Module Overview (End User/Administrator)

What Can You Do?

Create named announcements
Link to audio recordings
Configure optional destination
Set playback options (repeat, interrupt)
Add post-playback delay
Choose transfer behavior

Administrator Workflow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              Creating an Announcement                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Tab: General                                                   │
│  ├─ Name: "Welcome Message"                                    │
│  ├─ Description: "Main greeting for callers"                   │
│  ├─ Recording: [Select] welcome.wav                            │
│  ├─ Destination Type: IVR                                      │
│  ├─ Destination: Main Menu                                     │
│  └─ Enabled: ✓                                                 │
│                                                                 │
│  Tab: Advanced Settings                                         │
│  ├─ Allow Interrupt with Keypress: Off                         │
│  ├─ Terminator Key: #                                          │
│  ├─ Pause After Playback (ms): 500                             │
│  ├─ Repeat Announcement: 1                                     │
│  ├─ Transfer Behavior: Immediate                               │
│  ├─ Announcement Mode: Play Once                               │
│  ├─ Play Beep Before Message: Off                              │
│  └─ Record Call: Off                                           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Tips

TIP

Short Messages: Keep announcements under 30 seconds for best experience.

TIP

Allow Skip: Enable keypress interrupt for returning callers.

CAUTION

Recording Required: Announcement must have a linked audio file.

---

4. Configuration Fields Reference

General Fields

Field	Description	Example
Name	Unique identifier	`Welcome Message`
Description	Optional notes	`Main greeting`
Recording	Audio file	`welcome.wav`
Enabled	Announcement active	On/Off

Destination Fields

Field	Description
Destination Type	Module to route to
Destination Value	Specific target

Destination Types

Type	Description
Extension	Route to extension
Voicemail	Route to voicemail
IVR	Route to IVR menu
Conference	Route to conference
Queue	Route to call queue
Hangup	Terminate call
Park	Park the call

Advanced Settings

Field	Description	Default
Allow Interrupt	DTMF skip enabled	Off
Terminator Key	Key to skip (# or )	#
Pause After Playback	Delay in ms	0
Repeat Announcement	Times to play (1-5)	1
Transfer Behavior	When to route	Immediate
Announcement Mode	Play Once/Loop/Background	Once
Beep Before Message	Alert beep	Off
Record Call	Record session	Off

---

5. Destination Routing

How Routing Works

After the announcement plays, the handler routes based on destination_module:

Lua

if destination_module == 'extension' then
    execute routing/extension.lua
elseif destination_module == 'ivr' then
    transfer to IVR
elseif destination_module == 'queue' then
    execute routing/queue.lua
elseif destination_module == 'voicemail' then
    transfer to voicemail
-- ... etc
else
    hangup
end

Supported Modules

Module	Handler
extension	`routing/extension.lua`
ivr	Transfer to IVR
conference	`routing/conference.lua`
ring_group	`routing/ring_group.lua`
queue	`routing/queue.lua`
voicemail	Transfer
direct_route	Transfer (public)
announcement	`routing/announcement.lua`
call_flow	`routing/call_flow.lua`
time_condition	`routing/time_condition.lua`
language	`routing/language.lua`
direct_dial	`routing/direct_dial.lua`

---

6. Common Scenarios & Examples

Scenario 1: Welcome + IVR

Announcement: "Welcome"

Setting	Value
Recording	welcome.wav
Destination Type	IVR
Destination	Main Menu

Flow:

"Thank you for calling ABC Company"
→ Route to Main Menu IVR

Scenario 2: After-Hours + Voicemail

Announcement: "After Hours"

Setting	Value
Recording	after-hours.wav
Destination Type	Voicemail
Destination	General Mailbox

Flow:

"Our office is closed. Please leave a message..."
→ Route to General Voicemail

Scenario 3: Holiday Closure (No Destination)

Announcement: "Holiday"

Setting	Value
Recording	holiday.wav
Destination Type	Hangup
Destination	NORMAL_CLEARING

Flow:

"We are closed for the holiday..."
→ Hangup

Scenario 4: Legal Disclaimer + Queue

Announcement: "Recording Notice"

Setting	Value
Recording	recording-notice.wav
Destination Type	Queue
Destination	Support Queue
Allow Interrupt	Off

Flow:

"This call may be recorded for quality assurance..."
→ Route to Support Queue

---

7. Limitations & Important Notes

Technical Notes

NOTE

Case-Insensitive: Announcement lookup is case-insensitive.

WARNING

Recording Required: Without recording, playback is skipped.

WARNING

Call Must Be Answered: Audio requires answered call.

Best Practices

Short Audio: Keep under 30 seconds
Professional Quality: Use clear, well-recorded audio
Always Test: Verify playback works correctly
Set Destination: Configure where to route after
Use Categories: Organize by purpose (greeting, info, legal)

---

8. Troubleshooting Tips

Common Issues

Symptom	Possible Cause	Solution
No audio	Missing recording	Upload audio file
Wrong destination	Module misconfigured	Check destination settings
Audio cut off	Call not answered	Ensure call is answered
Not found	Name mismatch	Verify announcement name
No routing	Empty destination	Set destination or hangup

Diagnostic SQL

List announcements:

Sql

SELECT a.id, a.name, a.enabled, 
       a.destination_module, a.destination_data,
       r.file_path
FROM public.announcements a
LEFT JOIN public.voice_recordings r ON r.id = a.recording_id
WHERE a.domain_id = [domain_id];

FreeSWITCH Logs

Bash

# Check announcement playback
grep "announcement" /var/log/freeswitch/freeswitch.log
grep "streamFile" /var/log/freeswitch/freeswitch.log

---

9. Glossary

Term	Definition
Announcement	Audio message playback element
Recording	Audio file to play
Destination	Where to route after playback
Terminator	DTMF key to skip audio
Post-Delay	Pause after playback
Loop Mode	Continuous repeat

---

Lua Script Status ✅

Already Correct

Script	Status
`routing/announcement.lua`	✅ Uses `public.announcements`, `public.voice_recordings`

No Lua fixes needed!

---

Documentation last updated: January 2026*

Announcements Module Documentation

Table of Contents

1. Module Overview (Technical)

What Are Announcements?

Architecture

Key Tables

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

Quick Tips

4. Configuration Fields Reference

General Fields

Destination Fields

Destination Types

Advanced Settings

5. Destination Routing

How Routing Works

Supported Modules

6. Common Scenarios & Examples

Scenario 1: Welcome + IVR

Scenario 2: After-Hours + Voicemail

Scenario 3: Holiday Closure (No Destination)

Scenario 4: Legal Disclaimer + Queue

7. Limitations & Important Notes

Technical Notes

Best Practices

8. Troubleshooting Tips

Common Issues

Diagnostic SQL

FreeSWITCH Logs

9. Glossary

Lua Script Status ✅

Already Correct