Inbound Routes Module Documentation

Module Overview (Technical)
Module Overview (Commercial/Business)
Module Overview (End User/Administrator)
Configuration Fields Reference
Destination Modules
Pattern Matching
Common Scenarios & Examples
Limitations & Important Notes
Troubleshooting Tips
Glossary

---

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

Plaintext

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

Key Tables

Table	Purpose
`public.inbound_routes`	Route definitions
`public.domains`	Domain lookup
`public.time_conditions`	Optional time-based routing

Key Files

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

---

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

DID Routing

- Route +15051234567 → Sales Queue

- Route +15057654321 → Support IVR

Department Lines

- Main number → Auto-Attendant

- Support number → Support Queue

- Fax number → Fax Server

Geographic Routing

- Local calls → Local agents

- International → Language IVR

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
Anonymous Blocking	Reject hidden callers
Country Filter	Geographic restrictions
Max Concurrent	Capacity limits

---

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

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              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	Off
Announcement	Play before routing	None
Strip Digits	Remove N digits	0
Add Prefix	Prepend digits	None
Block Anonymous	Reject hidden callers	Off
Country Filter	Geographic restrictions	None
Allowed Gateways	Gateway restrictions	All
Max Concurrent	Call limit	Unlimited
Limit Action	When limit reached	Busy
External API	Webhook before routing	None

---

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

Plaintext

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

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

---

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

FreeSWITCH Logs

Bash

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

---

10. 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

---

Lua Script Status ✅

Already Correct

Script	Status
`route_with_fallback.lua`	✅ Uses `public.inbound_routes` with correct schema

Relevant code section (lines 281-296):

Lua

dbh:query(string.format([[
  SELECT 
    destination_module,
    destination_data
  FROM public.inbound_routes
  WHERE domain_id = %s
    AND enabled = TRUE
    AND '%s' ~ number_pattern
    AND (caller_id_filter IS NULL OR '%s' ~ caller_id_filter)
  ORDER BY priority ASC
  LIMIT 1
]], domain_id, escape_sql(destination), escape_sql(caller_id_number)), function(row)
  ...
end)

No Lua fixes needed!

---

Documentation last updated: January 2026

Inbound Routes Module Documentation

Table of Contents

1. Module Overview (Technical)

What Are Inbound 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

General Fields

Destination Fields

Advanced Fields

5. Destination Modules

Available Destinations

Destination Selection Flow

6. Pattern Matching

Number Pattern Syntax

Caller ID Filter

Pattern Examples

7. Common Scenarios & Examples

Scenario 1: Main Business Line

Scenario 2: Support Queue with Time Routing

Scenario 3: VIP Caller Direct to Extension

Scenario 4: Fax Line

8. Limitations & Important Notes

Technical Notes

Best Practices

9. Troubleshooting Tips

Common Issues

Diagnostic SQL

FreeSWITCH Logs

10. Glossary

Lua Script Status ✅

Already Correct