SMS Phone Number Exception/Blocking System

This document describes how to manage SMS phone number exceptions in the HungryHub system.

Overview

The system allows administrators to maintain a list of phone numbers that should NOT receive SMS notifications. This is useful for:

• Numbers that have requested to be excluded
• Fake/test numbers causing issues
• Numbers belonging to executives or sensitive contacts
• Numbers flagged for abuse

How It Works

1. AdminSetting Storage: Blocked phone numbers are stored in AdminSetting.sms_blocked_phone_numbers field
2. Automatic Filtering: The SmsWorker automatically filters out blocked numbers before sending SMS
3. Logging: All blocked SMS attempts are logged with details for auditing

Management via Rails Console

Adding Phone Numbers

# Add a single phone number
SmsBlockedPhoneManager.add_blocked_number('+66 800000003')

# Add multiple phone numbers
SmsBlockedPhoneManager.add_blocked_numbers([
  '+66 800000003',
  '+66 800000004',
  '+66 800000005'
])

Removing Phone Numbers

# Remove a single phone number
SmsBlockedPhoneManager.remove_blocked_number('+66 800000003')

# Remove multiple phone numbers
SmsBlockedPhoneManager.remove_blocked_numbers([
  '+66 800000003',
  '+66 800000004'
])

Viewing Blocked Numbers

# List all currently blocked phone numbers
SmsBlockedPhoneManager.list_blocked_numbers
# => ["+66 800000003", "+66 800000004", ...]

# Check if a specific number is blocked
SmsBlockedPhoneManager.blocked?('+66 800000003')
# => true

Clearing All Blocked Numbers

# Remove all exceptions
SmsBlockedPhoneManager.clear_all_blocked_numbers

Adding via AdminSetting Panel

If you have an admin panel for AdminSetting, you can also:

1. Navigate to AdminSetting configuration
2. Find the sms_blocked_phone_numbers field
3. Enter phone numbers separated by commas, e.g.: +66 800000003, +66 800000004, +66 800000005
4. Save the changes

Logging & Auditing

All SMS operations involving blocked numbers are logged with:

• Timestamp
• Reservation ID (if applicable)
• Phone numbers that were skipped
• Count of blocked numbers encountered

Example log:

[INFO] Skipped sending SMS to blocked phone numbers - 
  reservation_id: 12345, 
  skipped_phone_numbers: ["+66 800000003"], 
  blocked_count: 1

Use Case: Urgent Request

When you receive an urgent request like:

“Please exclude +66 800000003 from SMS notifications”

Execute in Rails console:

SmsBlockedPhoneManager.add_blocked_number('+66 800000003')

The system will:

1. ✅ Add the number to the AdminSetting storage
2. ✅ Log the action
3. ✅ Automatically skip this number on all future SMS sends
4. ✅ No code deployment needed

Implementation Details

Storage Format

Blocked phone numbers are stored as a comma-separated string in AdminSetting.sms_blocked_phone_numbers:

+66 800000003, +66 800000004, +66 800000005

Normalization

Phone numbers are:

• Trimmed of whitespace
• Stored in their original format (E164 or local format)
• Compared as exact string matches

Performance

• Blocking list is fetched from AdminSetting on each SMS send (allows real-time updates)
• Simple string filtering has negligible performance impact
• All operations are logged for audit trail

Error Handling

• Invalid/blank phone numbers are silently ignored
• If all numbers in a batch are blocked, the SMS operation returns early
• Failed blocks don’t prevent SMS sending, they just filter numbers