SMS Settings 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. Regulatory Compliance & Quiet Hours
8. Three-Tier Rate Limiting Architecture
9. Country & Prefix Filtering
10. Model Context Protocol (MCP) AI Integration
11. Troubleshooting Tips
12. Database Schema
13. Glossary

---

Navigation & Access

To access the SMS Settings 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 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.

---

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)

{}

Response:

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

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

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