--- title: "SMS Routes Module Documentation" description: "Documentation for SMS 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-commercial--business) 5. [Module Overview (End User / Administrator)](#3-module-overview-end-user--administrator) 6. [Configuration Fields Reference](#4-configuration-fields-reference) 7. [Route Matching Algorithm](#5-route-matching-algorithm) 8. [Failover & Fallback Carrier Architecture](#6-failover--fallback-carrier-architecture) 9. [Common Scenarios & Examples](#7-common-scenarios--examples) 10. [Model Context Protocol (MCP) AI Integration](#8-model-context-protocol-mcp-ai-integration) 11. [Troubleshooting Tips](#9-troubleshooting-tips) 12. [Database Schema](#10-database-schema) 13. [Glossary](#11-glossary) --- ## Navigation & Access To access the SMS Routes module: 1. Log in to the Ring2All Web Portal (`https:///login`). 2. In the left navigation sidebar, expand **PBX Engine**. 3. Under **SMS Messaging**, click **Routes** (`/pbx/sms/routes`). 4. To add a new outbound SMS route, click the **+ New Route** button (`/pbx/sms/routes/new`). 5. To edit an existing route, click the edit action icon in the table (`/pbx/sms/routes/:id`). --- ## Screenshots & Visual Interface ### SMS Routes Overview Displays all configured outbound SMS routing policies, destination prefix patterns, ISO country filters, assigned primary provider, fallback provider, priority, and enabled state. ![SMS Routes List View](/screenshots/pbx/sms/routes-list.png) ### SMS Route Configuration Form Configuration view for specifying route name, number pattern matching, destination country, primary carrier gateway, automatic failover gateway, and priority ranking. ![SMS Route Configuration Form](/screenshots/pbx/sms/routes-form.png) --- ## 1. Module Overview (Technical) ### What is an SMS Route? An **SMS Route** is an intelligent policy rule in Ring2All that dictates which telecom carrier gateway is selected to deliver an outbound text message based on the recipient's phone number, destination prefix, or country. ### Routing Execution Pipeline When an outbound message is dispatched: 1. The destination E.164 number is evaluated against active routes ordered by `priority ASC`. 2. Matching occurs via: - **Prefix Pattern**: Wildcard or Regex matching (e.g., `+1*` for North America, `+44*` for UK). - **Country Code**: 2-letter ISO code (e.g., `US`, `CA`, `MX`, `GB`). 3. Once a route matches, the message is dispatched to the **Primary Provider**. 4. If the primary provider fails (network timeout, HTTP 5xx error, or fatal carrier response code), the engine invokes the **Fallback Provider**. 5. If no route matches, the system dispatches via the domain's **Default Provider**. ``` Outbound SMS Destination: +13055550144 │ ▼ ┌─────────────────────────┐ │ Evaluate Active Routes │ │ Ordered by Priority ASC │ └──────────┬──────────────┘ │ ├─► Priority 10: Prefix "+1*" (Matches North America) │ │ │ ▼ │ Dispatch via Primary Provider (Telnyx) │ │ │ ├─► Success ──► Delivered to Handset │ │ │ └─► Carrier Failure ──► Auto-Switch to Fallback (Twilio) │ └─► No Route Matches ──► Dispatch via Domain Default Provider ``` --- ## 2. Module Overview (Commercial / Business) ### Business Value & Least Cost Routing (LCR) - **Least-Cost Messaging (LCR)**: SMS rates vary drastically across geographies. Directing US/Canada domestic traffic to low-cost wholesale aggregators (e.g., Telnyx) while routing international destinations through global networks (e.g., Twilio) significantly lowers monthly telecom expenditures. - **Zero-Downtime Reliability**: Telecom carrier outages or API rate limit blocks automatically trigger backup routes, ensuring critical business notifications, one-time passwords (OTP), and dispatch alerts never get lost. - **Geographic Routing Compliance**: Route messages according to local country regulations, avoiding carrier filtering or delivery rejections. --- ## 3. Module Overview (End User / Administrator) ### Administrator Experience Administrators build a routing matrix suited to their telecom agreements: - Define specific priority ranks (lower number = higher precedence). - Configure emergency, transactional, and marketing routes with separate carrier profiles. - Set up automatic backup paths without requiring manual intervention during carrier maintenance. --- ## 4. Configuration Fields Reference | Field Name | Technical Description | User-Friendly Tooltip | Example | Notes | |------------|----------------------|----------------------|---------|-------| | **Route Name** | Friendly name in `name`. | A descriptive identifier for this SMS route. | `North America Standard Route` | Must be unique per domain. | | **Prefix Pattern** | Wildcard/regex in `prefix_pattern`. | Number prefix or pattern to match recipient numbers. | `+1*` | Supports prefixes like `+1*`, `+44*`, `+52*`, `+*`. | | **Country Code** | ISO 3166-1 alpha-2 in `country_code`. | 2-letter destination country code. | `US` | Alternative or supplement to prefix pattern. | | **Primary Provider** | Foreign key in `provider_id`. | Telecom carrier gateway to use for this route. | `Telnyx US Carrier` | First carrier attempted for matched messages. | | **Fallback Provider**| Foreign key in `fallback_provider_id`. | Backup carrier if primary provider fails. | `Twilio Cloud SMS` | Optional; provides automatic fault-tolerant failover. | | **Priority** | Rank in `priority`. | Evaluation priority. Lower numbers are evaluated first. | `10` | 1 to 999. Default is 100. | | **Enabled** | Boolean toggle in `enabled`. | Activate or deactivate this routing rule. | `true` | Disabled routes are skipped during evaluation. | --- ## 5. Route Matching Algorithm When routing a message: 1. All enabled routes for the domain are loaded, sorted by `priority ASC`, then `id ASC`. 2. For each route: - If `prefix_pattern` is defined: The recipient number is tested against the pattern. If it matches, this route is chosen. - If `country_code` is defined and no prefix pattern is set: The recipient number's country is derived via libphonenumber standards. If it matches, this route is chosen. 3. If both match criteria are configured, `prefix_pattern` takes precedence. 4. Catch-all routes (e.g., `+*` or country code `ALL`) should always have high priority numbers (e.g., `priority: 500` or `1000`) so more specific routes match first. --- ## 6. Failover & Fallback Carrier Architecture Automatic failover ensures business continuity: - **Trigger Conditions**: - HTTP 500, 502, 503, 504 server errors from carrier API. - Network timeout (> 3000ms). - Carrier account suspension or credential expiration error. - **Failover Execution**: - The message status in `ss_cdr.sms_messages` notes the failover attempt. - The message is immediately queued for the `fallback_provider_id`. - The fallback provider credentials are used to dispatch the message without requiring client-side re-submission. --- ## 7. Common Scenarios & Examples ### Scenario 1: Domestic LCR with High-Availability Failover - **Route Name**: North America LCR - **Prefix**: `+1*` - **Primary Provider**: Telnyx ($0.004 / msg) - **Fallback Provider**: Twilio ($0.0079 / msg) - **Priority**: 10 - **Result**: Maximum cost savings under normal operations with 99.999% delivery reliability. ### Scenario 2: International Catch-All Route - **Route Name**: Global RoW (Rest of World) - **Prefix**: `+*` - **Primary Provider**: Twilio Cloud SMS - **Fallback Provider**: None - **Priority**: 200 - **Result**: All international numbers outside +1 route through Twilio's global carrier interconnects. --- ## 8. Model Context Protocol (MCP) AI Integration The Ring2All Model Context Protocol (MCP) server provides tools for managing outbound SMS routing policies, least-cost routing (LCR), and carrier failover rules dynamically through natural language interactions. Agents can inspect active route tables, tune priority orders, provision prefix-based carrier channels, and verify high-availability routing resilience. ### Available MCP Tools | Tool Name | Operation | Description | Target Entity | |---|---|---|---| | `list_sms_routes` | Read | Lists all outbound SMS routing rules ordered by priority with prefix matching and failover provider | Route Policies | | `get_sms_route` | Read | Retrieves detailed outbound route parameters by ID or name | Single Route | | `create_sms_route` | Write | Provisions a new pattern-based outbound SMS route with carrier prioritization and failover backup | New Route | | `update_sms_route` | Write | Modifies route prefix pattern, country filter, provider assignments, or priority | Existing Route | | `delete_sms_route` | Write | Removes an outbound SMS route | Inactive Route | ### Protection & Validation Guards - **Strict Domain Route Name Uniqueness**: Every route name within a domain must be strictly unique (`uq_sms_routes_domain_name`). Duplicate names trigger immediate rejection with a 409 Conflict status. - **Provider Referential Integrity**: Both `provider_id` and `fallback_provider_id` must resolve to valid, active SMS carrier providers within the current domain. - **Priority-Ordered Evaluation**: Routes are strictly evaluated in ascending numeric order of `priority` (e.g., 10 executes before 50), ensuring specific international or promotional routes take precedence over generic catch-all rules (`+*`). ### Example MCP Payloads #### 1. Creating a Domestic Outbound Route with Failover (`create_sms_route`) ```json { "name": "US Domestic Wholesale", "prefixPattern": "+1*", "countryCode": "US", "providerId": 1, "fallbackProviderId": 2, "priority": 10, "enabled": true } ``` *Response:* ```json { "success": true, "data": { "id": 5, "name": "US Domestic Wholesale", "prefix_pattern": "+1*", "priority": 10, "enabled": true, "message": "SMS route \"US Domestic Wholesale\" created successfully." } } ``` #### 2. Re-prioritizing an International Route (`update_sms_route`) ```json { "identifier": "US Domestic Wholesale", "priority": 5, "fallbackProviderId": 3 } ``` ### Copilot Natural Language Prompts - *"Show all outbound SMS routes in our domain ordered by priority."* - *"Check the configuration details of outbound route 'US Domestic Wholesale'."* - *"Create an outbound route named 'Mexico Wholesale' for prefix '+52*' with Telnyx as primary and Twilio as fallback."* - *"Adjust the priority of route 'Global RoW' to 150 so it evaluates after domestic routes."* - *"Delete obsolete outbound SMS route 'Legacy Promo Route'."* --- ## 9. Troubleshooting Tips | Symptom | Probable Cause | Corrective Action | |---------|----------------|-------------------| | **Messages routed to wrong carrier** | Route priority inverted | Lower the `priority` numeric value for the preferred specific route. | | **International SMS fails** | No matching international route | Create a catch-all route (`+*`) pointing to a global carrier. | | **Failover not triggering** | Fallback provider disabled or unset | Select an active carrier in the `fallback_provider_id` dropdown. | | **Regex syntax error** | Invalid pattern entered | Use standard prefix syntax like `+1*` or valid POSIX regex `^\+1`. | --- ## 10. Database Schema SMS routes are stored in table `sms_routes` within `ss_telephony`: ```sql CREATE TABLE public.sms_routes ( id SERIAL PRIMARY KEY, uuid UUID NOT NULL DEFAULT uuid_generate_v4(), domain_id INTEGER NOT NULL REFERENCES domains(id) ON DELETE CASCADE, name VARCHAR(100) NOT NULL, prefix_pattern VARCHAR(20), country_code VARCHAR(3), provider_id INTEGER NOT NULL REFERENCES sms_providers(id), priority INTEGER DEFAULT 100, fallback_provider_id INTEGER REFERENCES sms_providers(id), enabled BOOLEAN DEFAULT TRUE, created_at TIMESTAMPTZ NOT NULL DEFAULT now(), created_by INTEGER, updated_at TIMESTAMPTZ, updated_by INTEGER, CONSTRAINT uq_sms_routes_domain_name UNIQUE (domain_id, name) ); ``` --- ## 11. Glossary - **LCR (Least Cost Routing)**: Directing telecommunications traffic via the lowest-cost available transmission provider. - **Failover**: Automated switching to a redundant or standby carrier upon failure of the primary gateway. - **Prefix Pattern**: Character sequence representing country and area dial codes used for pattern matching. - **Priority**: Ordering mechanism where smaller integer values take precedence during route evaluation.