Direct Route Module Documentation

Table of Contents

1. Module Overview (Technical)
2. Module Overview (Commercial/Business)
3. Module Overview (End User/Administrator)
4. User Roles & Key Capabilities
5. Configuration Fields Reference
6. Call Flow / Logic Explanation
7. Common Scenarios & Examples
8. Model Context Protocol (MCP) AI Integration
9. Limitations & Important Notes
10. Troubleshooting Tips
11. Glossary

---

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

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

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

---

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

1. Partner/Vendor Access

   • International call restriction is on
   • Need to call specific overseas vendor
   • Create Direct Route for that specific number

2. Emergency Contacts

   • Allow specific numbers regardless of CoS
   • Corporate emergency line, CEO mobile, etc.

3. Customer Service Numbers

   • Toll-free customer support numbers
   • Specific client hotlines

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

Navigation

1. Navigate to PBX → Applications → Direct Route in the main sidebar.
2. The list view displays all configured direct route exceptions, detailing their Route Name, Number to Dial, assigned Class of Service, Description, and Enabled status.
3. Click the + Add button in the upper toolbar to configure a new direct route exception.
4. Click any row or the edit icon to modify routing parameters, update the authorized Class of Service, or change Caller ID overrides.

User Workflow

┌─────────────────────────────────────────────────────────────────┐
│                 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: Yes                                                 │
│                                                                 │
│  5. Save → Sales can now dial +44-20-7946-0958                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Tips

[!TIP] Use Full Number Format: Include country code and complete prefix for international numbers (e.g., +44-20-7946-0958).

[!TIP] Document Purpose: Use a clear, identifiable name so administrators know why the exception was granted.

[!CAUTION] CoS Must Match: The route exception only applies to users whose extension is assigned to the specified Class of Service.

---

🎯 User Roles & Key Capabilities

Role	Key Capabilities	Best Practice / Limitations
Super Admin	Full cross-tenant configuration of direct routes, OCS pre-routing rating enforcement, and trunk assignment.	Ensure direct routes have unique dial numbers per domain to prevent dialplan collisions.
PBX Administrator	Create, edit, and disable direct route bypass exceptions for assigned Class of Service profiles; set custom outbound Caller ID.	Audit bypass numbers periodically and remove obsolete exceptions to maintain toll restriction integrity.
Branch Manager	View existing direct route bypasses; request new exceptions for specific vendor or partner numbers.	Coordinate with PBX admins to identify required Class of Service groups before provisioning.
Agent / Extension User	Transparently dial authorized direct route numbers without encountering Class of Service restrictions or block messages.	Destination must match dialed digit format exactly (e.g., standard E.164 with international prefix).

---

4. Configuration Fields Reference

Basic Information Section

Field	Technical Description	User-Friendly Tooltip	Example	Required	Notes
Name *	Unique identifier for this direct route exception	Descriptive name identifying who or why this direct route exists	National Priority Route, UK Vendor Access	Yes	The system auto-derives context and description from this name.
Caller ID Name	Custom outbound Caller ID display name	Optional custom caller ID name displayed to the recipient when dialing this destination	Ring2All PBX, VIP Support	No	Overrides default tenant or extension caller ID name.
Caller ID Number	Custom outbound Caller ID telephone number	Optional custom phone number shown to the recipient	+15551234567	No	Overrides default tenant or extension caller ID number. E.164 format recommended.
Number To Dial *	Exact external phone number to route	The telephone number to dial (e.g. +44-20-7946-0958 or 9110)	9110, +44-20-7946-0958	Yes	Must match the dialed number format.
Class of Service *	Class of Service group authorized for this route	Select the Class of Service profile that is allowed to bypass restrictions using this route	Default, Local Only	Yes	Dropdown list populated from configured Classes of Service.
Enabled	Master activation toggle	Enable or disable this route without deleting it	Yes / No (toggle)	Yes	Default: Yes. Inactive routes revert to standard outbound routing.

---

5. Call Flow / Logic Explanation

Direct Route Checking Flow

┌─────────────────────────────────────────────────────────────────┐
│                  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. Model Context Protocol (MCP) AI Integration

Direct Route exceptions can be programmatically audited, created, and managed via the Model Context Protocol (MCP). AI copilots can analyze toll-restriction exception requests and safely create bypass rules without compromising security boundaries or colliding with dialplan resources.

Available MCP Tools

Tool Name	Operation	Description	Access Level
list_direct_routes	Query	List all direct bypass routes, assigned Class of Service, and destination numbers.	Read-Only
get_direct_route_status	Query	Retrieve detailed rule configuration for a specific route name or dialed number.	Read-Only
create_direct_route	Provisioning	Create a new CoS exception route for a specific dialed number with optional Caller ID masking.	Admin / Superadmin
update_direct_route	Management	Modify target number, CoS association, or Caller ID values for an existing direct route.	Admin / Superadmin
delete_direct_route	Deprovisioning	Remove a direct route exception from the PBX.	Superadmin

Tool Definitions & Parameter Reference

create_direct_route

Creates a Class of Service bypass rule for a specific dial string.

{
  "name": "create_direct_route",
  "description": "Create a new Direct Route to bypass Class of Service restrictions for a specific external phone number.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "name": { "type": "string", "description": "Friendly name (e.g. 'UK Support Center Exception')." },
      "numberToDial": { "type": "string", "description": "Exact destination phone number (e.g. '+442079460958' or '18005550199')." },
      "classOfServicesId": { "type": "number", "description": "Class of Service ID allowed to use this bypass." },
      "callerIdName": { "type": "string", "description": "Optional Caller ID Name override for this destination." },
      "callerIdNumber": { "type": "string", "description": "Optional Caller ID Number override for this destination." },
      "description": { "type": "string", "description": "Optional notes or business reason for the exception." }
    },
    "required": ["name", "numberToDial"]
  }
}

Safety Safeguards & Number Uniqueness

1. Domain Number Collision Prevention: The backend verifies validateNumberUniqueness(numberToDial, domainId, 'direct_routes') against public.dialplan_registry and active routes. If the number conflicts with an internal extension or system resource in the domain, the tool returns a clear conflict error.
2. Class of Service Verification: If classOfServicesId is not explicitly provided, the system defaults to the lowest-privilege standard profile or resolves it by domain context to prevent unauthorized privilege escalation.

Example AI Assistant Prompts & Workflow

Example 1: Creating an International Vendor Bypass

Admin Prompt:
“Create a direct route allowing calls to London Headquarters at +442079460123 for users with Class of Service ID 3.”

AI Tool Execution:

{
  "tool": "create_direct_route",
  "arguments": {
    "name": "London HQ Bypass",
    "numberToDial": "+442079460123",
    "classOfServicesId": 3,
    "description": "Exempt London HQ from international call restrictions"
  }
}

MCP Response:

{
  "success": true,
  "data": {
    "message": "Direct Route 'London HQ Bypass' to dial '+442079460123' created successfully!",
    "name": "London HQ Bypass",
    "numberToDial": "+442079460123",
    "callerIdName": "Default",
    "callerIdNumber": "Default",
    "id": 8
  }
}

---

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

1. Document Everything: Always explain why the exception exists in the description
2. Review Regularly: Audit direct routes quarterly—remove obsolete ones
3. Limit Usage: Direct routes are exceptions, not primary routing
4. 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.

---

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

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:

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:

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

---

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

---

Documentation last updated: January 2026