SMS Routes Module Documentation

Table of Contents

1. Navigation & Access
2. Screenshots & Visual Interface
3. Module Overview (Technical)
4. Module Overview (Commercial / Business)
5. Module Overview (End User / Administrator)
6. Configuration Fields Reference
7. Route Matching Algorithm
8. Failover & Fallback Carrier Architecture
9. Common Scenarios & Examples
10. Model Context Protocol (MCP) AI Integration
11. Troubleshooting Tips
12. Database Schema
13. Glossary

---

Navigation & Access

To access the SMS Routes module:

1. Log in to the Ring2All Web Portal (https://<domain-or-ip>/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 Route Configuration Form

Configuration view for specifying route name, number pattern matching, destination country, primary carrier gateway, automatic failover gateway, and priority ranking.

---

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)

{
  "name": "US Domestic Wholesale",
  "prefixPattern": "+1*",
  "countryCode": "US",
  "providerId": 1,
  "fallbackProviderId": 2,
  "priority": 10,
  "enabled": true
}

Response:

{
  "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)

{
  "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:

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.