--- title: "SMS Opt-outs Module Documentation" description: "Documentation for SMS Opt-outs" --- ## 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. [Automatic Keyword Handling (STOP / START / HELP)](#5-automatic-keyword-handling-stop--start--help) 8. [Legal & Regulatory Compliance (TCPA & 10DLC)](#6-legal--regulatory-compliance-tcpa--10dlc) 9. [Manual Opt-out Administration](#7-manual-opt-out-administration) 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 Opt-outs module: 1. Log in to the Ring2All Web Portal (`https:///login`). 2. In the left navigation sidebar, expand **PBX Engine**. 3. Under **SMS Messaging**, click **Opt-outs** (`/pbx/sms/optouts`). 4. To manually block a number or register a customer unsubscribe request, click the **+ Add Opt-out** button at the top right of the table. --- ## Screenshots & Visual Interface ### SMS Opt-outs Overview Displays all phone numbers currently blocked from receiving outbound text messages, categorized by opt-out trigger keyword (STOP, UNSUBSCRIBE, BLOCKED), timestamp, and management actions. ![SMS Opt-outs List View](/screenshots/pbx/sms/optouts-list.png) ### Add SMS Opt-out Modal Modal dialog allowing administrators to manually add a telephone number to the opt-out suppression list with an assigned opt-out reason code. ![Add SMS Opt-out Modal](/screenshots/pbx/sms/optouts-form.png) --- ## 1. Module Overview (Technical) ### What is SMS Opt-outs? The **SMS Opt-outs** module is the automated suppression list and unsubscribe management engine for the Ring2All platform. It ensures that any recipient who texts standard opt-out keywords (such as `STOP`, `UNSUBSCRIBE`, `CANCEL`, or `QUIT`) is immediately added to an unmodifiable blocklist, preventing any further automated or human-initiated outbound text messages to that phone number across the tenant domain. ### Technical Architecture - Inbound webhooks received from telecom carriers pass through an keyword analyzer before routing to extensions or applications. - If an inbound message matches standard opt-out regex (`/^(stop|stopall|unsubscribe|cancel|end|quit)$/i`), the system: 1. Inserts the phone number into `ss_telephony.sms_optouts`. 2. Replies automatically with the mandatory carrier unsubscribe confirmation receipt. 3. Halts further routing of that message. - Whenever an outbound message is submitted via User Portal, API, or automated notifications, a mandatory query verifies that the destination phone number does not exist in `sms_optouts`. If found, the message is rejected with status `rejected`. ``` Inbound SMS from +13055550199: "STOP" │ ▼ ┌───────────────────────────────┐ │ Inbound SMS Webhook Worker │ └──────────┬────────────────────┘ │ ▼ Keyword Match: STOP │ ├─► 1. Insert (+13055550199, 'STOP') into sms_optouts ├─► 2. Send automated confirmation: "You have unsubscribed..." └─► 3. Drop inbound event from user agent inbox ``` --- ## 2. Module Overview (Commercial / Business) ### Business Value & Legal Protection - **Mandatory Carrier Compliance**: US and Canadian mobile network operators (AT&T, T-Mobile, Verizon) will permanently revoke 10DLC campaign brand registrations if carrier audits discover that a business failed to honor STOP requests. - **Lawsuit Immunity (TCPA)**: Statutory damages under the Telephone Consumer Protection Act are $500 per unauthorized message, trebled to $1,500 for willful violations. Ring2All's database-level suppression guarantees zero accidental messages. - **Consumer Trust**: Respecting customer preferences builds brand credibility and prevents carrier spam flags from degrading sender reputation. --- ## 3. Module Overview (End User / Administrator) ### Administrator Experience Administrators can: - Inspect the full suppression list, including exact date and time of the opt-out event. - Manually register customer verbal unsubscribe requests received over the phone. - Remove a phone number from the opt-out list if a customer explicitly submits an opt-in consent form. ### End User Experience When an extension agent attempts to send an SMS to an opted-out number, the User Portal displays an immediate warning banner: *"This recipient has opted out of SMS communications (STOP). Message not sent."* --- ## 4. Configuration Fields Reference | Field Name | Technical Description | User-Friendly Tooltip | Example | Notes | |------------|----------------------|----------------------|---------|-------| | **Phone Number** | E.164 string in `phone_number`. | Phone number blocked from receiving messages. | `+13055550199` | Must be in valid international format. Unique per domain. | | **Reason** | Code in `reason`. | Keyword or event that triggered the opt-out. | `STOP` | Options: `STOP`, `UNSUBSCRIBE`, `BLOCKED`, `BOUNCED`. | | **Date Added** | Timestamp in `created_at`. | Timestamp when number was added to suppression list. | `Sep 4, 2026, 11:20 AM` | Provides audit proof of compliance. | | **Added By** | User ID or system flag in `created_by`. | Source of the opt-out entry. | `System (Keyword)` / `Admin` | Distinguishes auto-detection from manual admin entries. | --- ## 5. Automatic Keyword Handling (STOP / START / HELP) Ring2All strictly adheres to the CTIA Messaging Principles and Best Practices: ### Opt-Out Keywords (Blocklist Addition) When a consumer texts any of the following keywords (case-insensitive): - `STOP` - `STOPALL` - `UNSUBSCRIBE` - `CANCEL` - `END` - `QUIT` The number is immediately added to `sms_optouts` with reason `STOP`, and the system sends the automated confirmation: > *"You have successfully been unsubscribed. You will not receive any more messages from this number. Reply START to resubscribe."* ### Opt-In Keywords (Blocklist Removal) When an opted-out recipient texts any of the following keywords: - `START` - `YES` - `UNSTOP` - `SUBSCRIBE` The record is automatically deleted from `sms_optouts`, and the system replies: > *"You have successfully been resubscribed to messages from this number. Reply STOP to unsubscribe at any time."* ### Help Keywords When a recipient texts `HELP` or `INFO`, the system returns the business support contact and terms of service without modifying opt-out status. --- ## 6. Legal & Regulatory Compliance (TCPA & 10DLC) - **Audit Preservation**: Opt-out timestamps and historical CDRs are preserved even if numbers are subsequently re-enabled. - **Universal Suppression**: Suppression is enforced across all sender DIDs within the domain. If a customer sends STOP to one company number, all numbers in the domain respect the block. - **Zero-Tolerance Enforcement**: The outbound queue rejects opted-out numbers prior to dispatching REST API calls to telecom carriers, eliminating transmission costs. --- ## 7. Manual Opt-out Administration If a customer requests unsubscription via email, web portal form, or voice call: 1. Click **+ Add Opt-out** on the Opt-outs page. 2. Enter the customer's phone number in international E.164 format (e.g., `+13055550199`). 3. Select the reason code (e.g., `UNSUBSCRIBE` or `STOP`). 4. Click **Save**. The number is instantly blocked from all outbound messaging. To unblock a customer who has provided written resubscription consent, click the **Trash** icon next to the record and confirm deletion. --- ## 8. Model Context Protocol (MCP) AI Integration The Ring2All Model Context Protocol (MCP) server provides native tools for inspecting, maintaining, and automating the SMS opt-out suppression list to guarantee strict TCPA, CTIA, and 10DLC regulatory compliance through AI agents. ### Available MCP Tools | Tool Name | Operation | Description | Target Entity | |---|---|---|---| | `list_sms_optouts` | Read | Lists all phone numbers currently on the domain SMS suppression list with unsubscription timestamps | Opt-out Registry | | `add_sms_optout` | Write | Manually adds a recipient phone number to the suppression list (blocks outbound messages domain-wide) | Opt-out Entry | | `remove_sms_optout` | Write | Removes a phone number from the suppression list upon verified customer resubscription | Opt-out Entry | ### Protection & Validation Guards - **Strict Domain Phone Uniqueness**: Enforced by constraint `uq_sms_optouts_domain_phone` and controller validation. Registering the same phone number multiple times in the domain is prevented. - **Universal Suppression Enforcement**: When an opt-out is recorded, `send_sms_message` blocks outbound messages to this number regardless of which company DID or user extension attempts to initiate the conversation. - **Reason Code Validation**: Verifies that standard compliance reasons (`STOP`, `UNSUBSCRIBE`, `MANUAL_BLOCK`, `BOUNCED`) are recorded for legal proof and auditing. - **Immediate Transmission Halt**: Removing a number from the suppression list immediately restores transmission capability; adding a number halts transmission instantly without cache latency. ### Example MCP Payloads #### 1. Adding an Opt-out Suppression Entry (`add_sms_optout`) ```json { "phoneNumber": "+13055550199", "reason": "STOP" } ``` *Response:* ```json { "success": true, "data": { "id": 48, "phone_number": "+13055550199", "reason": "STOP", "created_at": "2026-09-08T15:20:00.000Z", "message": "Phone number \"+13055550199\" added to SMS opt-out suppression list." } } ``` #### 2. Querying Active Suppressed Numbers (`list_sms_optouts`) ```json { "search": "305555" } ``` #### 3. Unblocking a Resubscribed Recipient (`remove_sms_optout`) ```json { "phoneNumber": "+13055550199" } ``` ### Copilot Natural Language Prompts - *"Show all phone numbers currently in our SMS opt-out suppression list."* - *"Check if customer phone number +13055550199 has opted out of text messaging."* - *"Add customer +13055550199 to the opt-out list with reason 'UNSUBSCRIBE' per their email request."* - *"Remove +13055550199 from the opt-out list since they sent written consent to resubscribe."* --- ## 9. Troubleshooting Tips | Symptom | Probable Cause | Corrective Action | |---------|----------------|-------------------| | **Outbound SMS fails with "RECIPIENT_OPTED_OUT"** | Recipient number is in opt-out list | Verify entry in `/pbx/sms/optouts`. Remove if customer gave valid resubscription consent. | | **Inbound "STOP" not automatically blocking** | Inbound webhook not reaching Ring2All | Check carrier webhook URL in SMS Providers and verify server firewall allows carrier IPs. | | **Customer texts START but still blocked** | START keyword not received or parsed | Manually remove the customer number from the Opt-outs table in the Web Portal. | --- ## 10. Database Schema Opt-out records are stored in table `sms_optouts` in the `ss_telephony` database: ```sql CREATE TABLE public.sms_optouts ( id SERIAL PRIMARY KEY, uuid UUID NOT NULL DEFAULT uuid_generate_v4(), domain_id INTEGER NOT NULL REFERENCES domains(id) ON DELETE CASCADE, phone_number VARCHAR(20) NOT NULL, reason VARCHAR(20) DEFAULT 'STOP', created_at TIMESTAMPTZ NOT NULL DEFAULT now(), created_by INTEGER, CONSTRAINT uq_sms_optouts_domain_phone UNIQUE (domain_id, phone_number), CONSTRAINT chk_sms_optouts_reason CHECK (reason IN ('STOP', 'UNSUBSCRIBE', 'BLOCKED', 'BOUNCED')) ); ``` --- ## 11. Glossary - **Opt-out**: Explicit request by a consumer to cease receiving automated text communications. - **Suppression List**: Database table of blocked contacts checked prior to any outbound transmission. - **CTIA**: Cellular Telecommunications and Internet Association — trade association establishing US messaging rules. - **TCPA**: Telephone Consumer Protection Act — federal regulation carrying severe penalties for unauthorized commercial texting.