---
title: "DIDs & Number Inventory Module Documentation"
description: "Documentation for DIDs & Numbers"
---

## 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 & Inbound DID Routing](#5-architectural-flow--inbound-did-routing)
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 **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.

![Telephone Number Inventory List](/screenshots/billing/telecom-providers/dids/dids-list.png)

### 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.

![Carrier On-Demand DID Provisioning](/screenshots/billing/telecom-providers/dids/dids-carrier-on-demand.png)

### 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.

![Telephone Number Configuration Modal](/screenshots/billing/telecom-providers/dids/dids-form.png)

### 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)
```bash
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)
```bash
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
```json
{
  "name": "list_did_inventory",
  "arguments": {
    "status": "active",
    "limit": 5
  }
}
```

#### Response Payload
```json
[
  {
    "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.