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

## Table of Contents
1. [Module Overview (Technical)](#1-module-overview-technical)
2. [Module Overview (Commercial & Business Value)](#2-module-overview-commercial--business-value)
3. [🎯 User Roles & Key Capabilities](#3--user-roles--key-capabilities)
4. [Visual Interface & Form Structure](#4-visual-interface--form-structure)
5. [Architectural Flow & Upstream Trunk Ingestion](#5-architectural-flow--upstream-trunk-ingestion)
6. [Common Scenarios & Operational Playbooks](#6-common-scenarios--operational-playbooks)
7. [Troubleshooting & Diagnostic Commands](#7-troubleshooting--diagnostic-commands)
8. [Model Context Protocol (MCP) AI Integration](#8-model-context-protocol-mcp-ai-integration)
9. [Glossary](#9-glossary)

---

## 1. Module Overview (Technical)

The **Carrier Providers** module (`public.did_providers` and `didProviderService.ts`) manages upstream telecommunications carriers providing wholesale PSTN origination (DIDs, toll-free numbers, local numbers) and termination (outbound call transit). It integrates upstream vendor APIs (such as Telnyx, Twilio, Bandwidth, and generic SIP carriers), credential vaults, webhook signing secrets, and wholesale rate card mappings.

### Supported Carrier Integrations
* **Telnyx Wholesale (`telnyx`):** REST API v2 integration supporting live real-time DID search, instant on-demand ordering, emergency E911 registration, and webhook call status delivery.
* **Twilio Voice (`twilio`):** Account SID / Auth Token integration for international PSTN numbering, regulatory compliance bundles, and SIP trunking credentials.
* **Generic SIP Carrier (`generic_sip`):** Standard SIP trunking carrier utilizing static IP authentication or digest authentication with configurable SIP signaling ports and outbound proxies.

```
 ┌────────────────────────────────────────────────────────────────────────┐
 │                      Carrier Provider (public.did_providers)           │
 │  • provider_type: 'telnyx' | 'twilio' | 'generic_sip'                  │
 │  • api_key / auth_token: Encrypted Vault Token                         │
 │  • webhook_secret: HMAC Signature Validation Key                       │
 │  • target_engine_id: FK -> public.telecom_nodes (Ring2All SBC / PBX)   │
 │  • buy_rate_card_id: FK -> public.rate_cards (Wholesale Cost Deck)     │
 └───────────────────────────────────┬────────────────────────────────────┘
                                     │
           ┌─────────────────────────┴─────────────────────────┐
           │ Upstream Carrier API                              │ Downstream Voice Core
           ▼                                                   ▼
 ┌───────────────────────────────────┐               ┌───────────────────────────────────┐
 │   Upstream Vendor (e.g. Telnyx)   │               │    Ring2All SBC (Class 4 Core)    │
 │  • GET /v2/available_phone_numbers│               │  • Carrier IP Whitelist (Pike/ACL)│
 │  • POST /v2/number_orders         │               │  • kamcmd uac.reg_reload          │
 │  • Real-time Number Search        │               │  • Dynamic LCR Route Injection    │
 └───────────────────────────────────┘               └───────────────────────────────────┘
```

---

## 2. Module Overview (Commercial & Business Value)

* **Multi-Carrier Redundancy:** Prevents vendor lock-in and protects against carrier outages by aggregating multiple upstream voice providers into a single unified inventory.
* **Automated Wholesale Margin Calculation:** Pairs the upstream vendor's wholesale DID monthly rental and per-minute termination cost against customer retail pricing, displaying gross margins in real time.
* **On-Demand Inventory Acquisition:** Eliminates the capital expenditure of warehousing large blocks of unused telephone numbers; numbers are searched and provisioned in real-time from carrier APIs only when ordered by customers.

---

## 3. 🎯 User Roles & Key Capabilities

| User Role | Key Permissions | Core Responsibilities & Workflows |
| :--- | :--- | :--- |
| **Super Administrator** | Full Control & API Key Management | Registers wholesale carrier partnerships, inputs vendor API tokens, configures webhook endpoints, and assigns default cost decks. |
| **Carrier Relations Specialist**| Manage Accounts & Tariffs | Reviews wholesale contract pricing, negotiates volume discounts, and updates carrier rate card associations. |
| **Telecom Engineer** | Signaling & Trunk Alignment | Configures upstream SIP proxies, verifies codec preferences (G.711u, G.729, Opus), and checks SIP INVITE headers. |
| **Billing Analyst** | Read & Cost Reconciliation | Reconciles carrier monthly invoices against ingested wholesale CDR summaries and DID monthly rental costs. |

---

## 4. Visual Interface & Form Structure

### 4.1 Carrier Providers (List View)

The **Carrier Providers** list provides an operational overview of all active upstream vendors with carrier type badges, balance indicators, active DID counts, and configuration shortcuts.

![Carrier Providers List View](/screenshots/billing/telecom-providers/carriers/carriers-list.png)

### 4.2 Carrier Provider Configuration Form (Form View)

The **Carrier Provider Configuration** form handles API credentials, authentication types, default billing rates, assigned voice core engines, and webhook security parameters.

![Carrier Provider Configuration Form](/screenshots/billing/telecom-providers/carriers/carriers-form.png)

### 4.3 Form Parameter Reference

| Parameter Name | Data Type | Required | Default Value | Description & Business Rules |
| :--- | :--- | :---: | :--- | :--- |
| **Carrier / Provider Name** | `String` | Yes | — | Corporate brand name of the upstream carrier (e.g. `Telnyx Wholesale Carrier`). |
| **Provider Classification** | `Enum` | Yes | `telnyx` | Integration driver: `telnyx`, `twilio`, `bandwidth`, `generic_sip`. Controls API payload formats. |
| **API Key / Secret Token** | `Password`| Yes | — | Production API token issued by the carrier portal for programmatic number searches and provisioning. |
| **Webhook Signing Secret** | `Password`| No | — | HMAC secret used to verify the authenticity of incoming carrier event notifications (e.g. call status, SMS). |
| **Associated Buy Rate Card**| `Dropdown`| No | None | Wholesale rate card reflecting the vendor's per-minute termination costs for margin calculation. |
| **Target Telephony Engine** | `Dropdown`| Yes | — | Voice core node (**Ring2All SBC** or **Ring2All PBX**) where inbound signaling from this carrier is directed. |
| **Active Status** | `Boolean` | Yes | `true` | When active, the carrier is available for automated DID ordering and outbound LCR routing. |

---

## 5. Architectural Flow & Upstream Trunk Ingestion

```
   Carrier On-Demand DID Search (Web UI)
                     │
                     ▼
       BSS Encrypted Vault Lookup
  (Decrypts Carrier API Token for Telnyx)
                     │
                     ▼
 ┌──────────────────────────────────────────┐
 │  HTTPS GET /v2/available_phone_numbers   │
 │  Parameters: country_code=US, npa=305    │
 └───────────────────┬──────────────────────┘
                     │
                     ▼
 ┌──────────────────────────────────────────┐
 │       Carrier Returns Available DIDs     │
 │  • +13055550199 (Miami, FL)              │
 │  • Wholesale Cost: $0.75/month           │
 └───────────────────┬──────────────────────┘
                     │
                     ▼
 ┌──────────────────────────────────────────┐
 │       Render Results in Admin Portal     │
 │  • Display Instant Order Button          │
 │  • Calculate Retail Price & Margin       │
 └──────────────────────────────────────────┘
```

---

## 6. Common Scenarios & Operational Playbooks

### Scenario A: Configuring Telnyx for Automated Number Ordering
1. Navigate to **Telecom Providers** → **Carrier Providers** and click **+ Add**.
2. Enter Name: `Telnyx Wholesale Primary`.
3. Set **Provider Classification** to `Telnyx API v2`.
4. Paste the production **Telnyx API Key** from the Telnyx Mission Control Portal.
5. In **Target Telephony Engine**, select `Ring2All SBC Core`.
6. Under **Associated Buy Rate Card**, select `Telnyx Wholesale Deck`.
7. Click **Save Carrier**. The system instantly verifies API credentials and enables the Carrier On-Demand tab in the DIDs module.

### Scenario B: Restricting Carrier Outbound Transit During Maintenance
1. When an upstream carrier issues a planned maintenance window, open the carrier profile in the editor.
2. Toggle **Active Status** to `Inactive`.
3. Save changes. Ring2All Billing immediately updates the LCR matrix in Ring2All SBC, removing the carrier from the outbound route priority list without affecting other carriers.

---

## 7. Troubleshooting & Diagnostic Commands

### Querying Configured Carrier Providers (PostgreSQL)
```bash
su - postgres -c "psql -d ss_billing -c \"
SELECT id, name, provider_type, is_active,
       target_engine_id, created_at
FROM did_providers
ORDER BY id ASC;\""
```

### Testing Carrier API Connectivity (Telnyx API Example)
```bash
curl -s -X GET "https://api.telnyx.com/v2/phone_numbers" \
  -H "Authorization: Bearer <CARRIER_API_KEY>" \
  -H "Content-Type: application/json" | jq .
```

---

## 8. Model Context Protocol (MCP) AI Integration

The **Carrier Providers** module connects directly to the **Ring2All BSS MCP Server**, enabling telecom operations agents and NOC engineers to inspect carrier configurations, verify API status, and evaluate active trunk associations.

### Available MCP Tools

| Tool Name | Access Role | Description & Primary Function | Example Arguments |
| :--- | :--- | :--- | :--- |
| `list_carrier_providers` | `Telecom & Carrier Engineer` / `Admin` | Lists upstream wholesale telecom carrier providers (Telnyx, Twilio, Generic SIP) with status, type, and target engine. | `{"limit": 10}` |
| `get_carrier_provider` | `Telecom & Carrier Engineer` / `Admin` | Retrieves configuration details for an upstream wholesale telecom carrier provider by ID. | `{"providerId": 1}` |

### Sample MCP Tool Execution: `list_carrier_providers`

#### Request Payload
```json
{
  "name": "list_carrier_providers",
  "arguments": {
    "limit": 5
  }
}
```

#### Response Payload
```json
[
  {
    "id": 1,
    "name": "Telnyx Primary Carrier",
    "providerType": "telnyx",
    "isActive": true,
    "targetEngineId": 1,
    "createdAt": "2026-09-08T18:30:00Z"
  },
  {
    "id": 2,
    "name": "Twilio Backup Carrier",
    "providerType": "twilio",
    "isActive": true,
    "targetEngineId": 1,
    "createdAt": "2026-09-08T19:00:00Z"
  }
]
```

### Conversational AI Prompts for Copilot
* *"List all configured carrier providers and their active status."*
* *"Show detailed configuration for carrier provider ID 1."*
* *"Which carriers are currently integrated with our primary SBC node?"*

---

## 9. Glossary

* **PSTN Origination:** The delivery of telephone calls from public network callers to subscriber DIDs hosted on the carrier platform.
* **PSTN Termination:** The delivery of outbound calls placed by platform subscribers to external worldwide telephone networks.
* **Webhook Signature:** Cryptographic hash included in HTTP headers verifying that incoming events originated from the carrier and were not forged.
* **On-Demand DID Provisioning:** Real-time acquisition of telephone numbers via REST APIs without pre-purchasing large inventory pools.
* **Model Context Protocol (MCP):** Open protocol standard that enables secure, controlled integration between Large Language Models and external tools, databases, and telecom rating engines.