SMS Numbers Module Documentation

Table of Contents

1. Navigation & Access
2. Screenshots & Visual Interface
3. Module Overview (Technical)
4. Module Overview (Commercial / Business)
5. Module Overview (End User / Administrator)
6. Configuration Fields Reference
7. Number Types & Capabilities
8. Extension Assignment & User Portal Access
9. E.164 Number Standardization
10. Model Context Protocol (MCP) AI Integration
11. Troubleshooting Tips
12. Database Schema
13. 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 Number Configuration Form

Configuration form for specifying the E.164 phone number, carrier provider link, number type, descriptive friendly name, and extension assignment.

---

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)

{
  "phoneNumber": "+17863643150",
  "providerId": 1,
  "numberType": "long_code",
  "friendlyName": "Main Customer Support SMS",
  "extensionId": 105,
  "enabled": true
}

Response:

{
  "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)

{
  "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:

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.