---
title: "Inbound Routes Module Documentation"
description: "Documentation for Inbound 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. [Destination Modules](#5-destination-modules)
8. [Pattern Matching](#6-pattern-matching)
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 Inbound Routes module:
1. Log in to the Ring2All Web Portal.
2. In the left navigation sidebar, expand **PBX Engine**.
3. Under **Call Routing**, click **Inbound Routes** (`/pbx/calls-routing/inbound`).

---

## Screenshots & Visual Interface

### Inbound Routes List View
Displays all inbound DID routing rules, pattern numbers, assigned destination module and target, priority, and enabled status.
![Inbound Routes List View](/screenshots/pbx/call-routing/inbound-routes-list.png)

### Inbound Route Configuration Form
Provides configuration for DID matching patterns, destination endpoints, dial profiles, and advanced settings (failover, recording, caller ID rewrite, screening).
![Inbound Route Configuration Form](/screenshots/pbx/call-routing/inbound-routes-form.png)

---

## 1. Module Overview (Technical)

### What Are Inbound Routes?

Inbound Routes define **how incoming calls are routed** from SIP gateways/carriers to internal destinations (extensions, queues, IVRs, etc.). They match DIDs (phone numbers) to destinations based on regex patterns.

### Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                  Inbound Routes System                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Incoming Call: +15055551234 from Carrier                       │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              route_with_fallback.lua                     │   │
│  │                                                          │   │
│  │  1. Detect call_direction = "inbound"                    │   │
│  │  2. Query public.inbound_routes                          │   │
│  │  3. Match: number_pattern = ^5055551234$                 │   │
│  │  4. Optional: caller_id_filter check                     │   │
│  │  5. Route to destination_module + destination_data       │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │           Destination Handler                            │   │
│  │                                                          │   │
│  │  extension → routing/extension.lua                       │   │
│  │  ivr       → routing/ivr.lua                            │   │
│  │  queue     → routing/queue.lua                          │   │
│  │  ring_group → routing/ring_group.lua                    │   │
│  │  conference → routing/conference.lua                    │   │
│  │  ...                                                     │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## 2. Module Overview (Commercial/Business)

### Business Value

Inbound Routes enable **DID-to-destination mapping**:

| Without Inbound Routes | With Inbound Routes |
|------------------------|---------------------|
| All calls to default | Route by DID number |
| No caller filtering | Filter by caller ID |
| No time routing | Time-based destinations |
| No call screening | Anonymous call blocking |

### Use Cases

1. **DID Routing**
   - Route +15051234567 → Sales Queue
   - Route +15057654321 → Support IVR

2. **Department Lines**
   - Main number → Auto-Attendant
   - Support number → Support Queue
   - Fax number → Fax Server

3. **Geographic Routing**
   - Local calls → Local agents
   - International → Language IVR

4. **Time-Based Routing**
   - Business hours → Main IVR
   - After hours → Voicemail

### Feature Highlights

| Feature | Benefit |
|---------|---------|
| **Pattern Matching** | Regex for DIDs |
| **Caller ID Filter** | Route by caller |
| **Time Conditions** | Time-based routing |
| **Multiple Destinations** | Extension, Queue, IVR, etc. |
| **Call Recording** | Auto-record inbound calls |
| **Anonymous Blocking** | Reject hidden or anonymous callers |
| **Caller ID Rewriting** | Customize presented caller ID name and number |
| **Gateway Restriction** | Restrict routes to allowed trunk gateways |
| **Max Concurrent** | Capacity limits with failover rerouting |

---

## 3. Module Overview (End User/Administrator)

### What Can You Do?

- Create inbound routes for DIDs
- Define number patterns (regex)
- Filter by caller ID
- Set destination (extension, queue, IVR, etc.)
- Configure time conditions
- Block anonymous callers
- Set concurrent call limits

### Administrator Workflow

```
┌─────────────────────────────────────────────────────────────────┐
│              Creating an Inbound Route                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Section: General                                               │
│  ├─ Name: "Main Line"                                          │
│  ├─ Number Pattern: ^5055551234$                               │
│  ├─ Caller ID Filter: (optional)                               │
│  ├─ Priority: 100                                              │
│  └─ Enabled: ✓                                                 │
│                                                                 │
│  Section: Settings                                              │
│  ├─ Destination Module: IVR                                    │
│  ├─ Destination: Main Auto-Attendant                           │
│  ├─ Time Condition: Business Hours (optional)                  │
│  ├─ Failover Module: Voicemail                                 │
│  ├─ Failover Destination: General Mailbox                      │
│  ├─ Record Call: ✓                                             │
│  ├─ Block Anonymous: ✓                                         │
│  └─ Max Concurrent: 20                                         │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Quick Tips

> [!TIP]
> **Use Anchors**: `^5055551234$` matches exactly that number.

> [!TIP]
> **Wildcard DIDs**: `^505555.*` matches all 505555xxxx numbers.

> [!CAUTION]
> **Priority Order**: Lower number = higher priority (checked first).

---

## 4. Configuration Fields Reference

### General Fields

| Field | Description | Example |
|-------|-------------|---------|
| **Name** | Route identifier | `Main Line` |
| **Number Pattern** | Regex for DID | `^5055551234$` |
| **Caller ID Filter** | Optional caller pattern | `^1800.*` |
| **Priority** | Evaluation order (lower = first) | `100` |
| **Enabled** | Route active | On/Off |

### Destination Fields

| Field | Description |
|-------|-------------|
| **Destination Module** | Target type (extension, ivr, queue, etc.) |
| **Destination** | Specific destination |
| **Time Condition** | Optional time-based routing |
| **Dial Profile** | Optional Dial Profile template to control call variables (transfers, ringbacks) for incoming calls |
| **Failover Module** | Backup destination type |
| **Failover Destination** | Backup target |

### Advanced Fields

| Field | Description | Default |
|-------|-------------|---------|
| **Record Call** | Auto-record incoming calls with domain quota checks | Off |
| **Announcement** | Audio recording played before transfer to destination | None |
| **Strip Digits** | Number of leading digits to strip from destination number | 0 |
| **Add Prefix** | Digits or prefix prepended to destination number | None |
| **Rewrite Caller ID Name** | Overrides SIP `effective_caller_id_name` presented to destination | None |
| **Rewrite Caller ID Number** | Overrides SIP `effective_caller_id_number` presented to destination | None |
| **Block Anonymous** | Reject calls with anonymous/private caller ID (SIP 433) | Off |
| **Allowed Gateways** | Restrict route to specific SIP gateways | All (Unrestricted) |
| **Max Concurrent** | Maximum simultaneous calls (exceeded calls redirect to failover) | Unlimited |
| **Log Calls** | Log all calls routed through this rule | On |

---

## 5. Destination Modules

### Available Destinations

| Module | Description | Handler |
|--------|-------------|---------|
| **Extension** | Route to extension | `routing/extension.lua` |
| **IVR** | Route to IVR menu | `routing/ivr.lua` |
| **Queue** | Route to call center queue | `routing/queue.lua` |
| **Ring Group** | Route to ring group | `routing/ring_group.lua` |
| **Conference** | Route to conference room | `routing/conference.lua` |
| **Announcement** | Play announcement | `routing/announcement.lua` |
| **Call Flow** | Route to call flow | `routing/call_flow.lua` |
| **Time Condition** | Time-based routing | `routing/time_condition.lua` |
| **Direct Route** | Direct external route | `routing/direct_route.lua` |
| **Direct Dial** | Speed dial destination | `routing/direct_dial.lua` |
| **Language** | Language selection | `routing/language.lua` |
| **Fax** | Fax server | `routing/fax.lua` |
| **Emergency** | Emergency routing | `routing/emergency.lua` |

### Destination Selection Flow

```
Destination Module: Queue
       │
       ▼
Destination Dropdown loads:
├─ Sales Queue
├─ Support Queue
├─ Billing Queue
└─ ...
       │
       ▼
Select: "Support Queue"
```

---

## 6. Pattern Matching

### Number Pattern Syntax

| Pattern | Matches | Example DID |
|---------|---------|-------------|
| `^5055551234$` | Exact number | 5055551234 |
| `^505555.*` | 505555 + any digits | 5055551234, 5055559999 |
| `^1800\d{7}$` | 1800 + 7 digits | 18001234567 |
| `.*` | Any number | All DIDs |

### Caller ID Filter

| Pattern | Filters |
|---------|---------|
| `^1800.*` | Toll-free callers |
| `^505.*` | Local callers |
| `^011.*` | International callers |
| `^(PRIVATE|ANONYMOUS)$` | Anonymous callers |

### Pattern Examples

| Purpose | Number Pattern | Caller Filter |
|---------|---------------|---------------|
| Specific DID | `^5055551234$` | - |
| Range of DIDs | `^505555\d{4}$` | - |
| VIP Callers | `^5055551234$` | `^18001234567$` |
| Block Toll-Free | `^5055551234$` | `^(?!1800).*` |

---

## 7. Common Scenarios & Examples

### Scenario 1: Main Business Line

**Route: "Main Line"**
| Setting | Value |
|---------|-------|
| Number Pattern | `^5055551234$` |
| Destination Module | IVR |
| Destination | Main Auto-Attendant |
| Priority | 100 |
| Record Call | ✓ |
| Block Anonymous | ✓ |

### Scenario 2: Support Queue with Time Routing

**Route: "Support Line"**
| Setting | Value |
|---------|-------|
| Number Pattern | `^5055559999$` |
| Time Condition | Business Hours |
| Destination Module | Queue |
| Destination | Support Queue |
| Failover Module | Voicemail |
| Failover Destination | Support Mailbox |

### Scenario 3: VIP Caller Direct to Extension

**Route: "VIP Direct Line"**
| Setting | Value |
|---------|-------|
| Number Pattern | `^5055551234$` |
| Caller ID Filter | `^15055559999$` |
| Priority | 50 (higher than main) |
| Destination Module | Extension |
| Destination | 1001 (CEO) |

### Scenario 4: Fax Line

**Route: "Fax Line"**
| Setting | Value |
|---------|-------|
| Number Pattern | `^5055550000$` |
| Destination Module | Fax |
| Destination | Fax Server |

---

## 8. Model Context Protocol (MCP) AI Integration

Ring2All exposes native Model Context Protocol (MCP) tools for **Inbound Routes (DID Routing)**, enabling autonomous AI agents, Copilots, and telecom automation engines to inspect incoming phone number mappings, link DIDs to call handling destinations (IVRs, Ring Groups, Queues, Extensions, Voicemail), enforce strict DID numbering collision prevention within the domain, and maintain synchronized Telephony dialplans (`reloadxml`).

### Available MCP Tools

| Tool Name | Description | Key Parameters |
|:---|:---|:---|
| `list_inbound_routes` | Lists all inbound routes configured in the domain, displaying DID number patterns, destination modules, target data, priority, and enabled status. | `search` (optional string) |
| `get_inbound_route_status` | Retrieves complete configuration of an inbound route by name or DID number pattern, including caller ID filters, priority, and destination target. | `identifier` (required string - route name or DID) |
| `create_inbound_route` | Provisions a new inbound DID routing rule. Validates pattern syntax and **strictly prevents DID numbering collisions** against existing routes in the same domain. | `name`, `numberPattern`, `destinationModule` (`ivr`, `ring-group`, `queue`, `extension`, `voicemail`, `time-condition`, `hangup`), `destinationData`, `priority`, `callerIdFilter` |
| `update_inbound_route` | Updates an existing inbound route's destination target, priority, caller ID filter, or DID pattern with atomic collision verification. | `identifier`, `newName`, `numberPattern`, `destinationModule`, `destinationData`, `priority`, `enabled` |
| `diagnose_inbound_route` | Performs deep operational diagnostic on an Inbound DID Route: validates pattern/regex syntax, checks enabled status and priority ordering, verifies destination target existence and health (detecting orphaned routes), and scans Telephony engine logs for recent incoming SIP INVITE matching issues. | `identifier` (required string - route name or incoming DID) |
| `delete_inbound_route` | Removes an inbound DID route and immediately syncs Telephony Server XML cache. | `identifier` (required string) |

### Anti-Collision & Numbering Integrity Protection
- **DID Collision Prevention**: It is strictly forbidden for two inbound routes to claim the identical incoming DID pattern and caller ID filter within the same tenant domain. Both `create_inbound_route` and `update_inbound_route` perform atomic pre-flight checks:
  ```sql
  SELECT id FROM public.inbound_routes
  WHERE domain_id = [domain_id]
    AND number_pattern = [numberPattern]
    AND coalesce(caller_id_filter, '') = coalesce([callerIdFilter], '');
  ```
  If a duplicate is detected, the operation is immediately rejected with a descriptive conflict error.
- **Dialplan Hot Reload**: Creation, modification, or removal of inbound routes automatically invokes Telephony Server `reloadxml`, ensuring carrier traffic routes without manual daemon restarts.

### AI Agent Operational Examples

#### Querying Inbound Routes Matching a Specific DID
```json
{
  "tool": "get_inbound_route_status",
  "arguments": {
    "identifier": "+18005550199"
  }
}
```

#### Provisioning an Inbound DID to an IVR Menu
```json
{
  "tool": "create_inbound_route",
  "arguments": {
    "name": "Main Office Toll-Free",
    "numberPattern": "^(\\+?18005550199)$",
    "destinationModule": "ivr",
    "destinationData": "7001",
    "priority": 10
  }
}
```

#### Re-routing an Inbound Route to a Call Center Queue
```json
{
  "tool": "update_inbound_route",
  "arguments": {
    "identifier": "Main Office Toll-Free",
    "destinationModule": "queue",
    "destinationData": "800",
    "priority": 5
  }
}
```

#### Diagnosing Inbound Route & Destination Integrity
```json
{
  "tool": "diagnose_inbound_route",
  "arguments": {
    "identifier": "+18005550199"
  }
}
```

### Recommended Natural Language Prompts
- *"Show me all inbound DIDs and where they are currently routing."*
- *"Route incoming calls for DID +15055551234 to Ring Group 600."*
- *"Check if DID +18005550199 is already configured or if there is a number collision."*
- *"Update the after-hours inbound route to send callers directly to Voicemail 1001."*

---

## 9. Limitations & Important Notes

### Technical Notes

> [!NOTE]
> **Priority Order**: Inbound routes are checked by priority (lowest first). First match wins.

> [!WARNING]
> **Pattern Overlap**: If patterns overlap, use priority to control which route wins.

> [!WARNING]
> **Regex Escaping**: Use `\.` for literal dots, `\d` for digits.

### Best Practices

1. **Use Exact Patterns**: `^5055551234$` is safer than `505555.*`
2. **Set Priorities**: Lower priority for specific routes (50), higher for catch-all (999)
3. **Test Patterns**: Verify patterns match intended DIDs
4. **Configure Failover**: Always have a backup destination
5. **Use Time Conditions**: Route differently for business/after hours

---

## 10. Troubleshooting Tips

### Common Issues

| Symptom | Possible Cause | Solution |
|---------|---------------|----------|
| Wrong destination | Pattern overlap | Adjust priorities |
| No route found | Pattern doesn't match | Test regex pattern |
| Call rejected | Anonymous blocking | Disable or adjust |
| Failover not working | Failover not configured | Set failover module |
| Time routing wrong | Time condition incorrect | Check time condition |

### Diagnostic SQL

**List inbound routes:**
```sql
SELECT id, name, number_pattern, destination_module, destination_data, priority, enabled
FROM public.inbound_routes
WHERE domain_id = [domain_id]
ORDER BY priority;
```

**Test pattern matching:**
```sql
SELECT name, number_pattern, destination_module, destination_data
FROM public.inbound_routes
WHERE domain_id = [domain_id]
  AND enabled = TRUE
  AND '5055551234' ~ number_pattern
ORDER BY priority
LIMIT 1;
```

### Telephony Server Logs

```bash
# Check inbound routing
grep "inbound_routes" /var/log/freeswitch/freeswitch.log
grep "route_with_fallback" /var/log/freeswitch/freeswitch.log
```

---

## 11. Glossary

| Term | Definition |
|------|------------|
| **Inbound Route** | Rule for routing incoming calls |
| **DID** | Direct Inward Dialing number |
| **Number Pattern** | Regex to match dialed number |
| **Caller ID Filter** | Regex to match caller number |
| **Destination Module** | Type of destination (extension, ivr, etc.) |
| **Time Condition** | Time-based routing rule |
| **Failover** | Backup destination if primary fails |

---

*Documentation last updated: January 2026*