Numbers & SIP Trunks (Client Self-Care) Module Documentation

Module Code: billing/client/numbers-trunks
Route: /portal/telephony
Backend Service: clientService.ts (ring2all-billing-api)
Database Tables: dids, customer_ip_endpoints, customers
Brand Purity: 100% White-Label Compliant (Ring2All Billing)

Executive Summary & Commercial Autonomy
Technical Architecture & Real-Time Sync Pipeline
🎯 User Roles & Key Capabilities
Visual Interface & Screen Breakdown
Inbound DID Routing Engine & Features
SBC IP Whitelist & Trunk Peering Security
Database Schema & Data Dictionary
Diagnostic CLI & Operational Playbooks
Domain Glossary

1. Executive Summary & Commercial Autonomy

The Numbers & SIP Trunks module provides enterprise PBX clients, wholesale VoIP aggregators, and commercial subscribers with total self-service sovereignty over their inbound telephone numbers (DIDs), outbound SIP trunk authentication credentials, and SBC IP whitelist endpoints.

+-------------------------------------------------------------------------------+
|                       COMMERCIAL & OPERATIONAL IMPACT                         |
+-------------------------------------------------------------------------------+
| • Zero-Touch Trunk Turnup: Customers whitelist office IP addresses instantly   |
|   without engineering intervention or provisioning delays.                   |
| • Granular DID Routing: Dynamically route calls to hosted PBX extensions,     |
|   external SIP URIs, or PSTN failover destinations in real time.              |
| • Multi-Channel Capacity: Real-time channel burst limits per number.          |
| • Regulatory Compliance: Self-service E911 emergency registration and CNAM.   |
+-------------------------------------------------------------------------------+

2. Technical Architecture & Real-Time Sync Pipeline

The client portal interacts with the Ring2All Billing core API to inspect leased DIDs and manage IP-authenticated SIP trunks. When a client adds an IP endpoint, it is instantaneously committed to PostgreSQL and synced to the perimeter SBC cluster:

 ┌────────────────────────────────────────────────────────────────────────┐
 │            Client Browser (Ring2All Billing Client Portal)             │
 │            Route: /portal/telephony                                    │
 └───────────────────────────────────┬────────────────────────────────────┘
                                     │ HTTPS / JWT Auth
                                     ▼
 ┌────────────────────────────────────────────────────────────────────────┐
 │            Ring2All Billing API Engine (Fastify 5 / Node.js 22)         │
 │            Endpoints: GET /api/client/dids, POST /ip-endpoints         │
 └─────────────────┬──────────────────────────────────┬───────────────────┘
                   │                                  │
      SQL (Atomic) │                     RPC Dispatch │ (kamcmd / BINRPC)
                   ▼                                  ▼
 ┌───────────────────────────────────┐  ┌─────────────────────────────────┐
 │   PostgreSQL 17 (ss_billing)      │  │   Ring2All Perimeter SBC        │
 │   • public.dids                   │  │   • Kamailio 6.1 permissions    │
 │   • public.customer_ip_endpoints  │  │   • Real-Time Address Reload    │
 │   • public.customers              │  │   • Sub-millisecond Anti-Fraud  │
 └───────────────────────────────────┘  └─────────────────────────────────┘

3. 🎯 User Roles & Key Capabilities

The module enforces strict multi-tenant customer isolation, ensuring each subscriber only inspects and mutates their assigned telephone numbers and gateway endpoints.

User Role	Access Level	Primary Operational Capabilities
Enterprise Telecom Manager	Full Access	Whitelists IP PBX addresses, routes inbound DIDs to extensions or ring groups, activates E911 and CNAM caller ID listings.
Wholesale Carrier Interconnect	Trunk Configuration	Configures SIP credentials, verifies IP trunk peering status, monitors channel allocations and concurrent call quotas.
NOC / Technical Administrator	Diagnostic & Audit	Inspects active SIP registrar URIs, reviews porting lock status, audits IP endpoint synchronization against SBC address tables.
Financial / Billing Auditor	Read-Only	Inspects leased DID monthly fees, setup fees, and channel surcharge metrics for accounting reconciliation.

4. Visual Interface & Screen Breakdown

4.1 Numbers & SIP Trunks Inventory Overview

The primary interface organizes numbers, credentials, and IP endpoints into structured, responsive data cards:

Numbers & SIP Trunks Overview

Leased DIDs Table: Displays formatted telephone numbers, state/city location, allocated channel capacity, current routing target (e.g., Mini-PBX, IP Endpoint), and action buttons.
SIP Credentials Card: Outlines the primary SIP Registrar host (sbc.carrier.com), port (5060), SIP username, and interactive copy/reveal controls.
SBC IP Whitelist: Lists authorized customer PBX IP addresses with active sync status badges.

Customers click Add IP Endpoint to whitelist an on-premise PBX or remote cloud gateway:

Add SBC IP Whitelist Modal

Endpoint Name: Friendly identifier (e.g., Miami Core SBC Trunk).
IP Address & Port: Public IPv4 address and signaling port (default 5060).
Signaling Protocol: Protocol selection between UDP, TCP, or TLS.
Subnet Mask: Prefix bitmask (default /32 for single host).

5. Inbound DID Routing Engine & Features

The routing modal offers 4 deterministic delivery paths:

                        ┌───────────────────────────────┐
                        │   Incoming Call on Leased DID │
                        └───────────────┬───────────────┘
                                        │
           ┌────────────────────────────┼────────────────────────────┐
           │                            │                            │
           ▼                            ▼                            ▼
 ┌───────────────────┐        ┌───────────────────┐        ┌───────────────────┐
 │   Hosted PBX      │        │  Customer Trunk   │        │ External SIP URI  │
 │   Delivered to    │        │  Dispatched to    │        │ Forwarded via SIP │
 │   Cloud Extension │        │  Whitelisted IP   │        │ Proxy to URI      │
 └───────────────────┘        └───────────────────┘        └───────────────────┘

Route to Hosted PBX Domain: Directly hands the call off to Ring2All PBX routing scripts for extension, IVR, or call center queue processing.
Route to IP Trunk Endpoint: Bypasses PBX IVR logic and sends SIP INVITE directly to the customer’s on-premise SBC or IP PBX.
Route to Smart DID (Línea Plus / AI Line): Hands the call to the stateless smart line engine (smart-lines.ring2all.internal) for autonomous call screening, interactive mini-IVR, call forwarding, and real-time voice AI.
Emergency Failover Forwarding: If the primary IP PBX returns SIP 503 Service Unavailable or fails to respond within 20 seconds, the call automatically diverts to an external PSTN mobile number.
E911 & CNAM Services: Includes self-service address provisioning for North American emergency caller location identification.

5.1 Smart DIDs: Línea Plus vs. Línea Plus + AI (Autonomous Virtual Lines)

For businesses, professionals, and remote agents who do not require a complex multi-tenant PBX with dozens of extensions, Ring2All BSS provides Smart DIDs (Autonomous Virtual Lines). These lines eliminate the need to provision dedicated subdomains, Nginx SSL certificates, or heavy PBX configurations.

┌────────────────────────────────────────────────────────────────────────┐
│               Smart Line Delivery & Fallback Architecture              │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │ Inbound PSTN Call
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                        Ring2All SBC (Kamailio 6.1)                     │
│                        Dispatches to: smart-lines.ring2all.internal    │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │ Stateless Load Balancing
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                   FreeSWITCH Smart Router (Lua Engine)                 │
│                   • Time Schedule Filter (e.g. 09:00 - 18:00)          │
│                   • Personal Assistant (Interactive Mini-IVR DTMF)     │
└───────────────────┬────────────────────────────────┬───────────────────┘
                    │                                │
    [Plan: Línea Plus + AI]                 [Plan: Línea Plus]
                    ▼                                ▼
┌───────────────────────────────────┐  ┌─────────────────────────────────┐
│     RealTime Voice AI Agent       │  │    Direct Telecom Routing       │
│  • OpenAI Natural Speech (Alloy)  │  │  • 100% Traditional Telephony   │
│  • RAG Knowledge Base Injection   │  │  • 0 Tokens / $0.00 AI Cost     │
│  • Assisted Transfer to Mobile    │  │  • Low-latency Local Bridging   │
└───────────────────┬───────────────┘  └─────────────────┬───────────────┘
                    │                                    │
                    └─────────────────┬──────────────────┘
                                      │ Call Bridge to Destination
                                      ▼
             ┌─────────────────────────────────────────────────┐
             │       Target 1: Registered Softphone (SBC)      │
             │       Target 2: Customer IP PBX (SIP URI)       │
             │       Target 3: Mobile Phone (PSTN Cellular)    │
             └────────────────────────┬────────────────────────┘
                                      │
                         Unanswered / Busy / Offline
                                      ▼
             ┌─────────────────────────────────────────────────┐
             │            Cloud Smart Voicemail Rescue         │
             │  • Audio WAV saved in BSS Cloud Portal          │
             │  • Instant Voicemail Transcription (AI)         │
             └─────────────────────────────────────────────────┘

Commercial Tiers

📦 Línea Plus (Standard Telecom):
- Included Capabilities: Personal Assistant (Mini-IVR with custom DTMF options), Follow-Me call forwarding with customizable ring timeouts (5-60s), time-of-day scheduling, and digital Cloud Voicemail (WAV audio player in client portal).
- Resource Consumption: 100% native FreeSWITCH/Kamailio processing with $0.00 OpenAI cost and 0 tokens consumed.
🤖 Línea Plus + AI (Pro AI Assistant):
- Included Capabilities: Everything in Línea Plus plus the RealTime Voice AI Agent (OpenAI), selectable neural voices, natural conversation pacing, document knowledge base injection (RAG with vector embeddings), live transfer to mobile, and automated voicemail transcription.

Terminal & Forwarding Flexibility

A Smart DID is not restricted to cell phones; subscribers can choose how they answer incoming calls:

Registered Mobile Softphone / IP Deskphone: The user registers any SIP terminal (Zoiper, Grandstream Wave, Yealink) against the Ring2All SBC. When a call arrives, the softphone rings directly.
Customer On-Premise PBX: Bridges directly via SIP URI (e.g., sip:sales@pbx.customer.com).
PSTN Cellular Phone: Rings the user’s mobile cellular number directly.
Cloud Voicemail Rescue Fallback: In all three options, if the softphone is asleep/offline, the PBX is down, or the mobile user does not answer within the configured timeout, Ring2All retrieves the call immediately and sends the caller to the Cloud Voicemail box.

5.2 Zero-Touch Softphone Connectivity (RFC 3263)

Subscribers do not need to enter an Outbound Proxy in their softphones or IP hardware. Thanks to RFC 3263 DNS discovery and Kamailio SBC routing:

SIP Domain: sip.ring2all.com
Username / Account: Provided in the SIP Trunk Connection Details card.
Password: Generated securely in the client portal.
Outbound Proxy: (Leave Blank)

6. SBC IP Whitelist & Trunk Peering Security

To prevent unauthorized call termination and toll fraud:

Carrier SBC Enforcement: Every outbound call arriving at the SBC is cross-checked against customer_ip_endpoints. If the source IP does not match the customer’s registered trunk, the call is rejected immediately with SIP/2.0 403 Forbidden.
Zero Registration Overhead: IP-authenticated trunks require no SIP REGISTER packets, eliminating CPU overhead on Telephony Server and Kamailio.
Instant In-Memory Invalidation: When a customer deletes an IP endpoint in the portal, an atomic RPC command deletes the IP from Kamailio’s permissions htable in less than 50 milliseconds.

7. Database Schema & Data Dictionary

Table: `public.dids`

CREATE TABLE public.dids (
    id                      BIGSERIAL PRIMARY KEY,
    uuid                    UUID NOT NULL DEFAULT gen_random_uuid(),
    number                  VARCHAR(32) NOT NULL UNIQUE,
    customer_id             BIGINT REFERENCES customers(id) ON DELETE SET NULL,
    country                 VARCHAR(2) NOT NULL DEFAULT 'US',
    area_code               VARCHAR(10),
    city                    VARCHAR(100),
    setup_fee               NUMERIC(10,2) NOT NULL DEFAULT 0.00,
    monthly_rate            NUMERIC(10,2) NOT NULL DEFAULT 0.00,
    channels                INTEGER NOT NULL DEFAULT 2,
    route_type              VARCHAR(30) NOT NULL DEFAULT 'sip_account',
    route_target            VARCHAR(255),
    status                  VARCHAR(20) NOT NULL DEFAULT 'available',
    assigned_at             TIMESTAMPTZ,
    e911_enabled            BOOLEAN NOT NULL DEFAULT false,
    e911_caller_name        VARCHAR(100),
    e911_address            TEXT,
    ip_endpoint_id          BIGINT REFERENCES customer_ip_endpoints(id) ON DELETE SET NULL,
    cnam_listing_enabled    BOOLEAN NOT NULL DEFAULT false,
    messaging_enabled       BOOLEAN NOT NULL DEFAULT false,
    is_porting_locked       BOOLEAN NOT NULL DEFAULT true,
    created_at              TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at              TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

Table: `public.customer_ip_endpoints`

CREATE TABLE public.customer_ip_endpoints (
    id             BIGSERIAL PRIMARY KEY,
    uuid           UUID NOT NULL DEFAULT gen_random_uuid(),
    customer_id    BIGINT NOT NULL REFERENCES customers(id) ON DELETE CASCADE,
    name           VARCHAR(100) NOT NULL DEFAULT 'Main PBX',
    ip_address     VARCHAR(45) NOT NULL,
    port           INTEGER NOT NULL DEFAULT 5060,
    transport      VARCHAR(10) NOT NULL DEFAULT 'udp',
    mask           INTEGER NOT NULL DEFAULT 32,
    description    TEXT,
    status         VARCHAR(20) NOT NULL DEFAULT 'active',
    sbc_synced     BOOLEAN NOT NULL DEFAULT false,
    created_at     TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at     TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    CONSTRAINT uq_customer_ip UNIQUE (customer_id, ip_address, port)
);

8. Diagnostic CLI & Operational Playbooks

Verify SBC Address Table Reload

To verify that a customer’s IP endpoint has been pushed to Kamailio SBC memory:

# Execute on Perimeter SBC host
kamcmd permissions.addressDump

Trace Inbound Routing on Telephony Server

# Filter ESL events for customer DID
fs_cli -x "sofia status profile external"
fs_cli -x "luarun show_did_routing.lua +13058904421"

9. Domain Glossary

DID (Direct Inward Dialing): Virtual telephone number routed over IP to a subscriber terminal.
IP Endpoint: Public IP address authorized to peer with the SBC without digest authentication.
CNAM: Caller ID Name database lookup protocol providing 15-character caller names.
E911: Enhanced 911 location identification protocol transmitting physical address data to PSAP dispatchers.