---
title: "SMS Numbers Module Documentation"
description: "Documentation for SMS Numbers"
---

## Table of Contents
1. [Navigation & Access](#navigation--access)
2. [Screenshots & Visual Interface](#screenshots--visual-interface)
3. [Module Overview (Technical)](#1-module-overview-technical)
4. [Module Overview (Commercial / Business)](#2-module-overview-commercial--business)
5. [Module Overview (End User / Administrator)](#3-module-overview-end-user--administrator)
6. [Configuration Fields Reference](#4-configuration-fields-reference)
7. [Number Types & Capabilities](#5-number-types--capabilities)
8. [Extension Assignment & User Portal Access](#6-extension-assignment--user-portal-access)
9. [E.164 Number Standardization](#7-e164-number-standardization)
10. [Model Context Protocol (MCP) AI Integration](#8-model-context-protocol-mcp-ai-integration)
11. [Troubleshooting Tips](#9-troubleshooting-tips)
12. [Database Schema](#10-database-schema)
13. [Glossary](#11-glossary)

---

## Navigation & Access

To access the SMS Numbers module:
1. Log in to the Ring2All Web Portal (`https://<domain-or-ip>/login`).
2. In the left navigation sidebar, expand **PBX Engine**.
3. Under **SMS Messaging**, click **Numbers** (`/pbx/sms/numbers`).
4. To add a new SMS phone number, click the **+ New Number** button (`/pbx/sms/numbers/new`).
5. To edit an existing phone number or change carrier assignment, click the edit action icon in the table (`/pbx/sms/numbers/:id`).

---

## Screenshots & Visual Interface

### SMS Numbers Overview
Lists all SMS-enabled DID phone numbers, assigned carrier provider, number category (long code / toll-free), linked extension, and active status.
![SMS Numbers List View](/screenshots/pbx/sms/numbers-list.png)

### SMS Number Configuration Form
Configuration form for specifying the E.164 phone number, carrier provider link, number type, descriptive friendly name, and extension assignment.
![SMS Number Configuration Form](/screenshots/pbx/sms/numbers-form.png)

---

## 1. Module Overview (Technical)

### What is an SMS Number?
An **SMS Number** represents an individual Direct Inward Dialing (DID) telephone number provisioned on an SMS carrier and associated with a tenant domain in Ring2All. It serves as:
- The **Caller ID (From Number)** for outbound text messages generated by PBX extensions, automated notifications, or IVR interactions.
- The **Destination (To Number)** for inbound text messages routed to specific extensions, ring groups, or AI chatbots.

### Technical Routing Lifecycle
1. When an outbound SMS is requested by an extension in the Web Portal, the system retrieves the `sms_number_id` associated with that user's extension.
2. The number record references a parent `provider_id` in `sms_providers`.
3. The message is transmitted via that carrier's API using the phone number in international E.164 format.
4. For inbound messages, the carrier webhook delivers the destination number. The system performs a lookup against `sms_numbers` within the domain to route the message to the corresponding extension or queue.

---

## 2. Module Overview (Commercial / Business)

### Business Value & ROI
- **Unified Voice & Texting Identity**: Customers can call or text the exact same corporate number, providing a seamless multi-channel customer experience.
- **Toll-Free Texting**: Enable nationwide customer support on 1-800, 1-888, or 1-877 numbers with high delivery trust and carrier verification.
- **Personalized Agent Lines**: Assign dedicated business SMS numbers to sales representatives and account managers, preventing confidential communications from taking place on personal mobile devices.
- **Brand Protection & Privacy**: Protect corporate communication records with central archiving and compliance logging.

---

## 3. Module Overview (End User / Administrator)

### Administrator Experience
Administrators map purchased DIDs to carrier accounts and assign them to PBX extensions.
- Enable or disable messaging capability per phone number without affecting voice service.
- Verify number registration types (10DLC Long Code vs. Toll-Free).

### End User Experience
When a user has an SMS Number assigned to their extension:
- The **SMS** tab appears in their User Portal dashboard.
- Users can compose new SMS messages, read incoming replies, and maintain conversational threads in real time.

---

## 4. Configuration Fields Reference

| Field Name | Technical Description | User-Friendly Tooltip | Example | Notes |
|------------|----------------------|----------------------|---------|-------|
| **Phone Number** | E.164 string in `phone_number`. | The telephone number formatted in international standard. | `+17863643150` | Must begin with `+` and country code. Unique per domain. |
| **Provider** | Foreign key in `provider_id`. | Select which SMS carrier manages this number. | `Telnyx US Carrier` | References active provider in `sms_providers`. |
| **Number Type** | Category in `number_type`. | Classification of the phone number. | `long_code` | Options: `long_code`, `toll_free`, `short_code`, `alphanumeric`. |
| **Friendly Name** | Display label in `friendly_name`. | Descriptive alias for internal identification. | `Main Support Direct SMS` | Helpful for identifying business purpose. |
| **Assigned Extension** | Reference to `sip_extensions.id`. | PBX extension allowed to send/receive with this number. | `2000 - Tech Support` | Optional; links number to User Portal inbox. |
| **Enabled** | Boolean toggle in `enabled`. | Enable or disable SMS routing on this number. | `true` | Inactive numbers reject outgoing and incoming texts. |

---

## 5. Number Types & Capabilities

| Number Type | Format Example | Throughput (MPS) | Typical Use Case | Compliance Requirements |
|-------------|----------------|------------------|------------------|-------------------------|
| **Long Code (10DLC)** | `+17863643150` | 1 - 30 MPS | 1-on-1 customer chat, sales, account updates | Requires 10DLC Brand & Campaign registration in US. |
| **Toll-Free (TFN)** | `+18005550190` | 3 - 50 MPS | Customer support, enterprise hotlines, OTP codes | Requires Toll-Free Messaging Verification with TCR/carrier. |
| **Short Code** | `24242` | 100+ MPS | High-volume marketing, mass critical alerts | Dedicated carrier approval, premium monthly carrier fees. |
| **Alphanumeric** | `RING2ALL` | 10 - 100 MPS | One-way international notifications, brand alerts | Supported in select countries (UK, EU, Australia). Not US/CA. |

---

## 6. Extension Assignment & User Portal Access

Linking an SMS Number to an extension provides end-user functionality:
1. Open **PBX Engine → Extensions** and select the target extension.
2. Under the **General** configuration section, assign the **SMS Number**.
3. Save the extension.
4. When the user logs in to the User Portal, the **Messages** navigation icon is unlocked.
5. Inbound texts sent to this DID appear instantly in the user's portal inbox via real-time WebSocket notifications.

---

## 7. E.164 Number Standardization

All numbers stored in Ring2All must strictly follow ITU-T E.164 international numbering:
- **Prefix**: Always starts with `+`.
- **Country Code**: 1 to 3 digits (e.g., `1` for US/Canada, `44` for UK, `52` for Mexico).
- **Subscriber Number**: Up to 12 digits, excluding leading national trunk prefixes (e.g., omitting initial `0`).
- **Punctuation**: No spaces, hyphens, brackets, or dots.

```
+  [Country Code]  [National Destination Code / Area Code]  [Subscriber Number]
+        1                          786                            3643150
```

---

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

The Ring2All Model Context Protocol (MCP) server provides native tools for querying, provisioning, modifying, and safely releasing SMS-enabled phone numbers (DIDs) via conversational AI. Agents can verify carrier bindings, assign numbers to user extensions, and enforce strict domain numbering uniqueness.

### Available MCP Tools

| Tool Name | Operation | Description | Target Entity |
|---|---|---|---|
| `list_sms_numbers` | Read | Lists all SMS-enabled DIDs for the domain with provider binding, assigned extension, and active status | Number Inventory |
| `get_sms_number` | Read | Retrieves detailed configuration and extension assignment of a specific SMS number | Single Phone Number |
| `create_sms_number` | Write | Provisions a new SMS DID (strictly validates E.164 format and uniqueness in the domain) | New SMS DID |
| `update_sms_number` | Write | Modifies phone number label, carrier assignment, linked extension, or status (validates domain uniqueness) | Existing SMS DID |
| `delete_sms_number` | Write | Removes an SMS DID from the domain (guarded against active extension bindings) | Inactive SMS DID |

### Protection & Validation Guards

- **Strict Domain Number Uniqueness**: When provisioning (`create_sms_number`) or modifying numbers (`update_sms_number`), the system strictly checks for existing duplicate phone numbers in the domain (`uq_sms_numbers_domain_phone`). Re-registering the same telephone number within the same tenant domain is prohibited.
- **Dependency & Deletion Guard (`assertCanDeleteSmsNumber`)**: An SMS number cannot be deleted if it is actively linked to a SIP extension. The administrator or agent must explicitly unbind the extension before deletion is permitted.
- **E.164 Format Enforcement**: All input phone numbers are validated against the international ITU-T E.164 regex pattern (`^\+[1-9]\d{1,14}$`).

### Example MCP Payloads

#### 1. Provisioning a New SMS DID (`create_sms_number`)
```json
{
  "phoneNumber": "+17863643150",
  "providerId": 1,
  "numberType": "long_code",
  "friendlyName": "Main Customer Support SMS",
  "extensionId": 105,
  "enabled": true
}
```
*Response:*
```json
{
  "success": true,
  "data": {
    "id": 12,
    "phone_number": "+17863643150",
    "friendly_name": "Main Customer Support SMS",
    "number_type": "long_code",
    "enabled": true,
    "message": "SMS phone number \"+17863643150\" provisioned successfully."
  }
}
```

#### 2. Reassigning an SMS DID to Another Extension (`update_sms_number`)
```json
{
  "identifier": "+17863643150",
  "extensionId": 200,
  "friendlyName": "Tier 2 Escalations SMS"
}
```

### Copilot Natural Language Prompts

- *"Show all active SMS numbers in our domain and indicate which extension each is linked to."*
- *"Check the configuration and carrier details for phone number +17863643150."*
- *"Assign phone number +17863643150 to extension 200 (Support Queue)."*
- *"Provision a new Toll-Free SMS number +18005550190 under carrier Telnyx with friendly name 'Toll-Free Support'."*
- *"Verify if phone number +17863643150 can be safely deleted or if an extension is currently assigned to it."*

---

## 9. Troubleshooting Tips

| Symptom | Probable Cause | Corrective Action |
|---------|----------------|-------------------|
| **Outbound SMS Fails: "Number not found"** | Number not provisioned on carrier | Verify that the number exists and is SMS-enabled in the provider portal. |
| **Inbound SMS Not Arriving** | Number not bound to Messaging Profile | In the carrier console (Telnyx/Twilio), verify the number is assigned to the Ring2All webhook profile. |
| **Extension Cannot Send SMS** | Number disabled or unassigned | Verify `enabled` toggle is active and the extension is linked to the number. |
| **Duplicate Number Error** | Number already registered in domain | Ensure the same number is not registered twice under the same domain. |

---

## 10. Database Schema

SMS numbers are stored in table `sms_numbers` in the `ss_telephony` database:

```sql
CREATE TABLE public.sms_numbers (
    id            SERIAL PRIMARY KEY,
    uuid          UUID NOT NULL DEFAULT uuid_generate_v4(),
    domain_id     INTEGER NOT NULL REFERENCES domains(id) ON DELETE CASCADE,
    provider_id   INTEGER NOT NULL REFERENCES sms_providers(id) ON DELETE CASCADE,
    phone_number  VARCHAR(20) NOT NULL,
    number_type   VARCHAR(20) DEFAULT 'long_code',
    extension_id  INTEGER REFERENCES sip_extensions(id),
    friendly_name VARCHAR(100),
    enabled       BOOLEAN DEFAULT TRUE,
    created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
    created_by    INTEGER,
    updated_at    TIMESTAMPTZ,
    updated_by    INTEGER,
    CONSTRAINT uq_sms_numbers_domain_phone UNIQUE (domain_id, phone_number),
    CONSTRAINT chk_sms_numbers_type CHECK (number_type IN ('long_code', 'toll_free', 'short_code', 'alphanumeric'))
);
```

---

## 11. Glossary

- **DID (Direct Inward Dialing)**: A standard telephone number allocated to a business PBX.
- **E.164**: The international public telecommunication numbering plan standard.
- **TFN**: Toll-Free Number (e.g., 800, 888, 877, 866).
- **10DLC**: 10-Digit Long Code commercial messaging system.