VoIP.info Guide

FreeSWITCH XML dialplan: evaluation and execution

Understand contexts, conditions and queued applications before building a routing rule.

Reviewed 2026-09-07FreeSWITCH 1.11.3 release reference; verify installed modules and package supportIntermediateDocumentation based · not lab tested

Read the evaluation model

The XML dialplan groups extensions and conditions within contexts. Conditions determine which actions are selected, and actions normally execute after dialplan evaluation. This differs from assuming each action immediately changes the values used by the very next condition during the same evaluation pass. Supported inline actions are an explicit exception. Not every application can run inline. Keep preprocessor variables, runtime channel variables and regex captures distinguishable when reading an example.

FreeSWITCH configuration has distinct responsibilities
A SIP profile defines a listener and transport behavior, the directory supplies user identity, and the dialplan selects actions. Media modules execute the application path. FusionPBX manages configuration above FreeSWITCH.

Conceptual responsibilities, not a file-loading sequence. FusionPBX is an administration layer; edits to generated configuration can be replaced by its management workflow.

Keep untrusted entry points narrow

Identify the context selected for an incoming call and the source of that assignment. A public inbound context should reach only the destinations intended for untrusted callers. A broad route into privileged outbound logic can turn a working PBX into an unauthorized transit service. Create one explicit test destination and an intentional unmatched-number result. Verify which condition matched and which application executed. When transferring back into the dialplan, inspect the new destination and context rather than assuming the original route continues unchanged.

Test both matches and misses

Use valid local numbers, invalid numbers and destinations the caller is not permitted to reach. Include a busy or unavailable destination and confirm the fallback. For a variable-dependent route, log a non-sensitive value at the relevant stage so the evaluation order is observable. If a management interface owns the dialplan, use its supported editing mechanisms. Retain the previous rule and a recovery path. A syntactically valid XML file can still implement the wrong permissions or route every unmatched call into the wrong tenant.

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.