---
title: "SMS Providers Module Documentation"
description: "Documentation for SMS Providers"
---

## 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. [Supported Provider Types](#5-supported-provider-types)
8. [Priority, Failover & Rate Limiting](#6-priority-failover--rate-limiting)
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 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 Providers List View](/screenshots/pbx/sms/providers-list.png)

### SMS Provider Configuration Form
Standard form view for setting provider credentials, API secrets, endpoint URLs, account SIDs, webhook tokens, and throughput limits.
![SMS Provider Configuration Form](/screenshots/pbx/sms/providers-form.png)

---

## 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`)
```json
{
  "name": "Telnyx Wholesale Primary",
  "providerType": "telnyx",
  "apiKey": "KEY0182746198273641827364",
  "priority": 10,
  "isDefault": true,
  "rateLimitPerSecond": 25,
  "enabled": true
}
```
*Response:*
```json
{
  "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`)
```json
{
  "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`:

```sql
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.