Freeze one failed block or false positive
Record timestamp and timezone, caller and called identity exactly as received, caller-ID presentation, trunk, DID, route, call identifier, installed FreePBX and Blacklist versions, saved rule or unknown-ID setting, configured blocked destination and final result. For a legitimate caller, preserve the approved contact path without publishing sensitive calling data.
Classify the first broken boundary: the wrong number or presentation was assumed, the call used another route or context, the hook was not generated or loaded, the match returned false, the match returned true but the destination looked like ringing, or a correct match blocked a spoofed or reassigned legitimate number. These require different owners.
Prove the ingress route and blacklist hook
Follow the call from the authenticated or trusted trunk through DID and optional CID matching into the exact loaded inbound route. Current FreePBX source inserts app-blacklist-check into generated inbound DID contexts, including a CID-priority variant. Retain the saved route, successful Apply Config, generated hook and loaded dialplan as separate evidence.
If the call entered a custom context, a different DID/CID route or a path outside the managed inbound route, correct that ownership boundary rather than adding duplicate blacklist entries. Do not edit generated ext-did or app-blacklist-check output as the durable repair.
Compare the observed identity with the evaluated key
Read the inbound channel's caller number and presentation state and compare them byte-for-byte with the stored key or the installed release's unknown-ID handling. Country prefixes, normalization, privacy presentation and display formatting are separate. A name shown on a phone does not prove which number BLACKLIST() evaluated.
Current module source recognizes several textual unavailable-number forms plus an empty value when Block Unknown is enabled, but carriers and channel drivers can represent privacy differently. Compare one working and one failing trunk before changing the policy. Never trust an unauthenticated asserted identity merely to make the match succeed.
Separate the match result from the destination outcome
Preserve the Asterisk BLACKLIST() result or equivalent loaded branch and then follow the true and false outcomes. Current module source reads the configured BLDEST and falls back to a hangup destination when blank. A true match followed by an announcement, answered blackhole, staffed destination or loop is not the same failure as a false match.
Map any destination that returns to the inbound route or another call-flow object. Confirm the caller's audible and signaling result and the final channel state without interpreting a report row or phone notification as proof that the call reached an extension.
Audit the mutation path and timeline
Correlate the entry's add or remove time with the call, Apply Config and any feature-code, GUI or API action. Sangoma's Statistics view includes calls from before an entry was added. Current source obtains active add, remove and last-caller assignments from Feature Codes and uses a stored last-caller value for that user's path; do not assume a documented default code or the intended caller was used.
Determine who or what changed the system-wide list and whether the originating context was authorized. Protect exports, API credentials, CDRs and traces. If the number may have been spoofed or reassigned, use the incident evidence to narrow or retire the rule instead of permanently labeling the number's owner.
Correct the smallest owner and replay a matrix
Correct only the demonstrated owner: trunk normalization, route selection, saved entry, unknown-ID policy, generated configuration, loaded hook, destination, feature-code assignment or authorization boundary. Use supported FreePBX controls, Apply Config once, and compare generated with loaded state before replaying.
Retest the intended blocked number, a permitted neighbor, a legitimate caller previously blocked, each relevant trunk and route, withheld identity only where approved, the configured destination and rollback. Confirm both the caller's experience and the final PBX outcome, then remove temporary logging. This workflow is documentation-derived and has not been 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.