SMS Routes

Ring2All Platform — SMS Routing Configuration

Parent Module: SMS Messaging

---

Overview

SMS Routes determine which provider handles outbound messages based on destination number patterns. Routes support prefix matching, country code filtering, priority ordering, and failover providers.

Admin Panel → SMS → Routes

---

Configuration Fields

Field Name	Technical Description	User-Friendly Tooltip	Example	Notes
Name	Route identifier in `name`.	A name for this routing rule.	`US Domestic`	Must be unique per domain.
Prefix Pattern	Regex pattern in `prefix_pattern`.	Number pattern to match (regex).	`^\+1[2-9]`	Matches numbers starting with this pattern.
Country Code	ISO code in `country_code`.	Country code to match (ISO 2-letter).	`US`	Alternative to prefix pattern matching.
Provider	Primary provider in `provider_id`.	Provider to use for matching messages.	`Twilio US`	First provider to try for this route.
Fallback Provider	Backup in `fallback_provider_id`.	Backup provider if primary fails.	`Telnyx`	Used when primary returns error.
Priority	Order in `priority`.	Route priority. Lower numbers match first.	`100`	Routes are evaluated in priority order.
Enabled	Toggle in `enabled`.	Enable or disable this route.	`true`	Disabled routes are not evaluated.

---

Route Matching Logic

When sending an SMS, routes are evaluated in this order:

Plaintext

1. Sort all enabled routes by priority (ascending)
2. For each route:
   a. If prefix_pattern exists:
      - Test destination against regex pattern
   b. Else if country_code exists:
      - Extract country from destination, compare
   c. If matched → Use this route's provider
3. If no route matches → Use default provider

Priority Examples

Priority	Route Name	Pattern	Provider
10	Emergency	`^\+1911`	Primary
50	US Mobile	`^\+1[2-9]\d{2}[2-9]`	Twilio
100	US Domestic	`^\+1`	Twilio
200	Canada	`^\+1[2-9]\d{2}`	Telnyx
500	International	`.`	Telnyx

> 💡 Tip: Use lower priority numbers for more specific patterns, higher for catch-all routes.

---

Pattern Matching

Prefix Pattern (Regex)

Prefix patterns use regular expressions:

Pattern	Matches	Description
`^\+1`	+1XXXXXXXXXX	All US/Canada numbers
`^\+1[2-9]\d{2}`	+1XXX...	US/Canada area codes
`^\+44`	+44XXXXXXXXX	UK numbers
`^\+52`	+52XXXXXXXXX	Mexico numbers
`^\+[2-9]`	Non-+1 numbers	All international
`.`	Everything	Catch-all default

Country Code (ISO)

Alternatively, use 2-letter ISO country codes:

Code	Country
US	United States
CA	Canada
MX	Mexico
GB	United Kingdom
DE	Germany

> ⚠️ Note: If both prefix pattern AND country code are set, prefix pattern takes precedence.

---

Failover Configuration

Each route can have a fallback provider:

Plaintext

Message to +1555...
    │
    ▼
┌─────────────────┐
│ Route: US Dom   │
│ Provider: Twilio│
└────────┬────────┘
         │
         ▼ Try Twilio
    ┌────────────┐
    │ Success?   │
    └──────┬─────┘
       Yes │  No
       ────┼────
           │
           ▼
    ┌─────────────────┐
    │ Fallback:       │
    │ Telnyx          │
    └────────┬────────┘
             │
             ▼ Try Telnyx

When Fallback Triggers

Fallback is used when primary provider returns:

HTTP 5xx errors (server error)
Timeout errors
Rate limit errors
Temporary failures

Fallback is NOT used for:

Invalid number errors
Authentication errors
Permanent failures

---

Common Route Configurations

Simple Single-Provider

One route for all messages:

Route	Pattern	Provider
All Messages	`.`	Twilio US

US + International Split

Separate providers for domestic vs. international:

Priority	Route	Pattern	Provider
100	US Domestic	`^\+1`	Twilio US
200	International	`.`	Telnyx Intl

Multi-Region with Failover

Priority	Route	Pattern	Provider	Fallback
100	US Mobile	`^\+1[2-9]`	Twilio	Bandwidth
200	Canada	`^\+1[2-9]`	Telnyx	Twilio
300	Mexico	`^\+52`	Telnyx	-
500	Default	`.`	Bandwidth	Twilio

---

Troubleshooting

Issue	Cause	Solution
Wrong provider used	Priority misconfigured	Check route priorities (lower = first)
No route matched	Pattern doesn't match	Test pattern against destination number
Failover not triggering	Non-retryable error	Check provider error type
Route not evaluating	Route disabled	Enable the route
Default provider used unexpectedly	No routes match	Add more specific routes

Testing Route Matching

To test which route a number matches:

Note the destination number (e.g., +15551234567)
List routes sorted by priority
Test each regex pattern against the number
First match wins

---

Database Schema

Sql

CREATE TABLE sms_routes (
    id                   SERIAL PRIMARY KEY,
    uuid                 UUID DEFAULT gen_random_uuid(),
    domain_id            INTEGER NOT NULL,
    name                 VARCHAR(255) NOT NULL,
    prefix_pattern       VARCHAR(100),
    country_code         VARCHAR(2),
    provider_id          INTEGER NOT NULL REFERENCES sms_providers(id),
    fallback_provider_id INTEGER REFERENCES sms_providers(id),
    priority             INTEGER DEFAULT 100,
    enabled              BOOLEAN DEFAULT TRUE,
    created_at           TIMESTAMP DEFAULT NOW(),
    created_by           INTEGER,
    updated_at           TIMESTAMP,
    updated_by           INTEGER,
    UNIQUE(domain_id, name)
);

---

See also: SMS Providers | SMS Numbers | SMS Settings*

Glossary

Term	Definition
SMS Routing	Rules directing SMS traffic to specific users or queues

---

Lua Script Status ℹ️

Integration Module

Component	Status	Notes
SMS Routes	ℹ️ Configuration module	Routing rules applied by the main SMS handler