Outbound Routes Module Documentation

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

---

1. Module Overview (Technical)

What Are Outbound Routes?

Outbound Routes define how external calls are routed from the PBX to SIP gateways. They match dialed numbers against patterns and select gateways based on priority, weight, and routing strategy.

Architecture

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                  Outbound Routes System                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  User dials: 918005551212                                       │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              route_with_fallback.lua                     │   │
│  │                                                          │   │
│  │  1. Check dialplan_registry (extensions, features)       │   │
│  │  2. No match → Check outbound_route_patterns             │   │
│  │  3. Match pattern: ^9\d{10}$ → "National Calls"          │   │
│  │  4. Strip 1 digit (9) → 18005551212                     │   │
│  │  5. Prepend: +1 → +118005551212                         │   │
│  │  6. Select gateway based on strategy                     │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        Gateway Selection (Failover Strategy)             │   │
│  │                                                          │   │
│  │  Priority 1: carrier_primary  ──→ Try first             │   │
│  │  Priority 2: carrier_backup   ──→ If primary fails      │   │
│  │  Priority 3: carrier_tertiary ──→ Last resort           │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼                                                         │
│  sofia/gateway/carrier_primary/+118005551212                    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

Table	Purpose
`public.outbound_routes`	Route definitions
`public.outbound_route_patterns`	Dial patterns
`public.outbound_route_gateways`	Gateway assignments
`public.gateways`	Available gateways
`public.pin_lists`	Optional PIN protection

Key Files

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

---

2. Module Overview (Commercial/Business)

Business Value

Outbound Routes enable intelligent external call routing:

Without Outbound Routes	With Outbound Routes
Single gateway	Multiple carrier support
No cost optimization	Least-cost routing
No redundancy	Automatic failover
No access control	PIN-protected routes

Use Cases

Least-Cost Routing

- Route by destination prefix

- Different carriers for local/long-distance/international

Carrier Failover

- Primary carrier unreachable → automatic switch

- No manual intervention

Access Control

- PIN-protect expensive routes

- Restrict international dialing

Number Manipulation

- Strip access codes (9)

- Prepend country codes (+1)

Feature Highlights

Feature	Benefit
Pattern Matching	Regex or simplified (9XXX)
Strip/Prepend	Number manipulation
3 Strategies	Failover, Round Robin, Load Balance
Priority-based	Route evaluation order
PIN Protection	Access control
Gateway Failover	Automatic redundancy

---

3. Module Overview (End User/Administrator)

What Can You Do?

Create outbound routes with names
Define dial patterns (prefix or regex)
Configure number manipulation (strip/prepend)
Assign multiple gateways with priorities
Choose routing strategy
Add PIN protection

Administrator Workflow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              Creating an Outbound Route                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Tab 1: General Settings                                        │
│  ├─ Route Name: "National Calls"                               │
│  ├─ Description: "US domestic calls via primary carrier"       │
│  ├─ Priority: 100                                              │
│  ├─ Routing Strategy: Failover                                 │
│  └─ Enabled: ✓                                                 │
│                                                                 │
│  Tab 2: Dial Patterns                                           │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ Pattern: 9NXXNXXXXXX | Strip: 1 | Prepend: +1 | ✓         │  │
│  │ Pattern: 91NXXNXXXXXX | Strip: 1 | Prepend: + | ✓         │  │
│  └───────────────────────────────────────────────────────────┘  │
│  [+ Add Pattern]                                                │
│                                                                 │
│  Tab 3: Gateways & Failover                                     │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ ≡ carrier_primary   | Priority: 1 | Weight: 100 | ✓       │  │
│  │ ≡ carrier_backup    | Priority: 2 | Weight: 100 | ✓       │  │
│  └───────────────────────────────────────────────────────────┘  │
│  [+ Add Gateway]                                                │
│                                                                 │
│  Tab 4: Advanced Options                                        │
│  ├─ PIN List: (optional)                                       │
│  ├─ Failover Module: Terminate                                 │
│  └─ Failover Destination: Hangup                               │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Tips

TIP

Use Simplified Patterns: 9XXX is easier than ^9\d{3}$.

TIP

Lower Priority = Higher Precedence: Route with priority 50 is checked before 100.

CAUTION

Strip Count: Make sure strip count doesn't remove too many digits.

---

4. Configuration Fields Reference

Route Fields

Field	Description	Example
Route Name	Unique identifier	`National Calls`
Description	Optional description	`US domestic calls`
Priority	Evaluation order (lower = first)	`100`
Routing Strategy	Gateway selection method	Failover
Enabled	Route active status	On/Off
Dial Profile	Optional Dial Profile template to execute dialplan variables before bridging	(select list)
PIN List	Optional PIN protection	(select list)
Failover Module	Action when all fail	Terminate
Failover Destination	Specific action	Hangup

Pattern Fields

Field	Description	Example
Pattern	Dial pattern to match	`9NXXNXXXXXX`
Strip Digits	Digits to remove from start	`1`
Prepend	Digits to add after strip	`+1`
Description	Pattern description	`Local calls`
Priority	Order within route	`1`
Enabled	Pattern active	On/Off

Gateway Fields

Field	Description
Gateway	Selected gateway
Priority	Order for failover (1=first)
Weight	Load balance weighting
Description	Optional note
Enabled	Gateway in use

---

5. Dial Patterns

Pattern Syntax

Simplified Patterns:

Symbol	Meaning	Example
`X`	Any digit (0-9)	`9XXX` = 9000-9999
`Z`	Digit 1-9	`9ZXXX` = 91000-99999
`N`	Digit 2-9	`9NXXX` = 92000-99999

Regex Patterns:

Pattern	Matches
`^9\d{10}$`	9 + 10 digits
`^011.`	International (011...)
`^1[2-9]\d{9}$`	1 + 10 digit US

Pattern Examples

Purpose	Pattern	Strip	Prepend	Result
Local (7-digit)	`9NXXXXXX`	1	`+1305`	Dial 95551234 → +13055551234
National (10-digit)	`9NXXNXXXXXX`	1	`+1`	Dial 93055551234 → +13055551234
Toll-Free	`91800NXXXXXX`	1	`+`	Dial 918005551234 → +18005551234
International	`9011.`	1	`+`	Dial 901152... → +52...

---

6. Routing Strategies

Strategy Comparison

Strategy	Description	Best For
Failover	Try gateways in priority order	Reliability
Round Robin	Rotate through gateways	Load distribution
Load Balance	Weighted distribution	Proportional traffic

Failover Strategy

Plaintext

Call comes in
    │
    ▼
Try Gateway 1 (Priority 1)
    │
    ├── Success → Call connected
    │
    └── Fail → Try Gateway 2 (Priority 2)
                    │
                    ├── Success → Call connected
                    │
                    └── Fail → Failover destination

Round Robin Strategy

Plaintext

Call 1 → Gateway A
Call 2 → Gateway B
Call 3 → Gateway C
Call 4 → Gateway A (restart)

Load Balance Strategy

Plaintext

Weights: Gateway A = 70, Gateway B = 30

~70% of calls → Gateway A
~30% of calls → Gateway B

---

7. Common Scenarios & Examples

Scenario 1: US National Calling

Route: "National Calls"

Setting	Value
Priority	100
Strategy	Failover

Patterns:

Pattern	Strip	Prepend	Description
`9NXXNXXXXXX`	1	`+1`	10-digit national
`91NXXNXXXXXX`	1	`+`	11-digit with 1

Gateways:

Gateway	Priority
primary_carrier	1
backup_carrier	2

Scenario 2: International with PIN

Route: "International"

Setting	Value
Priority	200
Strategy	Failover
PIN List	International PIN

Patterns:

Pattern	Strip	Prepend	Description
`9011.`	1	`+`	International

Scenario 3: Load-Balanced Multi-Carrier

Route: "Multi-Carrier"

Setting	Value
Priority	100
Strategy	Load Balance

Gateways:

Gateway	Weight
carrier_a	50
carrier_b	30
carrier_c	20

---

8. Limitations & Important Notes

Technical Notes

NOTE

Route Priority: Lower number = higher priority (checked first).

WARNING

Pattern Overlap: If patterns overlap, the first matching route wins.

WARNING

Strip Count: Stripping too many digits will break the dialed number.

Best Practices

Order Routes Carefully: Most specific patterns first
Test Patterns: Verify patterns match intended numbers
Set Failover: Always have a backup gateway
Use PIN for Expensive Routes: Protect international calling
Document Routes: Use descriptions for future reference

---

9. Troubleshooting Tips

Common Issues

Symptom	Possible Cause	Solution
Call not routing	Pattern doesn't match	Test pattern regex
Wrong carrier used	Route priority wrong	Adjust route priority
Number format wrong	Strip/prepend incorrect	Review manipulation
No failover	All gateways disabled	Enable backup gateway
PIN always required	PINless not enabled	Check extension settings

Diagnostic SQL

List outbound routes:

Sql

SELECT id, name, priority, routing_strategy, enabled
FROM public.outbound_routes
WHERE domain_id = [domain_id]
ORDER BY priority;

Check route patterns:

Sql

SELECT r.name as route, p.pattern, p.strip_digits, p.prepend, p.enabled
FROM public.outbound_route_patterns p
JOIN public.outbound_routes r ON p.route_id = r.id
WHERE r.domain_id = [domain_id]
ORDER BY r.priority, p.priority;

Check route gateways:

Sql

SELECT r.name as route, g.name as gateway, org.priority, org.weight
FROM public.outbound_route_gateways org
JOIN public.outbound_routes r ON org.route_id = r.id
JOIN public.gateways g ON org.gateway_id = g.id
WHERE r.domain_id = [domain_id]
ORDER BY r.name, org.priority;

FreeSWITCH Logs

Bash

# Enable debug logging
fs_cli -x "sofia loglevel all 9"

# Check outbound call routing
grep "route_with_fallback" /var/log/freeswitch/freeswitch.log

---

10. Glossary

Term	Definition
Outbound Route	Rule for routing external calls
Dial Pattern	Regex or simplified pattern to match
Strip Digits	Remove N digits from start of number
Prepend	Add digits before the number
Failover	Try next gateway on failure
Round Robin	Rotate through gateways
Load Balance	Distribute calls by weight
PIN List	Access control via numeric codes

---

Lua Script Status ✅

Already Correct

Script	Status
`route_with_fallback.lua`	✅ Uses `public.outbound_routes`, `public.outbound_route_patterns`, `public.outbound_route_gateways`, `public.gateways`, `public.pin_lists`, `public.sip_extensions`

No Lua fixes needed!

---

Documentation last updated: January 2026*

Outbound Routes Module Documentation

Table of Contents

1. Module Overview (Technical)

What Are Outbound Routes?

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

Route Fields

Pattern Fields

Gateway Fields

5. Dial Patterns

Pattern Syntax

Pattern Examples

6. Routing Strategies

Strategy Comparison

Failover Strategy

Round Robin Strategy

Load Balance Strategy

7. Common Scenarios & Examples

Scenario 1: US National Calling

Scenario 2: International with PIN

Scenario 3: Load-Balanced Multi-Carrier

8. Limitations & Important Notes

Technical Notes

Best Practices

9. Troubleshooting Tips

Common Issues

Diagnostic SQL

FreeSWITCH Logs

10. Glossary

Lua Script Status ✅

Already Correct