Carrier Providers Module Documentation

Module Overview (Technical)
Module Overview (Commercial & Business Value)
🎯 User Roles & Key Capabilities
Visual Interface & Form Structure
Architectural Flow & Upstream Trunk Ingestion
Common Scenarios & Operational Playbooks
Troubleshooting & Diagnostic Commands
Model Context Protocol (MCP) AI Integration
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

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

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

Navigate to Telecom Providers → Carrier Providers and click + Add.
Enter Name: Telnyx Wholesale Primary.
Set Provider Classification to Telnyx API v2.
Paste the production Telnyx API Key from the Telnyx Mission Control Portal.
In Target Telephony Engine, select Ring2All SBC Core.
Under Associated Buy Rate Card, select Telnyx Wholesale Deck.
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

When an upstream carrier issues a planned maintenance window, open the carrier profile in the editor.
Toggle Active Status to Inactive.
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)

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)

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

{
  "name": "list_carrier_providers",
  "arguments": {
    "limit": 5
  }
}

Response Payload

[
  {
    "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.