Inbound Blacklist

The Inbound Blacklist module blocks unwanted inbound calls using pattern matching. Rules can apply globally or to specific DIDs.

Purpose

Use this module to:

• Block spam, robocalls, or unwanted callers
• Match caller IDs by exact number, prefix, or wildcard
• Choose how blocked calls are handled (drop, reject, or torment)
• Review blocked call logs and statistics

Match Types

Type	Behavior	Example
Exact	Exact match	+14155551234
Prefix	Starts with pattern	+1415
Wildcard	fnmatch pattern with * and ?	+1*555*

Rejection Strategies

Strategy	Behavior
Drop	Silent hangup
Reject	Play a rejection message, then hang up
Torment	Put the caller into a conference with hold music for a configurable timeout

Scope

Rules can be:

• Global: Apply to all inbound calls for the organization
• Per-DID: Apply only to calls arriving on selected DIDs

Permissions

Action	Owner	PBX Admin	PBX User	Reporter
View blacklist	Yes	Yes	Yes	Yes
Create blacklist entries	Yes	Yes	No	No
Update blacklist entries	Yes	Yes	No	No
Delete blacklist entries	Yes	Yes	No	No

UI Workflow

Add a Blacklist Entry

1. Navigate to Inbound Blacklist in the sidebar
2. Click Add Rule
3. Enter the caller ID pattern
4. Select the match type
5. Choose the rejection strategy
6. Select whether the rule is global or apply it to specific DIDs
7. Save

Review Blocked Calls

1. Open the Blocked Calls tab
2. View the caller ID, called number, rejection strategy, and timestamp
3. Use this data to refine your rules

View Statistics

The Statistics endpoint returns cached aggregate metrics, such as total blocked calls and breakdowns by strategy.

Key Data Fields

inbound_blacklists Table

Column	Type	Notes
id	bigint	Primary key
organization_id	FK	Tenant scope
match_type	enum	exact, prefix, wildcard
caller_id_pattern	string	Pattern to match
is_global	boolean	Apply to all DIDs
rejection_strategy	enum	drop, reject, torment
torment_room_prefix	string
torment_music_timeout	integer
status	enum	active, inactive
blocked_count	integer

blocked_call_logs Table

Column	Type	Notes
organization_id	FK	Tenant scope
inbound_blacklist_id	FK	Matching rule
did_number_id	FK	Target DID
caller_id	string
called_number	string
call_sid	string
session_id	string
rejection_strategy	enum
blocked_at	datetime

Related API Endpoints

Method	Endpoint	Purpose
GET/POST/PUT/DELETE	/v1/inbound-blacklist[/{inboundBlacklist}]	Standard CRUD
PATCH	/v1/inbound-blacklist/{inboundBlacklist}/toggle-status	Toggle active status
GET	/v1/inbound-blacklist/blocked-calls	Blocked call logs
GET	/v1/inbound-blacklist/statistics	Aggregate statistics

See the OPBX REST API reference for full schemas.

Related Modules

• Phone Numbers — Per-DID blacklist rules
• Voice Routing Engine — Blacklist is checked before routing