---
title: "Outbound Routes Module Documentation"
description: "Documentation for Outbound Routes"
---

## Table of Contents
1. [Navigation & Access](#navigation--access)
2. [Screenshots & Visual Interface](#screenshots--visual-interface)
3. [Module Overview (Technical)](#1-module-overview-technical)
4. [Module Overview (Commercial/Business)](#2-module-overview-commercialbusiness)
5. [Module Overview (End User/Administrator)](#3-module-overview-end-useradministrator)
6. [Configuration Fields Reference](#4-configuration-fields-reference)
7. [Dial Patterns](#5-dial-patterns)
8. [Routing Strategies](#6-routing-strategies)
9. [Common Scenarios & Examples](#7-common-scenarios--examples)
10. [Model Context Protocol (MCP) AI Integration](#8-model-context-protocol-mcp-ai-integration)
11. [Limitations & Important Notes](#9-limitations--important-notes)
12. [Troubleshooting Tips](#10-troubleshooting-tips)
13. [Glossary](#11-glossary)
---

## Navigation & Access

To access the Outbound Routes module:
1. Log in to the Ring2All Web Portal.
2. In the left navigation sidebar, expand **PBX Engine**.
3. Under **Call Routing**, click **Outbound Routes** (`/pbx/calls-routing/outbound`).

---

## Screenshots & Visual Interface

### Outbound Routes List View
Displays all configured outbound routes with their priority, routing strategy, assigned gateways, pattern count, and status.
![Outbound Routes List View](/screenshots/pbx/call-routing/outbound-routes-list.png)

### Outbound Route Configuration Form
Provides configuration for general settings, drag-and-drop dial patterns (with strip/prepend rules), and ordered gateway failover cascades.
![Outbound Route Configuration Form](/screenshots/pbx/call-routing/outbound-routes-form.png)

---

## 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

```
┌─────────────────────────────────────────────────────────────────┐
│                  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                    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## 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

1. **Least-Cost Routing**
   - Route by destination prefix
   - Different carriers for local/long-distance/international

2. **Carrier Failover**
   - Primary carrier unreachable → automatic switch
   - No manual intervention

3. **Access Control**
   - PIN-protect expensive routes
   - Restrict international dialing

4. **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

```
┌─────────────────────────────────────────────────────────────────┐
│              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

```
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

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

### Load Balance Strategy

```
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. Model Context Protocol (MCP) AI Integration

Ring2All exposes native Model Context Protocol (MCP) tools for **Outbound Routes**, allowing AI agents and PBX automation engines to inspect egress dial patterns, examine multi-gateway failover cascades, adjust routing strategies (`failover`, `round-robin`, `load-balance`, `lcr`), and provision or remove outbound dialing rules programmatically with strict domain isolation and automatic Telephony dialplan synchronization (`reloadxml`).

### Available MCP Tools

| Tool Name | Description | Key Parameters |
|:---|:---|:---|
| `list_outbound_routes` | Lists all outbound routes in the domain, including match patterns, assigned gateway trunks, routing strategy, priority, and enabled state. | `search` (optional string) |
| `get_outbound_route_status` | Retrieves full configuration of a specific outbound route, detailing ordered regex patterns, digit manipulation (strip/prepend), and prioritized gateway failover lists. | `name` (required string) |
| `create_outbound_route` | Provisions a new outbound route matching dial patterns to ordered carrier gateways with a specified strategy and priority. Strictly enforces route name uniqueness within the domain. | `name`, `patterns` (array of regex/prefix strings), `gatewayNames` (ordered array of gateways), `routingStrategy` (`failover`, `round-robin`, `load-balance`, `lcr`), `priority`, `description` |
| `update_outbound_route` | Updates outbound route parameters, including routing strategy, priority, enabled status, or name. | `name`, `newName`, `routingStrategy`, `priority`, `enabled` |
| `diagnose_outbound_route` | Performs deep operational diagnostic on an Outbound Route: tests dial patterns against an optional test dialed number, validates route priority and enabled status, checks live Sofia trunk gateway registration and ping reachability, evaluates trunk failover cascades, and scans Telephony engine logs for recent egress call errors (SIP 503, 486, 404). | `name` (required string), `testNumber` (optional string) |
| `simulate_dialplan_route` | Dry-run end-to-end call routing emulator reproducing the exact FreeSWITCH Lua dialplan engine. Tests extension DND, call forwardings, Ring Groups, Queues, IVR, Voicemail, Blacklists, Class of Service dial rule restrictions, Outbound Route priority/patterns, prepend/strip digit transformation, Gateway Sofia readiness, and effective CID resolution. | `dialedNumber` (required string), `callerExt` (optional string) |
| `delete_outbound_route` | Safely removes an outbound route and its associated pattern and gateway junction rows, automatically triggering dialplan XML reload. | `name` (required string) |

### Protection Guards & Integrity
- **Name Uniqueness**: Route names must be strictly unique within each tenant domain. Attempts to create or rename a route to an existing name trigger a validation rejection.
- **Gateway Existence Validation**: When creating an outbound route via MCP, every gateway named in `gatewayNames` is verified against active domain gateways before provisioning the junction table (`outbound_route_gateways`).
- **Atomic Telephony Server Synchronization**: Successful creation, modification, or deletion invokes Telephony Server XML cache invalidation (`reloadxml`) so outbound routing takes effect instantly without orphaned dialplans.

### AI Agent Operational Examples

#### Auditing Outbound Routes & Gateways
```json
{
  "tool": "list_outbound_routes",
  "arguments": {
    "search": "International"
  }
}
```

#### Provisioning an Emergency 911 Outbound Route
```json
{
  "tool": "create_outbound_route",
  "arguments": {
    "name": "Emergency_E911",
    "patterns": ["^911$", "^933$"],
    "gatewayNames": ["Telnyx_Primary", "Twilio_Backup"],
    "routingStrategy": "failover",
    "priority": 0,
    "description": "Highest priority emergency egress route"
  }
}
```

#### Updating Strategy to Least Cost Routing (LCR)
```json
{
  "tool": "update_outbound_route",
  "arguments": {
    "name": "Domestic_Standard",
    "routingStrategy": "lcr",
    "priority": 10
  }
}
```

#### Diagnosing Outbound Routing & Gateway Readiness
```json
{
  "tool": "diagnose_outbound_route",
  "arguments": {
    "name": "Domestic_Standard",
    "testNumber": "13055551234"
  }
}
```

#### Simulating End-to-End Dialplan Routing (`simulate_dialplan_route`)
```json
{
  "tool": "simulate_dialplan_route",
  "arguments": {
    "callerExt": "2002",
    "dialedNumber": "13055551234"
  }
}
```

### Recommended Natural Language Prompts
- *"List all outbound routes and the carrier gateways assigned to each."*
- *"Simulate an outbound call from extension 2002 to 13055551234 to verify which route and gateway will be selected."*
- *"Create an outbound route for North American 10-digit dialing through Telnyx with Twilio as failover."*
- *"Check the dial pattern configuration for the International route."*
- *"Disable the legacy carrier outbound route without deleting it."*

---

## 9. 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

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

---

## 10. 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;
```

### Telephony Server 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
```

---

## 11. 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 |

---

*Documentation last updated: January 2026*