Ctrl K
ring2all.com

Blacklist Module Documentation

Table of Contents

  1. Module Overview (Technical)
  2. Module Overview (Commercial/Business)
  3. Module Overview (End User/Administrator)
  4. Configuration Fields Reference
  5. Feature Codes
  6. Common Scenarios & Examples
  7. Limitations & Important Notes
  8. Troubleshooting Tips
  9. Glossary

---

1. Module Overview (Technical)

What Is Blacklist?

Blacklist is a call blocking system that rejects calls from specified phone numbers or patterns. Entries can be managed via the admin panel or by users dialing feature codes (30, 31, 32).

Architecture

Plaintext
┌─────────────────────────────────────────────────────────────────┐
│                    Blacklist System                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Incoming Call: +15551234567                                    │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │           Blacklist Check (during routing)               │   │
│  │                                                          │   │
│  │  1. Query public.blacklist for domain                    │   │
│  │  2. Check match types:                                   │   │
│  │     - Exact number match                                 │   │
│  │     - Pattern match (wildcards)                          │   │
│  │     - Regex match                                        │   │
│  │  3. Check scope (inbound/outbound/both)                  │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ├── Match Found? ────────────────────────────────────►    │
│       │       Yes → REJECT or Route to destination             │
│       │                                                         │
│       └── No Match ────────────────────────────────────────►    │
│               Continue normal routing                           │
│                                                                 │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  User Management via Feature Codes                              │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                 blacklist.lua                            │   │
│  │                                                          │   │
│  │  *30 → Add number to blacklist                          │   │
│  │  *31 → Remove number from blacklist                     │   │
│  │  *32 → Block last caller automatically                  │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

TablePurpose
public.blacklistBlacklist entries
public.domainsDomain resolution
public.sip_extensionsExtension lookup

Key Files

FileDescription
admin/apps/web/src/modules/blacklist/Frontend module
admin/apps/web/src/i18n/en/blacklist.jsonTranslations
telephony/freeswitch/lua/features/blacklist.luaFeature code handler (30, 31, 32)
---

2. Module Overview (Commercial/Business)

Business Value

Blacklist provides unwanted call protection:

Without BlacklistWith Blacklist
All calls acceptedSpam blocked
Manual rejectionAutomatic blocking
No patternsWildcard/regex support
Admin-onlyUser self-service

Use Cases

  1. Spam Protection

- Block known spam numbers

- Pattern-block area codes (555)

  1. Fraud Prevention

- Block premium rate numbers (900)

- Block international prefixes

  1. User Self-Service

- Dial 32 to block last caller

- Dial 30 to add number manually

  1. Compliance

- Block outbound to restricted countries

- Audit trail with source tracking

Feature Highlights

FeatureBenefit
Exact MatchBlock specific numbers
WildcardsPattern matching (555)
RegexAdvanced pattern matching
Inbound/OutboundDirection control
Feature CodesUser self-service
Source TrackingManual/System/API
---

3. Module Overview (End User/Administrator)

What Can You Do?

  • Block specific phone numbers
  • Create pattern-based blocks
  • Use regex for advanced matching
  • Set direction (inbound/outbound/both)
  • Enable/disable entries
  • Use feature codes for quick blocks

Administrator Workflow

Plaintext
┌─────────────────────────────────────────────────────────────────┐
│              Creating a Blacklist Entry                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Section: Blacklist Entry Information                           │
│  ├─ Match Type: Pattern (Wildcards)                            │
│  ├─ Number / Pattern: 555*                                     │
│  ├─ Description: Block all 555 area code                       │
│  ├─ Direction: Inbound Only                                    │
│  ├─ Source: Manual                                             │
│  ├─ Destination: (optional)                                    │
│  └─ Enabled: ✓                                                 │
│                                                                 │
│  [Save] [Cancel]                                                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

End User Feature Codes

CodeActionDescription
\30AddEnter number to block
\31RemoveEnter number to unblock
\32Block LastBlock last incoming caller

Quick Tips

TIP
Quick Block: Dial 32 immediately after an unwanted call to block that number.
TIP
Wildcards: Use 555 to block all numbers starting with 555.
CAUTION
Regex Syntax: Test regex patterns carefully before saving.

---

4. Configuration Fields Reference

Entry Fields

FieldDescriptionExample
Match TypeHow to matchExact/Pattern/Regex
Number / PatternValue to match+15551234567 or 555
DescriptionReason for blockSpam caller
DirectionWhere rule appliesInbound/Outbound/Both
SourceHow createdManual/System/API
DestinationOptional routeAnnouncement
EnabledEntry activeOn/Off

Match Types

TypeDescriptionExample
Exact NumberExact match only+15551234567
PatternWildcard matching555, 1234
RegexRegular expression^\+1(555\666).

Directions

DirectionDescription
Inbound OnlyBlock incoming calls
Outbound OnlyBlock outgoing calls
BothBlock both directions

Sources

SourceDescription
ManualAdded via admin panel
SystemFraud detection/automatic
APIExternal integration
---

5. Feature Codes

30 - Add Number to Blacklist

Flow:
  1. User dials 30
  2. System prompts: "Enter the number to block"
  3. User enters digits + #
  4. System adds to blacklist
  5. Confirmation: "Number has been blocked"

31 - Remove Number from Blacklist

Flow:
  1. User dials 31
  2. System prompts: "Enter the number to unblock"
  3. User enters digits + #
  4. System removes from blacklist
  5. Confirmation: "Number has been unblocked"

32 - Block Last Caller

Flow:
  1. User dials 32 (after unwanted call)
  2. System gets last caller number
  3. System adds to blacklist automatically
  4. Confirmation: "Last caller has been blocked"

---

6. Common Scenarios & Examples

Scenario 1: Block Specific Spam Number

Entry:
FieldValue
Match TypeExact Number
Value+15551234567
DescriptionTelemarketer
DirectionInbound Only

Scenario 2: Block Area Code

Entry:
FieldValue
Match TypePattern
Value555
DescriptionBlock all 555 numbers
DirectionBoth

Scenario 3: Block Premium Rate Numbers

Entry:
FieldValue
Match TypePattern
Value900
DescriptionBlock 900 premium
DirectionOutbound Only

Scenario 4: Block Multiple Prefixes with Regex

Entry:
FieldValue
Match TypeRegex
Value^\+1(900\976).
DescriptionBlock 900 and 976 prefixes
DirectionOutbound Only
---

7. Limitations & Important Notes

Technical Notes

NOTE
Inbound Scope: User feature codes (30, 31, 32) add entries as "inbound" only.
WARNING
Regex Complexity: Complex regex may impact call processing performance.
WARNING
Source Tracking: Keep track of why numbers were blocked.

Pattern Matching Rules

PatternMatches
555555, 5551234, 555anything
1234Any number ending in 1234
5551234Starting with 555, ending 1234

Best Practices

  1. Document Entries: Add clear descriptions
  2. Review Regularly: Remove outdated blocks
  3. Test Patterns: Verify before enabling
  4. Use Right Type: Simple = Exact, Complex = Regex
  5. Monitor Sources: Track automatic blocks

---

8. Troubleshooting Tips

Common Issues

SymptomPossible CauseSolution
Call not blockedPattern mismatchCheck match type/pattern
Wrong calls blockedPattern too broadNarrow pattern scope
Feature code failsCoS restrictionCheck feature permissions
Duplicate errorAlready blockedEntry exists
Invalid numberNon-numeric inputEnter digits only

Diagnostic SQL

List blacklist entries:

Sql
SELECT id, type, value, scope, source, enabled, description
FROM public.blacklist
WHERE domain_id = [domain_id]
ORDER BY created_at DESC;

Check if number is blacklisted:

Sql
SELECT * FROM public.blacklist
WHERE domain_id = [domain_id]
  AND value = '+15551234567';

FreeSWITCH Logs

Bash
# Check blacklist operations
grep "blacklist" /var/log/freeswitch/freeswitch.log
grep "\*30\|\*31\|\*32" /var/log/freeswitch/freeswitch.log

---

9. Glossary

TermDefinition
BlacklistList of blocked numbers
PatternWildcard matching rule
RegexRegular expression pattern
ScopeDirection (inbound/outbound)
SourceHow entry was created
Feature CodeDial code for user actions
---

Lua Script Status ✅

Already Correct

ScriptStatus
features/blacklist.lua✅ Uses public.domains, public.blacklist, public.sip_extensions
No Lua fixes needed!

---

Documentation last updated: January 2026*

AI Assistant

👋 Hello! I'm your Ring2All documentation assistant. I can help you find information about configuring and using the Ring2All PBX platform.

How can I help you today?