---
title: "Direct Route Module Documentation"
description: "Documentation for Direct Route"
---

## Table of Contents
1. [Module Overview (Technical)](#1-module-overview-technical)
2. [Module Overview (Commercial/Business)](#2-module-overview-commercialbusiness)
3. [Module Overview (End User/Administrator)](#3-module-overview-end-useradministrator)
4. [User Roles & Key Capabilities](#-user-roles--key-capabilities)
5. [Configuration Fields Reference](#4-configuration-fields-reference)
6. [Call Flow / Logic Explanation](#5-call-flow--logic-explanation)
7. [Common Scenarios & Examples](#6-common-scenarios--examples)
8. [Model Context Protocol (MCP) AI Integration](#7-model-context-protocol-mcp-ai-integration)
9. [Limitations & Important Notes](#8-limitations--important-notes)
10. [Troubleshooting Tips](#9-troubleshooting-tips)
11. [Glossary](#10-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.

![Direct Route List View](/screenshots/pbx/applications/direct-route-list.png)

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

![Direct Route Configuration Form](/screenshots/pbx/applications/direct-route-form.png)

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

```json
{
  "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:**
```json
{
  "tool": "create_direct_route",
  "arguments": {
    "name": "London HQ Bypass",
    "numberToDial": "+442079460123",
    "classOfServicesId": 3,
    "description": "Exempt London HQ from international call restrictions"
  }
}
```

**MCP Response:**
```json
{
  "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:**
```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];
```

---

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