Blacklist 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. Feature Codes
8. Common Scenarios & Examples
9. Model Context Protocol (MCP) AI Integration
10. Limitations & Important Notes
11. Troubleshooting Tips
12. Glossary

---

Navigation & Access

To access the Blacklist module:

1. Log in to the Ring2All Web Portal.
2. In the left navigation sidebar, expand PBX Engine.
3. Under Incoming Call Tools, click Blacklist (/pbx/incoming-tools/blacklist).

---

Screenshots & Visual Interface

Blacklist Overview

Displays all blocked numbers and regex patterns, source (manual / phone code), block scope, and status.

Blacklist Configuration Form

Configures blocked phone number or pattern, scope (inbound/outbound/all), custom rejection destination action, and notes.

---

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

┌─────────────────────────────────────────────────────────────────┐
│                    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                  │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

---

2. Module Overview (Commercial/Business)

Business Value

Blacklist provides unwanted call protection:

Without Blacklist	With Blacklist
All calls accepted	Spam blocked
Manual rejection	Automatic blocking
No patterns	Wildcard/regex support
Admin-only	User self-service

Use Cases

1. Spam Protection

   • Block known spam numbers
   • Pattern-block area codes (555*)

2. Fraud Prevention

   • Block premium rate numbers (900*)
   • Block international prefixes

3. User Self-Service

   • Dial *32 to block last caller
   • Dial *30 to add number manually

4. Compliance

   • Block outbound to restricted countries
   • Audit trail with source tracking

Feature Highlights

Feature	Benefit
Exact Match	Block specific numbers
Wildcards	Pattern matching (555*)
Regex	Advanced pattern matching
Inbound/Outbound	Direction control
Feature Codes	User self-service
Source Tracking	Manual/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

┌─────────────────────────────────────────────────────────────────┐
│              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

Code	Action	Description
*30	Add	Enter number to block
*31	Remove	Enter number to unblock
*32	Block Last	Block 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

Field	Description	Example
Match Type	How to match	Exact/Pattern/Regex
Number / Pattern	Value to match	+15551234567 or 555*
Description	Reason for block	Spam caller
Direction	Where rule applies	Inbound/Outbound/Both
Source	How created	Manual/System/API
Destination	Optional route	Announcement
Enabled	Entry active	On/Off

Match Types

Type	Description	Example
Exact Number	Exact match only	+15551234567
Pattern	Wildcard matching	555*, *1234
Regex	Regular expression	^\+1(555|666).*

Directions

Direction	Description
Inbound Only	Block incoming calls
Outbound Only	Block outgoing calls
Both	Block both directions

Sources

Source	Description
Manual	Added via admin panel
System	Fraud detection/automatic
API	External 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:

Field	Value
Match Type	Exact Number
Value	+15551234567
Description	Telemarketer
Direction	Inbound Only

Scenario 2: Block Area Code

Entry:

Field	Value
Match Type	Pattern
Value	555*
Description	Block all 555 numbers
Direction	Both

Scenario 3: Block Premium Rate Numbers

Entry:

Field	Value
Match Type	Pattern
Value	900*
Description	Block 900 premium
Direction	Outbound Only

Scenario 4: Block Multiple Prefixes with Regex

Entry:

Field	Value
Match Type	Regex
Value	^\+1(900|976).*
Description	Block 900 and 976 prefixes
Direction	Outbound Only

7. Model Context Protocol (MCP) AI Integration

Ring2All exposes native Model Context Protocol (MCP) tools for Blacklist (Spam & Fraud Call Blocking), allowing AI security bots, SOC Copilots, and PBX administrators to inspect blocked number registries, query fraud patterns, dynamically ban malicious robocallers, and manage rejection policies programmatically with domain-level isolation.

Available MCP Tools

Tool Name	Description	Key Parameters
list_blacklist_entries	Lists all blacklisted phone numbers, prefixes, or regex patterns configured in the domain, including match type, scope, and status.	search (optional string)
get_blacklist_entry_status	Retrieves full configuration, blocking scope (inbound/outbound/all), and rejection action for a specific blocked number or pattern.	value (required string - phone number or pattern)
add_to_blacklist	Adds a caller ID, prefix, or regex pattern to the Blacklist to block unwanted robocalls. Strictly enforces entry uniqueness per domain.	value, type (number, pattern, regex), scope (inbound, outbound, all), destinationModule (hangup, busy, congestion, voicemail), description
update_blacklist_entry	Updates an existing blacklist entry’s pattern, scope, rejection destination, description, or enabled status.	value, newValue, scope, description, enabled
remove_from_blacklist	Unblocks and removes a phone number or pattern from the domain Blacklist.	value (required string)

Protection Guards & Integrity

• Uniqueness Enforcement: The PBX enforces domain-level uniqueness on blocked numbers/patterns (SELECT id FROM blacklist WHERE domain_id = ${domainId} AND value = ${value}). Duplicate blocks are cleanly prevented.
• In-Memory Dialplan Evaluation: Blacklist checks run in Telephony Server Lua prior to routing to extensions or queues, dropping abusive robocalls at zero cost without tying up IVR ports.

AI Agent Operational Examples

Auditing Blacklist Registry for a Specific Caller

{
  "tool": "get_blacklist_entry_status",
  "arguments": {
    "value": "+18005550199"
  }
}

Automatically Banning a Detected Robocaller

{
  "tool": "add_to_blacklist",
  "arguments": {
    "value": "+15559876543",
    "type": "number",
    "scope": "inbound",
    "destinationModule": "busy",
    "description": "Auto-blocked by AI Fraud Detection: 15 failed DTMF attempts"
  }
}

Recommended Natural Language Prompts

• “Is phone number ‘+18005550199’ blocked in our domain blacklist?”
• “Add ‘+15559876543’ to the blacklist and send them busy tone immediately.”
• “Show me all blocked numbers added in the last 24 hours.”
• “Unblock number ‘+15551234567’ from the blacklist.”

---

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

Pattern	Matches
555*	555, 5551234, 555anything
*1234	Any number ending in 1234
555*1234	Starting 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

---

9. Troubleshooting Tips

Common Issues

Symptom	Possible Cause	Solution
Call not blocked	Pattern mismatch	Check match type/pattern
Wrong calls blocked	Pattern too broad	Narrow pattern scope
Feature code fails	CoS restriction	Check feature permissions
Duplicate error	Already blocked	Entry exists
Invalid number	Non-numeric input	Enter digits only

Diagnostic SQL

List blacklist entries:

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:

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

Telephony Server Logs

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

---

10. Glossary

Term	Definition
Blacklist	List of blocked numbers
Pattern	Wildcard matching rule
Regex	Regular expression pattern
Scope	Direction (inbound/outbound)
Source	How entry was created
Feature Code	Dial code for user actions

---

Documentation last updated: January 2026