---
title: "Blacklist Module Documentation"
description: "Documentation for Blacklist"
---

## 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-commercialbusiness)
5. [Module Overview (End User/Administrator)](#3-module-overview-end-useradministrator)
6. [Configuration Fields Reference](#4-configuration-fields-reference)
7. [Feature Codes](#5-feature-codes)
8. [Common Scenarios & Examples](#6-common-scenarios--examples)
9. [Model Context Protocol (MCP) AI Integration](#7-model-context-protocol-mcp-ai-integration)
10. [Limitations & Important Notes](#8-limitations--important-notes)
11. [Troubleshooting Tips](#9-troubleshooting-tips)
12. [Glossary](#10-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 List View](/screenshots/pbx/incoming-tools/blacklist-list.png)

### Blacklist Configuration Form
Configures blocked phone number or pattern, scope (inbound/outbound/all), custom rejection destination action, and notes.
![Blacklist Configuration Form](/screenshots/pbx/incoming-tools/blacklist-form.png)

---

## 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
```json
{
  "tool": "get_blacklist_entry_status",
  "arguments": {
    "value": "+18005550199"
  }
}
```

#### Automatically Banning a Detected Robocaller
```json
{
  "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:**
```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';
```

### Telephony Server Logs

```bash
# 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*