Define known-number and unknown-ID policies separately
The Blacklist module can match a stored calling number and can separately reject calls whose caller number is unavailable. These policies have different scope and false-positive risk. Record the affected DID, one timestamped call, the business owner, the proposed key or unknown-ID rule, the blocked-call destination, a review date and a recovery contact before changing either.
Do not enable unknown-ID blocking merely because a nuisance campaign rotates numbers. Hospitals, switchboards and privacy-conscious callers can legitimately withhold presentation. Conversely, a stored number is only a match key: caller ID can be spoofed or reassigned, so an entry must not be treated as proof of a caller's identity or intent.
Preserve the exact identity FreePBX received
For one authorized call, preserve the inbound channel's caller number, caller-name and presentation state before normalization, the DID and trunk, the selected route, timestamp, call identifier and final result. Asterisk keeps the caller number and presentation as distinct party-ID fields. Compare the exact number evaluated by the PBX with the stored blacklist key; display formatting on a handset or report is not sufficient evidence.
Current FreePBX source handles the optional unknown policy by checking lowercased number text for unknown, unavailable, anonymous, private, restricted, blocked or an empty value, then checks the Asterisk blacklist result for known numbers. That implementation is version evidence, not a universal carrier token contract. Prove how each intended trunk and installed release represents privacy or missing identity.
Prove saved entry, route hook and loaded match separately
Retain the saved Blacklist row or API result, successful Apply Config, generated inbound-route hook and loaded dialplan before asserting that a rule is active. Current release/17.0 source splices app-blacklist-check into generated inbound DID contexts and uses the route's DID or DID-plus-CID form. A call on a different context, custom path or unmatched route is not repaired by repeatedly adding the same number.
At runtime, Asterisk's BLACKLIST() reads the caller ID against the blacklist AstDB family and returns a Boolean result. Preserve that result and the exact channel identity in a bounded diagnostic. Do not edit FreePBX-generated dialplan or write AstDB values directly as the durable administrative workflow.
Separate a match from the blocked-call destination
A successful match does not itself describe what the caller heard or where the channel ended. Sangoma documents a configurable destination; current module source reads BLDEST and uses app-blackhole,hangup,1 when it is blank. Record the installed module's saved destination, loaded branch, answer state, audio or signaling and final channel outcome.
Inspect the selected destination for a route back to the same inbound entry, unexpected answering, recording or billing effects, and a usable recovery path for a legitimate caller. Choose the least revealing business-appropriate response. Do not describe a hangup, announcement, staffed destination or carrier rejection as equivalent outcomes.
Treat feature codes as privileged system-wide mutations
Sangoma's older guide lists defaults for adding a number, adding the last caller and removing a number, while current source builds the active assignments from Feature Codes. Read the installed PBX's enabled codes rather than publishing *30, *31 or *32 as universal values. The current last-caller path reads the user's CALLTRACE value before adding it. Prove which caller the PBX retained and require confirmation before mutating the list.
The module describes a system-wide list. Restrict add, last-caller and remove paths to authorized internal contexts and train staff to preserve the timestamp and reason. A dialable code is not authentication, and exposing it through an inbound route or untrusted endpoint can let a caller alter policy for everyone.
Retest blocks, false positives and rollback
Test an authorized number that should match, a neighboring allowed number, withheld identity only if that policy is enabled, every relevant trunk or route, and the configured blocked destination. Recheck a legitimate caller complaint with the same route and identity form. Sangoma notes that the Statistics view includes inbound calls from before a number was blacklisted, so its count is not proof that each listed call was blocked.
For rollback, remove or disable only the demonstrated rule through supported controls, Apply Config, prove the loaded path, then replay the allowed call. Retain the owner, activation and removal times, result and next review date; protect any export as calling data. This workflow is documentation-derived and was not reproduced on a customer or laboratory PBX.
Sources & applicability
Primary references for the technical details above. Operational examples and planning checklists are VoIP.info editorial guidance.
- Sangoma Blacklist module user guide ↗
- Sangoma Blacklist GraphQL APIs ↗
- FreePBX Blacklist release/17.0 metadata ↗
- FreePBX Blacklist release/17.0 inbound-route hook ↗
- FreePBX Blacklist release/17.0 class and dialplan source ↗
- Asterisk BLACKLIST dialplan function ↗
- Asterisk CALLERID dialplan function ↗
- Asterisk party-ID information ↗
Examples require adaptation to your topology. No live PBX or hardware testing is claimed.