SMS Providers 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. Supported Provider Types
8. Priority, Failover & Rate Limiting
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 Providers 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 Providers (/pbx/sms/providers).
4. To create a new provider, click the + New Provider button (/pbx/sms/providers/new).
5. To edit an existing carrier, click on the edit action icon in the providers table (/pbx/sms/providers/:id).

---

Screenshots & Visual Interface

SMS Providers Overview

Displays all configured external SMS carrier connections, protocol type, active status, priority rank, default carrier flag, and rate limits.

SMS Provider Configuration Form

Standard form view for setting provider credentials, API secrets, endpoint URLs, account SIDs, webhook tokens, and throughput limits.

---

1. Module Overview (Technical)

What is an SMS Provider?

An SMS Provider in Ring2All is an external communication gateway or telecom carrier (such as Telnyx, Twilio, Bandwidth, SignalWire, or custom HTTP REST gateways) responsible for transmitting short message service (SMS) and multimedia message service (MMS) payloads to the public switched telephone network (PSTN) and mobile network operators (MNOs).

Technical Architecture

The Ring2All backend subsystem integrates with carrier APIs via asynchronous background workers and connection pooling:

• Outbound SMS requests dispatched by users, applications, or IVR callbacks are validated, inspected against opt-out tables, and submitted to the carrier API.
• Inbound SMS webhooks from carriers hit /api/v1/telephony/sms/webhook/:provider where payloads and HMAC signatures are parsed, authenticated, and mapped to destination extensions or automated chatbots.
• Delivery Receipts (DLRs) received through webhooks update the CDR status in ss_cdr.sms_messages.

┌─────────────────────────────────────────────────────────────────┐
│                    SMS Provider Architecture                    │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Ring2All Platform                                              │
│  ┌───────────────────────┐                                      │
│  │ User Portal / Webhook │                                      │
│  └───────────┬───────────┘                                      │
│              ▼                                                  │
│  ┌───────────────────────┐      REST API / JSON                 │
│  │ Fastify SMS Worker    │─────────────────────────┐            │
│  └───────────────────────┘                         ▼            │
│                                           ┌─────────────────┐   │
│                                           │  SMS Provider   │   │
│                                           │ (Telnyx/Twilio) │   │
│                                           └────────┬────────┘   │
│                                                    ▼            │
│                                           ┌─────────────────┐   │
│                                           │   Mobile MNOs   │   │
│                                           │  (AT&T/T-Mobile)│   │
│                                           └─────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

---

2. Module Overview (Commercial / Business)

Business Value & ROI

• Multi-Carrier Redundancy: Protect business communications from carrier outages by maintaining active-standby or load-balanced carrier connections.
• Cost Optimization (Least-Cost Routing): Leverage competitive per-message wholesale rates (e.g., Telnyx or BulkVS for domestic US, Twilio for international destinations).
• Brand Identity & Local Presence: Enable two-way messaging on corporate voice phone numbers, preventing customers from receiving messages from untrusted random sender numbers.
• Compliance & 10DLC Support: Built-in support for carrier campaign profiles (10DLC A2P messaging) avoiding costly carrier spam penalties and delivery blocks.

---

3. Module Overview (End User / Administrator)

Administrator Experience

Administrators configure API credentials provided by telecom vendors:

• Set global sending throughput limits (messages per second) to prevent carrier throttling (HTTP 429 Too Many Requests).
• Designate primary and fallback carriers.
• Monitor provider connectivity, response codes, and delivery health across all provisioned domains.

---

4. Configuration Fields Reference

Field Name	Technical Description	User-Friendly Tooltip	Example	Notes
Name	Unique identifier in sms_providers.name.	A friendly name for this SMS carrier connection.	Telnyx US Carrier	Unique per domain.
Provider Type	Carrier protocol in provider_type.	Select the carrier API integration.	telnyx	Options: telnyx, twilio, bandwidth, signalwire, bulkvs, custom.
API Key	Primary bearer token in api_key.	API key or token generated in provider portal.	KEY0182746194...	Stored securely; masked in interface.
API Secret	Secondary secret/token in api_secret.	Provider auth secret or token.	SS_SECRET_TELNYX_01	Required for Twilio Auth Token or signed webhooks.
Account SID	Provider account id in account_sid.	Account SID identifier (primarily Twilio).	AC9876543210...	Required when provider type is twilio.
API Endpoint	HTTP URL in api_endpoint.	Custom REST API URL for generic or private carriers.	https://api.telnyx.com/v2/messages	Pre-populated based on provider type.
Webhook URL	Inbound HTTP hook in webhook_url.	URL for receiving incoming SMS and delivery receipts.	https://pbx.ring2all.xyz/api/v1/telephony/sms/webhook/telnyx	Copy this URL into the carrier dashboard.
Webhook Secret	Verification key in webhook_secret.	Shared secret to validate incoming webhook signatures.	whsec_9837410...	Prevents unauthorized spoofed webhook posts.
Priority	Rank in priority.	Order of preference. Lower numbers are evaluated first.	10	Default is 100. Lower value = higher priority.
Is Default	Boolean flag in is_default.	Sets this provider as default fallback for unmatched routes.	true	Only one provider per domain should be default.
Rate Limit (per sec)	Numeric rate in rate_limit_per_second.	Maximum outgoing messages dispatched per second.	20	Prevents carrier rate violations and 429 errors.
Enabled	Boolean toggle in enabled.	Activate or deactivate this provider connection.	true	Inactive carriers are skipped during routing.

---

5. Supported Provider Types

Telnyx (Recommended)

• Authentication: API Key (V2 API).
• Features: Fast delivery receipts, 10DLC messaging profiles, high throughput, low latency.
• Webhook Configuration: In the Telnyx Mission Control Portal, create a Messaging Profile and paste the Ring2All Webhook URL.

Twilio

• Authentication: Account SID + Auth Token (api_secret).
• Features: Global coverage, automatic phone number binding, standard MMS support.
• Webhook Configuration: In the Twilio Console, set the phone number’s “A MESSAGE COMES IN” webhook to HTTP POST with the Ring2All Webhook URL.

Bandwidth

• Authentication: Account ID (account_sid) + API Token (api_key) + Secret (api_secret).
• Features: High-volume wholesale messaging, direct Tier-1 carrier connectivity.

Generic / Custom HTTP Gateway

• Authentication: Custom HTTP Headers, Bearer tokens, or basic auth.
• Features: Allows integrating private SMS gateways, local GSM modems, or regional SMS aggregators via JSON REST endpoints.

---

6. Priority, Failover & Rate Limiting

Providers work in tandem with the SMS Routes module:

1. When an outbound message is generated, matching routes determine the assigned primary carrier.
2. If multiple carriers have identical routing priority, the system uses the lowest numeric priority value.
3. If the primary carrier returns an error (HTTP 5xx, network timeout, or negative DLR), the engine immediately switches to the designated Fallback Provider.
4. The background queue regulates requests to match rate_limit_per_second, distributing high-volume campaigns cleanly without triggering provider blocks.

---

7. Common Scenarios & Examples

Scenario A: Domestic Primary with Automatic Failover

• Primary Carrier: Telnyx US Carrier (priority: 10, is_default: true).
• Backup Carrier: Twilio Cloud SMS (priority: 20, is_default: false).
• Result: All standard SMS goes through Telnyx at competitive rates. In case of API disruption, Twilio automatically routes failed messages.

Scenario B: Dedicated International Provider

• Domestic Carrier: Telnyx for US/Canada (+1).
• International Carrier: Twilio for all destination numbers starting with + outside NANP (+44, +34, +52).

---

8. Model Context Protocol (MCP) AI Integration

The Ring2All Model Context Protocol (MCP) server provides native tools for inspecting, provisioning, updating, and safely removing SMS wholesale carrier gateways through natural language interactions. Agents and Copilots can manage carrier priorities, monitor rate limits, and audit credentials with strict domain isolation and referential integrity protection.

Available MCP Tools

Tool Name	Operation	Description	Target Entity
list_sms_providers	Read	Lists all SMS wholesale carrier gateways for the domain with status, priority, and rate limit	Carrier List
get_sms_provider	Read	Retrieves detailed configuration and webhook credentials for a specific SMS carrier	Single Carrier
create_sms_provider	Write	Provisions a new wholesale SMS carrier connection (Telnyx, Twilio, Bandwidth, Sinch, Plivo, Generic)	New Carrier
update_sms_provider	Write	Modifies carrier credentials, default status, priority rank, or MPS rate limit	Existing Carrier
delete_sms_provider	Write	Deletes an SMS carrier (guarded against active number or route dependencies)	Inactive Carrier

Protection & Validation Guards

• Dependency & Deletion Protection (assertCanDeleteSmsProvider): The MCP server prevents the deletion of any carrier provider if active SMS phone numbers (sms_numbers) or SMS routing rules (sms_routes) are bound to it. Furthermore, any carrier designated as the domain default (is_default = true) cannot be removed without first designating an alternate default carrier.
• Domain Name Uniqueness: Enforced both in controller validation and database constraint uq_sms_providers_domain_name. Attempting to register two providers with the same name within the same domain is strictly rejected.
• Credential Masking & Security: Webhook secrets and auth tokens are handled with strict encryption at rest and masked in public AI responses.

Example MCP Payloads

1. Creating a Wholesale SMS Provider (create_sms_provider)

{
  "name": "Telnyx Wholesale Primary",
  "providerType": "telnyx",
  "apiKey": "KEY0182746198273641827364",
  "priority": 10,
  "isDefault": true,
  "rateLimitPerSecond": 25,
  "enabled": true
}

Response:

{
  "success": true,
  "data": {
    "id": 3,
    "name": "Telnyx Wholesale Primary",
    "provider_type": "telnyx",
    "webhook_url": "/api/webhooks/sms/telnyx/1",
    "priority": 10,
    "is_default": true,
    "enabled": true,
    "message": "SMS provider \"Telnyx Wholesale Primary\" created successfully."
  }
}

2. Updating Carrier Throughput (update_sms_provider)

{
  "identifier": "Telnyx Wholesale Primary",
  "rateLimitPerSecond": 50,
  "priority": 5
}

Copilot Natural Language Prompts

• “Show all configured SMS wholesale providers and their priority ranking.”
• “Check the configuration details and webhook URL for carrier ‘Telnyx Wholesale Primary’.”
• “Register a new backup SMS provider named ‘Twilio Secondary’ using providerType ‘twilio’ with priority 20.”
• “Increase the rate limit for carrier ‘Telnyx Wholesale Primary’ to 50 messages per second.”
• “Verify whether provider ‘Twilio Secondary’ can be safely removed or if any routes depend on it.”

---

9. Troubleshooting Tips

Symptom	Probable Cause	Corrective Action
HTTP 401 Unauthorized	Invalid API Key or Account SID	Verify credentials directly in carrier management console.
HTTP 429 Too Many Requests	Carrier throughput exceeded	Decrease rate_limit_per_second in the provider configuration.
Inbound SMS Not Received	Webhook URL misconfigured	Ensure Webhook URL is accessible externally and configured in carrier portal.
Webhook Signature Mismatch	Webhook Secret does not match	Re-copy the signing secret from the carrier dashboard.

---

10. Database Schema

SMS providers are stored in the ss_telephony database within table sms_providers:

CREATE TABLE public.sms_providers (
    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,
    provider_type         VARCHAR(50) NOT NULL,
    api_key               VARCHAR(255),
    api_secret            VARCHAR(255),
    api_endpoint          VARCHAR(255),
    account_sid           VARCHAR(100),
    webhook_url           VARCHAR(255),
    webhook_secret        VARCHAR(100),
    priority              INTEGER DEFAULT 100,
    is_default            BOOLEAN DEFAULT FALSE,
    enabled               BOOLEAN DEFAULT TRUE,
    rate_limit_per_second INTEGER DEFAULT 10,
    settings              JSONB DEFAULT '{}'::jsonb,
    created_at            TIMESTAMPTZ NOT NULL DEFAULT now(),
    created_by            INTEGER,
    updated_at            TIMESTAMPTZ,
    updated_by            INTEGER,
    CONSTRAINT uq_sms_providers_domain_name UNIQUE (domain_id, name)
);

---

11. Glossary

• 10DLC: 10-digit long code standard for Application-to-Person (A2P) commercial SMS messaging in North America.
• DLR (Delivery Receipt): Carrier notification indicating whether an SMS successfully reached the handset.
• MNO: Mobile Network Operator (cellular carrier like Verizon, T-Mobile, AT&T).
• Throughput (MPS): Messages Per Second allowed across a specific messaging profile or carrier API endpoint.