VoIP.infoThe independent guide to business communications.
VoIP.info Guide

FreePBX Route Congestion Messages: prompt, tone and route-class boundaries

Keep the original outbound failure, selected route class, optional congestion destination, generated failure branch, chosen System Recording or tone, and final audible result as separate evidence.

Reviewed 2026-10-12FreePBX Route Congestion Messages release/17.0 repository, metadata and generated dialplan, FreePBX core outbound-routing source, Sangoma route and System Recordings documentation, and Asterisk Dial, Playback and hangup-cause documentation reviewed October 12, 2026; module 17.0.1 is repository metadata rather than proof of an installed version, and the exact PBX, module, route, trunk, recording, generated or loaded dialplan, failure response, call and audible result remain deployment-specific and untestedAdvancedDocumentation based · not lab tested

Place the message after one proven route and trunk sequence

First preserve the dialed digits, caller, selected outbound route, attempted trunks in order, each Dial result, final SIP response and Asterisk channel outcome. A congestion announcement is a summary delivered after the attempt path; it is not proof that the carrier lacked circuits, the trunk was registered, the number pattern matched correctly or every configured trunk was tried.

Use the all-circuits-busy diagnostic when the audible message is the symptom. Correct the route or trunk evidence before changing the message that describes its failure.

Separate default, intra-company and emergency route classes

The reviewed release/17.0 source generates distinct selections for the default path, an intra-company route and an emergency route. Confirm which route actually matched and which route-class flag reached the failure branch before expecting a particular recording or tone. A label, route position or saved checkbox does not prove that the live call entered that class.

Treat emergency behavior as a safety boundary. Do not place an unapproved emergency test call merely to hear a prompt. Confirm current carrier, location and fallback requirements, keep accessible alternatives available, and use the provider-approved validation process.

Keep the module prompt separate from the route congestion destination

FreePBX core exposes an optional congestion destination on an outbound route, while Route Congestion Messages generates the macro-outisbusy failure treatment. Record both controls separately: the route selected by the call, whether that route has an alternate congestion destination, and which generated message branch remains reachable.

Do not assume that changing the module-wide prompt overrides a route-specific alternate destination, or that a route destination proves which recording played. Preserve the actual dialplan branch and the final channel path.

Trace the selected recording into generated and loaded dialplan

The module can use its default all-circuits-busy and try-later prompts, a selected System Recording, or congestion tones. Keep the System Recording identity and media files separate from the module selection, generated macro-outisbusy lines, loaded Asterisk dialplan, Playback status and what the caller heard.

The reviewed source resolves a selected recording through FreePBX recording data and falls back to the default when the resulting file value is empty. A visible selection therefore does not prove that the referenced media exists, decodes on the channel or was loaded after Apply Config.

Preserve DIALSTATUS, HANGUPCAUSE and the original SIP result

Capture DIALSTATUS, per-channel HANGUPCAUSE, the technology-specific cause and the original SIP final response before the prompt, congestion application or final Hangup replaces the caller-facing experience. Use Asterisk cause mappings as interpretation aids, not as a guarantee that every provider maps the same response or supplies the same Reason header.

Keep a route-selection failure, trunk rejection, authentication failure, no response, busy destination and local resource failure separate even if callers hear the same message. The prompt should remain useful and neutral without concealing the evidence needed to diagnose the underlying condition.

Retest a bounded failure matrix and preserve rollback

After one evidenced change, retest an authorized non-emergency number for the default class and, only where applicable, a controlled intra-company route. Prove the selected route, attempted trunks, original result, expected fallback branch, selected recording or tone, intelligible audio and clean release. Test the successful-call path separately so the failure treatment cannot intercept valid calls.

Record the prior module selection, route destination, System Recording reference and generated output for rollback. This workflow is derived from first-party source and documentation; no PBX, module, route, trunk, recording, call or emergency service was inspected or tested.

Sources & applicability

Primary references for the technical details above. Operational examples and planning checklists are VoIP.info editorial guidance.

Examples require adaptation to your topology. No live PBX or hardware testing is claimed.

Continue your research

Guide · FreePBX 17 on Debian 12; route semantics cross-checked against Sangoma PBX GUI 13 guides and current FreePBX Blacklist 17.0.1.2 release/17.0 source on October 11, 2026; exact installed modules, generated or loaded route hooks and calls were not tested

FreePBX inbound and outbound routes

Follow the incoming number and outgoing dial pattern as two separate routing decisions.

Read guide →
Troubleshooting · FreePBX 17 with Asterisk 22 LTS terminology; exact dialplan, modules and carrier responses require inspection

FreePBX says all circuits are busy after an outbound dial

Treat the announcement as a dial failure summary, then find the selected route, attempted trunk and original SIP result.

Read guide →
Guide · FreePBX 17 on Debian 12; System Recordings module, consuming module and Asterisk version must be verified on the installed host

FreePBX System Recordings: reusable audio, language and replacement boundaries

Manage the reusable recording object, its ordered media, language and rerecording controls separately from Announcements, IVRs and other call-flow consumers.

Read guide →
Guide · FreePBX 17 / Debian 12; module UI varies

FreePBX outbound restrictions and emergency routes

Separate extension permissions, number normalization and carrier authorization.

Read guide →
Guide · Current Asterisk branch-23-generated HANGUPCAUSE, HANGUPCAUSE_KEYS, HangupCauseClear, Dial and CHANNEL references plus the project mapping table reviewed October 6, 2026; exact behavior still depends on the installed Asterisk branch, channel driver, dialplan and call path

Asterisk hangup causes: preserve each called-channel result

Interpret Dial status, per-channel technology causes, translated Asterisk causes and hangup source without collapsing parallel or sequential call attempts into one reason.

Read guide →
Troubleshooting · Current Sangoma outbound-route guidance, current Asterisk Dial and troubleshooting documentation, and SIP standards reviewed October 5, 2026; no phone, PBX, carrier or live call test

Outbound VoIP calls fail: locate the broken call leg

Classify one failed call, then follow the exact digits through the phone, PBX route, attempted trunk, remote response, answer and media.

Read guide →
Guide · FreePBX 17 on Debian 12; Bulk Handler 17.0.7.1 release/17.0 metadata and Sangoma Bulk Handler workflow reviewed October 11, 2026; repository state does not prove the installed module or runtime, and no import or Apply Config operation was tested

FreePBX changes: submit, apply and verify

Keep GUI settings, generated configuration and runtime behavior aligned during routine administration.

Read guide →
Guide · FreePBX 17 / Debian 12; module UI varies

FreePBX module administration and updates

Inventory module state, preview dependencies and signatures, change the smallest intended set, and prove reload and call behavior before closing the window.

Read guide →