Direct Route Module Documentation

Module Overview (Technical)
Module Overview (Commercial/Business)
Module Overview (End User/Administrator)
Configuration Fields Reference
Call Flow / Logic Explanation
Common Scenarios & Examples
Limitations & Important Notes
Troubleshooting Tips
Glossary
Suggested UI Improvements

---

1. Module Overview (Technical)

What Is Direct Route?

Direct Route is a Class of Service bypass mechanism that allows specific phone numbers to be dialed by users who would otherwise be restricted. It provides exception-based routing with optional caller ID override.

The Problem It Solves

Plaintext

Normal Flow:
User (CoS: Local Only) → Dial +44-123-456-7890 → ❌ BLOCKED (International)

With Direct Route:
User (CoS: Local Only) → Dial +44-123-456-7890 → ✅ ALLOWED (Direct Route exists)

Architecture

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                    Direct Route System                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  User dials: +44-123-456-7890                                   │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              Direct Route Lookup                         │   │
│  │  SELECT * FROM direct_routes                             │   │
│  │  WHERE number_to_dial = '+44-123-456-7890'               │   │
│  │    AND class_of_services_id = [user_cos_id]              │   │
│  │    AND enabled = true                                    │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ├─ Found → Bypass CoS check, apply caller ID override     │
│       └─ Not Found → Normal dialrule processing (may block)     │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              Route Call                                  │   │
│  │  ├─ Apply caller ID override (if configured)             │   │
│  │  └─ Bridge call to destination via trunk                 │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

Table	Purpose
`public.direct_routes`	Route definitions (number, CoS, caller ID override)
`public.class_of_services`	Referenced for CoS assignment

Key Files

File	Description
`admin/apps/api/src/modules/telephony/direct-route/services/`	Backend service
`admin/apps/web/src/modules/directRoute/`	Frontend module
`admin/apps/web/src/i18n/en/directRoute.json`	English translations

---

2. Module Overview (Commercial/Business)

Business Value

Direct Route provides granular exception control without modifying Class of Service:

Without Direct Route	With Direct Route
Create separate CoS for exception users	Keep standard CoS, add exceptions
All-or-nothing permission models	Specific number-level control
Security risk with broad permissions	Minimal permission expansion

Use Cases

Partner/Vendor Access

- International call restriction is on

- Need to call specific overseas vendor

- Create Direct Route for that specific number

Emergency Contacts

- Allow specific numbers regardless of CoS

- Corporate emergency line, CEO mobile, etc.

Customer Service Numbers

- Toll-free customer support numbers

- Specific client hotlines

Caller ID Override

- Appear as different number when calling specific destinations

- Compliance or privacy requirements

Feature Highlights

CoS-Based Control: Each route is tied to a Class of Service
Caller ID Override: Override outbound caller ID per destination
Enable/Disable: Quickly toggle without deletion
Specific Number: Exact match on destination number

---

3. Module Overview (End User/Administrator)

What Can You Do?

Create routes that bypass CoS restrictions for specific numbers
Override caller ID when calling specific destinations
Tie routes to specific Class of Service groups
Enable/disable routes without deletion

User Workflow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                 Creating a Direct Route                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Scenario: Sales team (Local-Only CoS) needs to call           │
│            UK vendor at +44-20-7946-0958                        │
│                                                                 │
│  1. Basic Information                                           │
│     ├─ Name: "UK Vendor - ABC Corp"                            │
│     └─ Description: "Exception for Sales team"                 │
│                                                                 │
│  2. Routing Configuration                                       │
│     ├─ Number To Dial: +44-20-7946-0958                        │
│     └─ Class of Service: "Local Only" (Sales team's CoS)       │
│                                                                 │
│  3. Caller ID Override (Optional)                               │
│     ├─ Caller ID Name: "ABC Sales"                             │
│     └─ Caller ID Number: +1-555-123-4567                       │
│                                                                 │
│  4. Enable: ✓                                                   │
│                                                                 │
│  5. Save → Sales can now dial +44-20-7946-0958                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Tips

TIP

Use Full Number Format: Include country code for international numbers (e.g., +44-20-7946-0958).

TIP

Document Purpose: Use description field to explain WHY the exception exists.

CAUTION

CoS Must Match: The route only works for users with the specified Class of Service.

---

4. Configuration Fields Reference

Basic Information

Field	Description	Example	Required
Name	Descriptive name for the route	`UK Vendor - ABC Corp`	Yes
Description	Purpose documentation	`Exception for sales to call UK vendor`	No

Routing Configuration

Field	Description	Example	Required
Number To Dial	Exact destination number	`+44-20-7946-0958`	Yes
Class of Service	CoS that gets this exception	`Local Only`, `National Only`	Yes

Caller ID Override

Field	Description	Example	Required
Caller ID Name	Override outbound CNAM	`ABC Sales Department`	No
Caller ID Number	Override outbound CNUM	`+1-555-123-4567`	No

Status

Field	Description	Default
Enabled	Whether the route is active	Yes

---

5. Call Flow / Logic Explanation

Direct Route Checking Flow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                  Direct Route Check Flow                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. User (CoS: Local Only) dials +44-20-7946-0958               │
│     │                                                           │
│     ▼                                                           │
│  2. Dialplan checks direct_routes table:                        │
│     SELECT * FROM direct_routes                                 │
│     WHERE number_to_dial = '+44-20-7946-0958'                   │
│       AND class_of_services_id = [user_cos_id]                  │
│       AND enabled = true                                        │
│     │                                                           │
│     ├─ FOUND → Step 3a                                         │
│     └─ NOT FOUND → Step 3b                                      │
│     │                                                           │
│     ▼ (3a - Route exists)                                       │
│  3a. Bypass Class of Service check                              │
│     ├─ Apply caller ID override (if configured)                 │
│     │   session.setVariable("effective_caller_id_name", "...")  │
│     │   session.setVariable("effective_caller_id_number", "...") │
│     └─ Route call to trunk                                      │
│     │                                                           │
│     ▼                                                           │
│  Call proceeds to +44-20-7946-0958                              │
│                                                                 │
│     ▼ (3b - Route not found)                                    │
│  3b. Normal dialrule processing                                 │
│     ├─ Check CoS allows international → NO                      │
│     └─ "The number you dialed is not allowed" → hangup          │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

---

6. Common Scenarios & Examples

Scenario 1: International Vendor Exception

Problem: Sales team has "Local Only" CoS but needs to call UK vendor.

Field	Value
Name	UK Vendor - ABC Corp
Number To Dial	+44-20-7946-0958
Class of Service	Local Only
Caller ID Override	(none)
Enabled	✓

Result: Only users with "Local Only" CoS can dial this specific UK number.

Scenario 2: Corporate Emergency Line

Problem: Everyone should be able to reach corporate security regardless of CoS.

Field	Value
Name	Corporate Emergency
Number To Dial	+1-800-555-HELP
Class of Service	Internal Only
Caller ID Override	(none)
Enabled	✓

Repeat for each CoS that needs this exception.

Scenario 3: Caller ID Privacy

Problem: When calling a specific client, show company main line instead of extension.

Field	Value
Name	Client XYZ - Privacy Override
Number To Dial	+1-555-987-6543
Class of Service	Standard
Caller ID Name	ABC Company
Caller ID Number	+1-800-555-0100
Enabled	✓

Result: When calling +1-555-987-6543, recipient sees "ABC Company" / +1-800-555-0100.

Scenario 4: Multiple CoS Same Number

Problem: Both "Sales" and "Support" CoS need to call the same number. Solution: Create TWO Direct Routes:

Route 1	Route 2
Name: Vendor - Sales	Name: Vendor - Support
Number: +44-20-7946-0958	Number: +44-20-7946-0958
CoS: Sales	CoS: Support

---

7. Limitations & Important Notes

Technical Limitations

WARNING

Exact Match Only: The number must match exactly. Wildcards are not supported.

WARNING

CoS Specific: Each route is tied to ONE Class of Service. Create multiple routes for multiple CoS groups.

IMPORTANT

No Trunk Selection: Direct Route bypasses CoS check but still uses default trunk selection logic.

Best Practices

Document Everything: Always explain why the exception exists in the description
Review Regularly: Audit direct routes quarterly—remove obsolete ones
Limit Usage: Direct routes are exceptions, not primary routing
Use Full Numbers: Include country codes to avoid ambiguity

Security Considerations

CAUTION

Audit Trail: Document who requested each exception and why. Direct routes bypass security controls.

CAUTION

Caller ID Fraud: Caller ID override can be misused. Restrict who can create routes.

---

8. Troubleshooting Tips

Common Issues

Symptom	Possible Cause	Solution
Call still blocked	CoS mismatch	Verify user's CoS matches route's CoS
Call blocked	Number format mismatch	Check exact number format (with/without +)
Caller ID not changing	Trunk overrides	Check trunk doesn't force caller ID
Route not found	Disabled	Verify route is enabled

Diagnostic SQL

List all direct routes:

Sql

SELECT dr.name, dr.number_to_dial, cs.name as cos_name, dr.enabled
FROM public.direct_routes dr
JOIN public.class_of_services cs ON dr.class_of_services_id = cs.id
WHERE dr.domain_id = [domain_id]
ORDER BY dr.name;

Check if route exists for a number:

Sql

SELECT dr.name, cs.name as cos_name, dr.enabled
FROM public.direct_routes dr
JOIN public.class_of_services cs ON dr.class_of_services_id = cs.id
WHERE dr.number_to_dial = '+44-20-7946-0958'
  AND dr.domain_id = [domain_id];

Find disabled routes:

Sql

SELECT name, number_to_dial 
FROM public.direct_routes 
WHERE enabled = false AND domain_id = [domain_id];

---

9. Glossary

Term	Definition
Direct Route	A bypass rule that allows specific numbers regardless of CoS restrictions
Class of Service (CoS)	Permission level defining what types of calls a user can make
Dialrule	Pattern matching rules that determine call routing
Caller ID Override	Changing the outbound caller ID for a specific destination
CNAM	Caller Name - the name portion of caller ID
CNUM	Caller Number - the number portion of caller ID
Exception	A special case that bypasses normal rules
Trunk	Connection to external telephone network (PSTN, SIP provider)

---

10. Suggested UI Improvements

Enhanced Tooltips

Field	Current	Suggested
numberToDial	"Enter the phone number to dial"	"Exact destination number to allow. Include country code for international (e.g., +44-20-7946-0958). Must match exactly—no wildcards."
classOfServices	"Select the class of service that allows this route"	"Only users with this Class of Service will be able to dial this number. Create multiple routes for multiple CoS groups."
callerIdNumber	"Override caller ID number"	"Outbound caller ID shown to the recipient. Leave blank to use user's default. Carrier may override this."

UX Enhancements

CoS Multi-Select: Allow selecting multiple CoS for one route instead of creating duplicates

Wildcard Support: Allow patterns like +44- for all UK numbers

Current	Suggested
Plain list	Show CoS badge with color
Text only	Flag icon for international numbers
Simple toggle	Expiration indicator if date set

Component	Status	Notes
Direct Route	ℹ️ Configuration module	Routing handled by dialplan XML structure

Expiration Date: Option to auto-disable route after a certain date

Usage Stats: Show how many calls have used this route

Bulk Import: CSV import for creating multiple routes

Clone Button: Easily duplicate a route for a different CoS

Visual Improvements

Current Suggested
Plain list Show CoS badge with color
Text only Flag icon for international numbers
Simple toggle Expiration indicator if date set
---

Lua Script Status ℹ️

Integration Module

Component Status Notes
Direct Route ℹ️ Configuration module Routing handled by dialplan XML structure
---

Documentation last updated: January 2026*

Direct Route Module Documentation

Table of Contents

1. Module Overview (Technical)

What Is Direct Route?

The Problem It Solves

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?

User Workflow

Quick Tips

4. Configuration Fields Reference

Basic Information

Routing Configuration

Caller ID Override

Status

5. Call Flow / Logic Explanation

Direct Route Checking Flow

6. Common Scenarios & Examples

Scenario 1: International Vendor Exception

Scenario 2: Corporate Emergency Line

Scenario 3: Caller ID Privacy

Scenario 4: Multiple CoS Same Number

7. Limitations & Important Notes

Technical Limitations

Best Practices

Security Considerations

8. Troubleshooting Tips

Common Issues

Diagnostic SQL

9. Glossary

10. Suggested UI Improvements

Enhanced Tooltips

UX Enhancements

Visual Improvements

Lua Script Status ℹ️

Integration Module