FreePBX inbound and outbound routes

Keep the documentation version visible

Sangoma's detailed Inbound Routes and Outbound Routes field guides are explicitly labelled for PBX GUI 13, while the current FreePBX 17 installation path uses Debian 12. Their routing model remains useful evidence, but an installed FreePBX 17 system can expose different fields through its module versions and licensed add-ons.

Confirm the running FreePBX, Core and route-module versions before following a screenshot or field location. This guide uses the older pages for documented semantics and does not present their interface as an exact FreePBX 17 screen map.

Inbound and outbound routing are separate

Trace inbound DID and CID precedence

An inbound route can match the delivered DID, caller ID or both, then send the call to a destination such as a time condition, IVR or extension. The DID must match the format the provider actually sends; an account number or invoice display is not enough. A route with blank DID and CID fields matches calls with any or no such information and is therefore a catch-all, not proof that trunk identification is correct.

The version-13 guide documents this normal order: specific DID plus CID, specific DID alone, CID alone, then blank catch-all. CID Priority can move a CID-only route ahead of a DID-only route, but a specific DID-plus-CID route still wins. Capture the Request-URI, To header and caller identity from a redacted inbound attempt before changing these match fields.

Separate outbound route selection from trunk order

FreePBX evaluates outbound routes from highest to lowest priority and stops at the first route whose dial pattern matches; it does not continue looking for a more specific route below it. A broad earlier route can therefore intercept a later one. Time-group handling can make a route unavailable and allow evaluation to continue, so preserve the active time policy in the evidence.

Only after a route matches does its trunk sequence apply. That sequence is not another route search. Record the selected route, transformed number, first attempted trunk, response and any advance to a later trunk instead of describing every failed call as provider failover.

Write each number transformation once

An outbound route pattern can match a number, remove a prefix and prepend digits before handing the result to a trunk. The trunk can then perform another prefix, match and prepend transformation. Sangoma distinguishes their responsibilities: outbound routes decide what numbers are allowed and select a path, while trunk rules only add or subtract digits from the number already passed down.

Write a table containing the user-dialed value, matched route, route output, matched trunk rule and provider-facing value. Use constrained patterns where possible. Asterisk warns that dot and exclamation wildcards match characters as well as digits, so a broad pattern is also a security boundary rather than merely a dialing convenience.

Prove the trunk-advance trigger

Sangoma's trunk guide says a later trunk is normally tried when the current trunk is congested or unavailable. The separate Continue if Busy option can also advance after BUSY or INVALID NUMBER, and the guide says it should normally remain unchecked. Preserve that distinction: a destination rejection, user busy response and transport outage should not silently share one recovery policy.

The route can also have an optional congestion destination. Confirm the actual SIP or channel result that triggered the next trunk or destination, the caller ID used on that path, and whether the alternate trunk has compatible number, emergency and commercial policy.

Give emergency routing its own acceptance path

Sangoma documents a dedicated Emergency route near the top of the outbound-route order with a direct 911 match that does not require a prefix. The Emergency route type, route caller ID, per-extension Emergency CID, selected trunk and endpoint digit map are separate controls. The provider's registered dispatchable location and approved test procedure remain outside FreePBX route matching.

Do not place a live emergency call as an informal test. Validate direct dialing, location-specific caller identity, provider provisioning, on-site notification and an approved non-emergency test path with the responsible provider and emergency-program owner.

Apply, inspect and test a bounded matrix

Submit stores the route edit; Apply Config is the documented step that makes the change active. Saved GUI state, generated dialplan, loaded Asterisk state and a completed call are separate acceptance stages. Inspect the running route order and dialplan when runtime behavior differs rather than editing generated configuration as the durable source.

Test an allowed number, an intentionally denied number, overlap with a broader route, each intended trunk-advance condition, the exact incoming DID, a DID-plus-CID case, catch-all behavior and an after-hours destination. Record the observed route, trunk and final destination—not only ringing—and keep an export or rollback record before restructuring working routes.

Record the inbound-route music category as one precedence layer

The Music on Hold guide shows how a call-target category can temporarily override the category inherited from an inbound route. Trace the target entered and left before treating the route's selection as the runtime class.

Place PIN enforcement after a proven route match

The PIN Sets guide treats the selected set as a gate on the outbound route, not as the route selector itself. A broader earlier pattern can bypass the protected route; use the paired diagnostic to preserve route order, prompt result and trunk outcome as separate stages.

Prove where the inbound blacklist hook runs

Current FreePBX release/17.0 source inserts its blacklist check into generated inbound DID contexts, including a CID-priority route form. Use the Blacklist guide and paired diagnostic to prove the call selected that loaded route before changing the stored list.

Keep fax branch selection observable

For dedicated and mixed-use DIDs, the FreePBX fax guide records the normal and fax destinations separately from Asterisk transfer and later delivery. If ReceiveFAX succeeded but email or UCP did not, move to the post-receipt diagnostic.

Preserve both sides of a Callback

A FreePBX Callback ends an inbound leg and creates a chargeable outbound leg. The Callback guide keeps caller identity, number normalization, route authorization, carrier result and later destination separate.

Keep the route failure path distinct from its caller-facing message

After an outbound route and its ordered trunks fail, use the Route Congestion Messages guide to distinguish the route class, optional congestion destination, generated failure branch, selected recording or tone and original Dial result.

Trace caller-name lookup after the inbound route match

When an inbound route selects a lookup source, use the Caller ID Lookup Sources guide to preserve the received identity, selected source, cache decision, returned name and final display separately.

Trace external Misc Destinations as outbound calls

When an inbound route selects a Misc Destination containing an external number, preserve source authorization, exact digits, outbound route, caller-ID policy, trunk response and answer as separate evidence.

Document which inbound paths may assign elevated queue priority

A public DID or route can select a Queue Priorities object. Preserve eligibility and authorization rather than letting any caller inherit a privileged class.

Keep an inbound route handoff separate from a dynamic decision

An inbound route can hand a call to Dynamic Routes, but caller or DID selection is not the lookup result. The Dynamic Routes diagnostic follows the input, returned token, exact match and final destination separately.

Trace a Set CallerID destination as its own handoff

When a route or other call-flow object selects Set CallerID, prove the upstream selection, channel change and next destination separately. The module diagnostic continues into later outbound policy only after that handoff is correct.

Match the exact SIPStation DID after proving request receipt

Sangoma says the inbound-route DID must match the format supplied by the provider. Use the SIPStation diagnostic to preserve Request-URI, To identity, CID conditions, route priority and final destination.

Prove the route actually enters the time decision

Before changing hours, the Asterisk wrong-branch diagnostic confirms the inbound route reached the expected context and priority, then separates branch selection from final destination behavior.

ClearlyIP missing-DID automation uses a verification destination

The ClearlyIP diagnostic verifies that an auto-created inbound route was changed to the intended business destination.

Simwood Request-URI and To can carry different users

The Simwood diagnostic preserves Contact-derived addressing and the called number before route normalization.