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

FreePBX Dynamic Routes: bounded lookup-to-destination routing

Turn one documented DTMF, ODBC, URL, AGI or channel-variable lookup into an exact destination match while preserving support status, input, substitution, result, default path and external-system evidence.

Reviewed 2026-10-14Current Sangoma Dynamic Routes module, user-guide, example, support-classification and Module Admin documentation plus the FreePBX project article and contributed-module repository reviewed October 14, 2026; the module page says installations since FreePBX 15 can obtain Dynamic Routes from the Unsupported repository while the current category page describes these modules as community supported and not maintained by the core PBX Engineering team, so installed version, signature, support entitlement, lookup dependencies, generated dialplan, credentials, returned values and live routing remain deployment specific, and no PBX, module, database, ODBC source, URL, AGI script, channel, DTMF input, dialplan, destination or call was inspected or testedAdvancedDocumentation based · not lab tested

Record the module and support boundary first

The current Dynamic Routes overview says that since FreePBX 15 the module can be installed through Module Admin from the Unsupported repository. Sangoma's current category page describes the same family as community-supported modules whose maintenance is not owned by the core PBX Engineering team. Preserve both statements rather than relabeling the module as a standard supported feature.

Before designing a route, record the installed FreePBX branch, module name and version, signature state, repository channel and change owner. A current documentation page or repository branch is not proof that a particular PBX has a compatible, enabled or supported build.

Define one lookup contract before choosing a source

Write down the allowed input, the single value expected back, the exact result-to-destination table, invalid-input destination and default destination. Dynamic Routes documents MySQL, ODBC, URL, AGI and Asterisk-variable lookup sources; those are different trust, availability and parsing boundaries rather than interchangeable ways to obtain the same fact.

Use the narrowest source that already owns the decision. Keep caller identity, dialed DID, DTMF input, saved variables, external response and final destination as separate observations so a correct branch is not mistaken for proof that every upstream value was authentic.

Bound DTMF and channel-local saved variables

If caller input is enabled, set an explicit maximum digit count, timeout, validation expression, retry count, retry prompt and invalid destination. The guide documents saved input and result names for later Dynamic Routes, with DYNROUTE_-prefixed channel variables for dialplan use. These values last only while that channel is up.

Treat the input as untrusted. A format-valid value is not authorization, account ownership or consent, and a saved channel variable is not durable storage. Record each route in a chain and the exact name passed forward instead of assuming another channel or later call inherits it.

Make substitutions deliberate and results exact

Square brackets can trigger Dynamic Route variable substitution. The user guide explicitly warns that substitutions must be disabled when brackets in a query or destination are literal. Preserve the configured substitution state and the rendered lookup expression without exposing credentials or personal data.

Dynamic Route entries use an exact match against the returned result. Normalize the producer contract deliberately: plain-text URL output, ODBC value, AGI-set variable or Asterisk expression must yield the intended token without undocumented wrappers, extra fields or whitespace assumptions.

Give every miss an explicit, safe destination

The user guide strongly recommends a default destination and says a failed lookup or unmatched result can drop the call when no default exists. If intentional termination is required, choose the explicit Terminate Call destination rather than depending on an empty configuration.

Keep invalid DTMF, lookup failure, no result, unmatched result and an exact matched result as different branches. A fallback should provide safe service behavior without silently granting a privileged queue, external route or data-dependent treatment.

Test one bounded change and preserve rollback

Use an authorized non-production or controlled maintenance window to exercise one valid match, one invalid input, one empty or failed lookup and one unmatched result. Record the generated dialplan revision, source type, sanitized request or query fingerprint, returned token, chosen destination and call-channel identifiers.

External databases, URLs and AGI scripts need their own least-privilege credentials, certificate and network controls, logging, availability expectations and change owners. The published examples are starting points, not proof of security, compatibility or production fitness. This guide is documentation-derived; no module, lookup or call was 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

Hub

FreePBX

Plan and administer a FreePBX 17 system on Debian 12 using the supported project installation path.

Explore topic →
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 →
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 →
Guide · FreePBX CallerID Lookup release/17.0 repository, module metadata, generated-dialplan source and configuration class plus current Asterisk caller-ID, party-ID, internal-database and TXTCIDNAME documentation reviewed October 12, 2026; repository metadata reports module 17.0.1.1 and FreePBX 17.0 support but does not establish the installed module, saved source, inbound-route assignment, generated or loaded dialplan, database value, external response, channel identity, endpoint display or call result; no PBX, module, source, credential, database, cache, route, call or endpoint was inspected or tested

FreePBX Caller ID Lookup Sources: route, source, cache and displayed-name evidence

Follow one incoming number through the matched inbound route, selected lookup source, returned value, optional AstDB cache, channel caller name and final endpoint display.

Read guide →
Guide · Sangoma Custom Destinations, Misc Applications and Misc Destinations guidance; FreePBX Custom Applications 17.0.1 and Misc Applications 17.0.3 release/17.0 metadata and current dialplan sources; and current Asterisk Goto, Gosub, Return and dialplan documentation reviewed October 11, 2026; older screen guides establish concepts rather than an exact FreePBX 17 field map, and no installed module, code, application, destination, generated or loaded dialplan, caller path or call was inspected or tested

FreePBX Custom Destinations: publish custom dialplan without losing ownership

Register a reviewed context, extension and priority as a managed destination, choose transfer or subroutine behavior deliberately, and keep source, generated state and call results separate.

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 · Operational guidance; Asterisk 22 / FreePBX 17 where applicable

Least privilege for PBX users and integrations

Separate the right to register, place calls, administer the PBX and read sensitive data.

Read guide →
Troubleshooting · Current Sangoma Dynamic Routes module, user-guide, example, support-classification and Module Admin documentation plus the FreePBX project article and contributed-module repository reviewed October 14, 2026; the module page says installations since FreePBX 15 can obtain Dynamic Routes from the Unsupported repository while the current category page describes these modules as community supported and not maintained by the core PBX Engineering team, so installed version, signature, support entitlement, lookup dependencies, generated dialplan, credentials, returned values and live routing remain deployment specific, and no PBX, module, database, ODBC source, URL, AGI script, channel, DTMF input, dialplan, destination or call was inspected or tested

FreePBX Dynamic Route picks the wrong destination or drops the call

Find the first mismatch among module state, caller input, variable substitution, lookup source, returned text, exact entry match, invalid branch, default destination and generated dialplan.

Read guide →