DIDs & Number Inventory Module Documentation

Table of Contents

1. Module Overview (Technical)
2. Module Overview (Commercial & Business Value)
3. 🎯 User Roles & Key Capabilities
4. Visual Interface & Form Structure
5. Architectural Flow & Inbound DID Routing
6. Common Scenarios & Operational Playbooks
7. Troubleshooting & Diagnostic Commands
8. Model Context Protocol (MCP) AI Integration
9. Glossary

---

1. Module Overview (Technical)

The DIDs & Number Inventory module (public.dids and didsPage.tsx) manages the global lifecycle, commercial pricing, routing targets, and regulatory services of E.164 telephone numbers within Ring2All Billing. It handles inventory concessions, automated on-demand carrier ordering, customer assignment, emergency services (E911), caller ID listing (CNAM), call forwarding rules, and anti-spam screening.

Data Architecture & Relational Mapping

• E.164 Canonical Formatting: All telephone numbers are stored in strict international E.164 standard (e.g. +13055550199).
• Inbound Route Destinations (route_type):
  • sip_account: Dispatches directly to an enterprise SIP trunk configured in Ring2All SBC.
  • ring2all_pbx: Routes to an extension, ring group, or IVR within a customer’s Ring2All PBX tenant.
  • external_pstn: Immediate call forwarding to an external telephone number.
• Perimeter Call Forwarding & Failover: Executes conditional call forwarding (always or on_failover) directly within the Kamailio SBC layer before reaching customer endpoints, ensuring zero downtime if customer PBX servers go offline.
• Zero-Cost On-Net Optimization: When a DID forwards to another internal DID hosted on the platform, Ring2All SBC identifies the destination in local memory and loops the call internally at $0 upstream transit cost.

 ┌────────────────────────────────────────────────────────────────────────┐
 │                      Telephone Number (public.dids)                    │
 │  • number: VARCHAR(32) (e.g. "+13055550199")                           │
 │  • customer_id: FK -> public.customers (Assigned Subscriber)          │
 │  • route_type: 'sip_account' | 'ring2all_pbx' | 'external_pstn'       │
 │  • route_target: VARCHAR(255) (e.g. "100" or "Trunk-Acme-HQ")         │
 │  • forward_mode: 'disabled' | 'always' | 'failover'                    │
 │  • vendor_monthly_cost: $0.75 | monthly_rate: $2.50 (Margin: 70%)     │
 └───────────────────────────────────┬────────────────────────────────────┘
                                     │
           ┌─────────────────────────┴─────────────────────────┐
           │                                                   │
           ▼ Inbound Signalling Delivery                       ▼ Emergency & Regulatory
 ┌───────────────────────────────────┐               ┌───────────────────────────────────┐
 │     Ring2All SBC / PBX Core       │               │     Regulatory & Security APIs    │
 │  • Kamailio `drouting` / Alias    │               │  • E911 Emergency Master Address  │
 │  • RTPEngine Media Anchoring      │               │  • CNAM Inbound & Outbound Lookup │
 │  • Anti-Spam / STIR/SHAKEN Filter │               │  • T.38 Virtual Fax Gateway Email │
 └───────────────────────────────────┘               └───────────────────────────────────┘

---

2. Module Overview (Commercial & Business Value)

• High-Margin Value-Added Services (VAS): Enhances base DID revenue by offering premium add-on services: E911 emergency registration ($1.50/mo), CNAM caller name listing ($1.00/mo), T.38 virtual fax to email ($3.00/mo), and automated anti-spam call screening.
• Instant Customer Fulfillment: Carrier on-demand API integration allows enterprise customers to select, purchase, and begin using local or toll-free numbers within seconds directly from the portal.
• Zero-Waste Inventory Lifecycle: Provides clear operational separation between “Releasing DID from customer” (returns number to available pool for reassignment) and “Deleting DID” (cancels number on upstream carrier to stop recurring wholesale costs).

---

3. 🎯 User Roles & Key Capabilities

User Role	Key Permissions	Core Responsibilities & Workflows
Super Administrator	Full Control & Number Provisioning	Approves bulk DID imports, sets default retail prices and setup fees, and manages carrier concessions.
Telecom Provisioning Specialist	Search, Order & Assign DIDs	Queries carrier APIs for available vanity/local numbers, executes purchase orders, and assigns DIDs to customer accounts.
NOC Support Engineer	Route & Forwarding Configuration	Configures failover routing targets, investigates inbound call completion failures, and updates E911 dispatch addresses.
Client Portal Customer	Self-Service Management	Orders new DIDs from the plan store, configures call forwarding destinations, and manages CNAM display names.

---

4. Visual Interface & Form Structure

4.1 Telephone Number Inventory (List View)

The Telephone Number Inventory list displays all active, assigned, and available numbers with country flags, assigned customer badges, inbound routing targets, and action tools.

4.2 Carrier On-Demand Search & Provisioning (Tab View)

The Carrier On-Demand view queries upstream carrier APIs (e.g. Telnyx) in real time by country, phone type (local or toll-free), area code, or city, allowing immediate one-click purchasing.

4.3 Telephone Number Configuration & Range Generator (Modal View)

The Telephone Number Configuration modal enables manual DID additions, sequential range generation, wholesale cost versus retail price margin calculations, and granular routing parameters.

4.4 Form Parameter Reference

Parameter Name	Data Type	Required	Default Value	Description & Business Rules
E.164 Telephone Number	String	Yes	—	Complete international format number starting with + and country code (e.g. +13055550199).
Country ISO-2	String	Yes	US	2-letter country code governing regulatory dialing and emergency service routing.
Area Code / City	String	No	—	Geographic NPA and metropolitan region for caller ID display and directory listing.
Inventory Sourcing	Enum	Yes	carrier_api	carrier_api (Telnyx/Twilio), inventory_concession (Wholesale block), or manual.
Vendor Wholesale Cost	Numeric	Yes	0.75	Monthly wholesale recurring cost charged by the upstream carrier.
Retail Monthly Rate	Numeric	Yes	2.50	Monthly recurring charge invoiced to the assigned customer.
One-Off Setup Fee	Numeric	Yes	1.00	Non-recurring activation fee invoiced on initial assignment.
Concurrent Channels	Integer	Yes	2	Number of simultaneous inbound calls permitted on this specific DID.
Inbound Route Target	String	No	—	Destination for answered calls (e.g. Extension 100, IVR Main-Menu, or SIP Trunk).
Call Forwarding Mode	Enum	Yes	disabled	disabled, always (permanent divert), or failover (diverts if PBX is offline/unregistered).
Forwarding Target	String	No	—	Destination E.164 phone number or SIP URI for diverted calls.
E911 Emergency Service	Boolean	Yes	false	Enables legal emergency dispatch capabilities with a registered physical street address.
Anti-Spam Screening	Enum	Yes	disabled	Automated STIR/SHAKEN verification and robocall blocking in Ring2All SBC.

---

5. Architectural Flow & Inbound DID Routing

          Inbound Call Arrives at SBC (+13055550199)
                              │
                              ▼
 ┌────────────────────────────────────────────────────────┐
 │           Ring2All SBC Memory Lookup (htable)          │
 └────────────────────────────┬───────────────────────────┘
                              │
               ┌──────────────┴──────────────┐
               ▼                             ▼
       Customer Online?               Customer Offline?
               │                             │
               ▼                             ▼
   Forward to Target PBX / Trunk    Check Failover Forwarding
     (SIP INVITE -> Dest URI)       (e.g. Divert to Cell Phone)

---

6. Common Scenarios & Operational Playbooks

Scenario A: Provisioning an On-Demand DID from Telnyx

1. Navigate to Telecom Providers → DIDs & Numbers and select the Carrier On-Demand tab.
2. Select Country United States, Type Local, and enter Area Code 305.
3. Click Search Available Numbers. The table renders available numbers directly from Telnyx.
4. Select the desired number and click Order Number. The system executes the carrier order, records the DID in the inventory database, and redirects to assignment.

Scenario B: Configuring Emergency Failover to a Mobile Number

1. In the DIDs inventory, locate the customer’s main corporate phone number and click Edit.
2. Open the Routing & Forwarding tab.
3. Under Call Forwarding Mode, select Failover (On Endpoint Offline).
4. Enter Forwarding Target: +17865551234 (CEO mobile).
5. Set Timeout Seconds: 20.
6. Click Save Changes. If the customer’s on-premise IP-PBX loses Internet connectivity, incoming calls are automatically diverted to the mobile phone within 20 seconds.

---

7. Troubleshooting & Diagnostic Commands

Querying Assigned DIDs & Sourcing Margins (PostgreSQL)

su - postgres -c "psql -d ss_billing -c \"
SELECT d.id, d.number, d.country, d.status,
       c.company_name AS customer,
       d.vendor_monthly_cost, d.monthly_rate,
       (d.monthly_rate - d.vendor_monthly_cost) AS gross_margin
FROM dids d
LEFT JOIN customers c ON c.id = d.customer_id
ORDER BY d.id ASC;\""

Checking Real-time SBC DID Memory Table (Ring2All SBC Server)

ssh root@192.168.10.32 "kamcmd htable.dump did_routing"

---

8. Model Context Protocol (MCP) AI Integration

The DIDs & Number Inventory module connects directly to the Ring2All BSS MCP Server, empowering AI assistants and carrier operations engineers to query available numbers, audit assigned inventory, and verify customer routing configurations.

Available MCP Tools

Tool Name	Access Role	Description & Primary Function	Example Arguments
list_did_inventory	Telecom & Carrier Engineer / Billing Operations	Lists assigned and unassigned DIDs with routing destination, customer ownership, monthly price, and carrier.	{"customerId": 1, "status": "active"}

Sample MCP Tool Execution: list_did_inventory

Request Payload

{
  "name": "list_did_inventory",
  "arguments": {
    "status": "active",
    "limit": 5
  }
}

Response Payload

[
  {
    "id": 1,
    "number": "+13055550199",
    "country": "US",
    "status": "active",
    "customerId": 1,
    "customerName": "Cuadra Telecom Corp",
    "monthlyRate": 2.50,
    "vendorCost": 0.50,
    "routeType": "ring2all_pbx"
  },
  {
    "id": 2,
    "number": "+17865550123",
    "country": "US",
    "status": "active",
    "customerId": 1,
    "customerName": "Cuadra Telecom Corp",
    "monthlyRate": 2.50,
    "vendorCost": 0.50,
    "routeType": "sip_account"
  }
]

Conversational AI Prompts for Copilot

• “List all active DIDs assigned to customer ID 1.”
• “Show all unassigned DIDs available in our United States inventory pool.”
• “What is the monthly recurring revenue generated by our assigned DIDs?”

---

9. Glossary

• DID (Direct Inward Dialing): A standard telephone number assigned to an enterprise PBX or trunk to reach internal extensions directly.
• E.164: International public telecommunication numbering plan establishing the universal format +[CountryCode][AreaCode][SubscriberNumber].
• CNAM (Caller ID Name): Telephony database service providing the text name associated with a calling phone number.
• E911: Enhanced 911 emergency dispatch system delivering caller location data to Public Safety Answering Points (PSAPs).
• Model Context Protocol (MCP): Open protocol standard that enables secure, controlled integration between Large Language Models and external tools, databases, and telecom rating engines.