--- title: "SMS Settings Module Documentation" description: "Documentation for SMS Settings" --- ## 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. [Regulatory Compliance & Quiet Hours](#5-regulatory-compliance--quiet-hours) 8. [Three-Tier Rate Limiting Architecture](#6-three-tier-rate-limiting-architecture) 9. [Country & Prefix Filtering](#7-country--prefix-filtering) 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 Settings 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 **Settings** (`/pbx/sms/settings`). 4. Modify the required parameters and click **Save Changes** on the action bar at the bottom. --- ## Screenshots & Visual Interface ### SMS Settings Configuration Form Standard 4-column inline layout organized into functional FormBoxes: Master Service Toggle, Destination Filtering, Rate Limiting Throttles, and Quiet Hours Compliance. ![SMS Settings Configuration Form](/screenshots/pbx/sms/settings-form.png) --- ## 1. Module Overview (Technical) ### What is SMS Settings? The **SMS Settings** module controls tenant-level rules, compliance policies, sending quotas, geographic permissions, and quiet hours constraints for all text messaging operations on a domain. ### Technical Architecture - Settings records are stored per domain in `ss_telephony.sms_settings`. - Before any message is queued or submitted to a provider, the SMS controller evaluates: 1. **Master Toggle (`sms_enabled`)**: Immediate rejection if false. 2. **Destination Filtering**: Verifies the country code against `allowed_countries` and ensures the number prefix is not listed in `blocked_prefixes`. 3. **Rate Limits**: Checks minute, hourly, and daily Redis counters against `rate_limit_per_minute`, `rate_limit_per_hour`, and `rate_limit_per_day`. 4. **Quiet Hours**: Compares current time in `quiet_hours_timezone` against `quiet_hours_start` and `quiet_hours_end`. If quiet hours are active, the message is delayed or rejected based on compliance rules. --- ## 2. Module Overview (Commercial / Business) ### Business Value & Compliance Protection - **Cost Protection & Budget Safeguard**: Multi-tier rate limits prevent runaway scripts, API leaks, or bot compromised endpoints from generating thousands of billable SMS in minutes. - **TCPA & Legal Penalty Avoidance**: TCPA (Telephone Consumer Protection Act) fines range from $500 to $1,500 per unauthorized message. Automated Quiet Hours enforcement ensures messages are never delivered during nighttime hours. - **Geographic Fraud Mitigation**: Restrict outbound messages to domestic territories, preventing international SMS toll fraud (IRSF) attacks. --- ## 3. Module Overview (End User / Administrator) ### Administrator Experience Administrators configure safety thresholds and compliance policies in a single centralized screen: - Toggle the entire domain's SMS engine on or off during security audits. - Adjust hourly burst limits during marketing campaigns. - Define customer timezones for legal compliance. --- ## 4. Configuration Fields Reference | Field Name | Technical Description | User-Friendly Tooltip | Example | Notes | |------------|----------------------|----------------------|---------|-------| | **SMS Enabled** | Master boolean in `sms_enabled`. | Master toggle to enable or disable SMS messaging on domain. | `true` | Must be ON for any SMS sending or receiving. | | **Allowed Countries** | Array in `allowed_countries`. | Allowed destination countries (ISO 2-letter codes). | `["US", "CA", "GB", "MX", "ES"]` | Empty array allows all non-blocked countries. | | **Blocked Prefixes** | Array in `blocked_prefixes`. | Specific phone number prefixes to block from sending. | `["900", "976"]` | Used for blocking premium rate or restricted ranges. | | **Rate Limit / Min** | Integer in `rate_limit_per_minute`. | Maximum messages allowed per minute across domain. | `60` | Prevents burst abuse and carrier throttling. | | **Rate Limit / Hour** | Integer in `rate_limit_per_hour`. | Maximum messages allowed per hour across domain. | `500` | Sustained throughput control. | | **Rate Limit / Day** | Integer in `rate_limit_per_day`. | Maximum messages allowed per 24-hour day across domain. | `5000` | Budget cap and volume ceiling. | | **Quiet Hours Enabled**| Boolean in `quiet_hours_enabled`. | Enforce TCPA quiet hours (delay/block night messages). | `false` | When enabled, no messages are sent during quiet time. | | **Quiet Hours Start** | Time string in `quiet_hours_start`. | Start time for restricted messaging period. | `22:00` | Standard 24-hour format (e.g. 10:00 PM). | | **Quiet Hours End** | Time string in `quiet_hours_end`. | End time for restricted messaging period. | `08:00` | Standard 24-hour format (e.g. 8:00 AM). | | **Timezone** | IANA timezone in `quiet_hours_timezone`. | Reference timezone for calculating quiet hours window. | `America/New_York` | Select from standard global timezones. | --- ## 5. Regulatory Compliance & Quiet Hours The TCPA and mobile network carriers strictly prohibit sending commercial or non-emergency automated messages outside of 8:00 AM to 9:00 PM in the recipient's local timezone. ### Quiet Hours Logic - **Start Time**: Typically `21:00` or `22:00` (9:00 PM or 10:00 PM). - **End Time**: Typically `08:00` (8:00 AM). - **Handling**: - Non-transactional messages submitted during quiet hours can either be held in queue until morning release or rejected with status `rejected`. - Transactional critical messages (e.g., 2FA verification codes) can bypass quiet hours if explicitly marked as high-priority OTP transactions. --- ## 6. Three-Tier Rate Limiting Architecture Ring2All implements a cascading sliding window rate-limiter in Redis: | Tier | Window Duration | Default Value | Purpose | |------|-----------------|---------------|---------| | **Per-Minute Limit** | 60 seconds | `60 msgs` | Prevents API burst flood and carrier 429 errors. | | **Per-Hour Limit** | 3,600 seconds | `500 msgs` | Normalizes campaign distributions and agent throughput. | | **Per-Day Limit** | 86,400 seconds | `5,000 msgs` | Protects telecom balance from catastrophic overspending. | If any tier's threshold is reached, subsequent requests return an error (`429 RATE_LIMIT_EXCEEDED`) and are logged in CDR audits. --- ## 7. Country & Prefix Filtering ### Whitelisting & Blacklisting - **Allowed Countries**: Specify target markets (`US`, `CA`, `GB`). Any destination number belonging to another country code is rejected before reaching telecom carriers. - **Blocked Prefixes**: Specifically prevent calling high-risk prefixes, such as international premium rate services (IPRS), adult lines (`900`), or disputed prefixes. --- ## 8. Model Context Protocol (MCP) AI Integration The Ring2All Model Context Protocol (MCP) server provides tools for reading and configuring domain-wide SMS messaging policies, rate-limiting quotas, destination filters, and TCPA nighttime quiet hours through autonomous agents or Copilots. ### Available MCP Tools | Tool Name | Operation | Description | Target Entity | |---|---|---|---| | `get_sms_settings` | Read | Retrieves domain-level SMS policies, allowed countries, blocked prefixes, volume rate limits, and quiet hours | Domain Settings | | `update_sms_settings` | Write | Updates domain SMS policies, rate limit quotas, quiet hours, and country whitelists | Domain Settings | ### Protection & Validation Guards - **Singleton Domain Integrity (`sms_settings_domain_id_key`)**: Configuration is managed at the domain level with atomic `ON CONFLICT (domain_id) DO UPDATE` semantics, ensuring no duplicate or conflicting policy rows exist. - **TCPA Regulatory Window Enforcement**: When `quietHoursEnabled` is set to `true`, `send_sms_message` evaluates current local time in `quietHoursTimezone`. Any non-urgent promotional text dispatched during the nighttime window is held or rejected with `QUIET_HOURS_ACTIVE`. - **Three-Tier Sliding Window Controls**: Outbound limits (`rateLimitPerMinute`, `rateLimitPerHour`, `rateLimitPerDay`) protect against runaway API loops and carrier 429 throttling. ### Example MCP Payloads #### 1. Retrieving Domain SMS Settings (`get_sms_settings`) ```json {} ``` *Response:* ```json { "success": true, "data": { "domainId": 1, "smsEnabled": true, "allowedCountries": ["US", "CA", "MX"], "blockedPrefixes": ["+1900"], "rateLimitPerMinute": 60, "rateLimitPerHour": 500, "rateLimitPerDay": 5000, "quietHoursEnabled": true, "quietHoursStart": "21:00:00", "quietHoursEnd": "08:00:00", "quietHoursTimezone": "America/New_York" } } ``` #### 2. Updating SMS Governance Policies (`update_sms_settings`) ```json { "smsEnabled": true, "allowedCountries": ["US", "CA"], "blockedPrefixes": ["+1900", "+1976"], "rateLimitPerMinute": 100, "quietHoursEnabled": true, "quietHoursStart": "21:00", "quietHoursEnd": "08:00", "quietHoursTimezone": "America/New_York" } ``` ### Copilot Natural Language Prompts - *"Show our current SMS messaging settings, rate limits, and quiet hours policy."* - *"Enable SMS messaging for this domain and restrict delivery to the US and Canada."* - *"Configure quiet hours between 9:00 PM and 8:00 AM Eastern Time to prevent automated messages overnight."* - *"Increase our domain hourly SMS rate limit to 1,000 messages per hour."* --- ## 9. Troubleshooting Tips | Symptom | Probable Cause | Corrective Action | |---------|----------------|-------------------| | **All outbound SMS fail with "SMS_DISABLED"** | Master toggle is turned off | In SMS Settings, turn ON the `SMS Enabled` toggle and save changes. | | **Messages fail at night with "QUIET_HOURS"** | Quiet hours restriction is active | Verify `quiet_hours_start` and `quiet_hours_timezone` configuration. | | **Error: "COUNTRY_NOT_ALLOWED"** | Recipient country not in allowed list | Add the recipient's ISO country code to `Allowed Countries`. | | **Error: "RATE_LIMIT_EXCEEDED"** | Minute, hourly, or daily quota reached | Increase the rate limit values in SMS Settings. | --- ## 10. Database Schema SMS settings are stored per domain in table `sms_settings` in `ss_telephony`: ```sql CREATE TABLE public.sms_settings ( id SERIAL PRIMARY KEY, uuid UUID NOT NULL DEFAULT uuid_generate_v4(), domain_id INTEGER NOT NULL REFERENCES domains(id) ON DELETE CASCADE, sms_enabled BOOLEAN DEFAULT FALSE, allowed_countries TEXT[], blocked_prefixes TEXT[], rate_limit_per_minute INTEGER DEFAULT 60, rate_limit_per_hour INTEGER DEFAULT 500, rate_limit_per_day INTEGER DEFAULT 5000, quiet_hours_enabled BOOLEAN DEFAULT FALSE, quiet_hours_start TIME WITHOUT TIME ZONE, quiet_hours_end TIME WITHOUT TIME ZONE, quiet_hours_timezone VARCHAR(50) DEFAULT 'UTC', created_at TIMESTAMPTZ NOT NULL DEFAULT now(), created_by INTEGER, updated_at TIMESTAMPTZ, updated_by INTEGER, CONSTRAINT sms_settings_domain_id_key UNIQUE (domain_id) ); ``` --- ## 11. Glossary - **TCPA**: Telephone Consumer Protection Act — US federal statute governing telemarketing and automated messaging. - **Quiet Hours**: Restricted nighttime period during which automated text messages must not be delivered to consumers. - **Sliding Window**: Rate limiting technique that tracks request counts over continuously moving time intervals. - **ISO 3166-1**: International standard for country codes (e.g. US, CA, MX).