Emergency server help: get in touch

FreePBX Blacklist and Caller ID Blocking: Stop Junk Calls (Tested)

How the FreePBX 17 Blacklist and caller ID inbound routes really behave: exact matching, anonymous calls, answered vs rejected blocks, and testing with SIPp.

Published Updated 11 min read

Short answer: In FreePBX 17, use the FreePBX Blacklist (Admin > Blacklist) for single numbers, and turn on Block Unknown/Blocked Caller ID for anonymous calls. The Blacklist only matches the exact caller ID string your trunk delivers (2125550199 is not +12125550199), and it answers blocked calls before hanging up. To block a whole range, such as one prefix, add an inbound route with a caller ID pattern like _1800NXXXXXX and the destination Terminate Call (on the DID, or for any DID with CID Priority Route ticked); in our test that rejected the call with 603 Decline without answering it. (Reviewed October 2026.)

Robocalls and repeat junk callers are one of the most common FreePBX forum questions, and the two built-in tools behave differently in ways the GUI does not show. We sent inbound calls with chosen caller IDs into a FreePBX 17 lab server with SIPp, posing as the SIP trunk, and recorded what each caller received and where Asterisk sent the call.

Which tool to use

GoalUseMatchingWhat the caller gets
Block one known numberBlacklistExact caller ID number or caller ID nameCall answered, then hung up (200 OK, then BYE)
Block anonymous, private or withheld callsBlacklist setting Block Unknown/Blocked Caller IDCaller ID number empty or unknown, unavailable, anonymous, private, restricted, blocked (any case)Answered, then hung up
Block a prefix or rangeInbound route with a caller ID patternAsterisk pattern, e.g. _1800NXXXXXXRejected without answer (603 Decline with Terminate Call: Hangup)

The Blacklist applies to every inbound route; an inbound route with a caller ID only applies to the DID it is set on. For ranges on several DIDs, add one route per DID, or leave the DID empty (“any DID”) and tick CID Priority Route on that route. Without that option, our DID route won and calls from the blocked range still went to the extension (details below).

Block a single number with the FreePBX Blacklist

Open Admin > Blacklist, click Blacklist Number, enter it in Number/CallerID, add a description and save. The module writes the entry to the Asterisk database straight away; no Apply Config is needed for numbers. The same entry from the command line, useful for scripts:

asterisk -rx 'database put blacklist 2125550199 "repeat junk caller"'
asterisk -rx "database show blacklist"
asterisk -rx "database del blacklist 2125550199"   # remove it again

Results from our lab with 2125550199 on the list:

Caller ID number sent by the trunkResult
2125550199Blocked: answered, then hung up
12125550199Not blocked: reached the route to extension 1001
+12125550199Not blocked: reached the route to extension 1001
3105550111 (not on the list)Not blocked

The match is a plain string comparison. Before adding numbers, look at how your trunk presents caller ID: place a test call from a mobile and check the CDR src column or the From header in a SIP trace. If your provider sends E.164 with a plus, add numbers with the plus; if it sends 10 digits, add 10 digits. If your inbound route normalises caller ID (for example with Set CallerID or a caller ID prefix), the Blacklist sees whatever is set by the time it runs.

The Blacklist also matched on the caller ID name: an entry SPAM LIKELY blocked a call from 4155550123 whose name was SPAM LIKELY. That is handy when a carrier labels spam in the name field, but be careful with generic names such as WIRELESS CALLER, which would block every caller with that label.

Block anonymous and withheld caller ID

In Admin > Blacklist > Settings, set Block Unknown/Blocked Caller ID to Yes, save and press Apply Config. Apply Config matters: FreePBX only writes the anonymous checks into the dialplan when it regenerates it. When we set the flag directly in the Asterisk database without a reload, an anonymous call still went to the extension; after fwconsole reload it was blocked.

asterisk -rx "database put blacklist blocked 1"
fwconsole reload
grep -n -A9 "^\[app-blacklist-check\]" /etc/asterisk/extensions_additional.conf

After the reload, calls with caller ID number anonymous, Restricted and unknown were all blocked, and a normal number still got through. The generated dialplan lowercases the number and compares it with unknown, unavailable, anonymous, private, restricted and blocked, and also catches an empty number.

If your carrier sends the real number in P-Asserted-Identity with Privacy: id, what Asterisk uses as the caller ID depends on the trunk’s trust settings, so test with a withheld call from a mobile before relying on this. Some legitimate callers withhold their number (hospitals, some businesses), so consider sending blocked calls to a voicemail or an announcement instead of hanging up.

Choose where blocked calls go

Destination for BlackListed Calls in the same Settings tab sets the destination; the default is Terminate Call: Hangup. Whatever you pick, the dialplan runs Answer first. In our test the caller received 200 OK and then a hang-up, so the call shows as answered in your CDR, and for the caller it is a connected call, which their carrier may charge for. We did not check how any carrier bills it. If you would rather reject calls without answering, use an inbound route as described next.

Block a range of numbers with an inbound route

Under Connectivity > Inbound Routes, add a route with your DID in DID Number, the pattern in CallerID Number (patterns start with an underscore), and Terminate Call: Hangup as the destination. FreePBX turns it into a caller ID match on the DID extension:

exten => 15550100/_1800NXXXXXX,1,Set(__DIRECTION=INBOUND)
Caller IDRoute matchedResult
18005550123DID + _1800NXXXXXXRejected with 603 Decline, not answered
18885550123DID onlyReached the route to extension 1001
2125550100DID onlyReached the route to extension 1001

For the same DID, Asterisk prefers the route with the caller ID match, so it did not matter that the DID-only route already existed. Pattern letters follow normal Asterisk rules: X is any digit, N is 2–9, [2-5] is a range and . matches one or more characters; see Asterisk dialplan pattern matching. As with the Blacklist, the pattern has to match the format your trunk sends.

One pattern for every DID: CID Priority Route

A route with an empty DID Number and a caller ID pattern matches calls to any DID, but by default a route for the called DID is preferred over it. On our lab, with the DID route to extension 1001 in place, we added a second route with no DID, _1800NXXXXXX and Terminate Call:

CID Priority Route on the any-DID routeCall from 18005550123Call from 2125550100
Off (default)Reached the route to extension 1001: not blockedReached the route to extension 1001
OnRejected with 603 Decline, not answeredReached the route to extension 1001

So tick CID Priority Route on any caller-ID-only blocking route, apply the config, and test one blocked and one normal number afterwards.

Test your rules with SIPp

Testing with your own mobile only covers one number. We used SIPp to place one call from the trunk’s IP address with any caller ID we wanted. The scenario sends an INVITE with a From header built from a CSV file and handles 200, 4xx/5xx and 6xx answers:

printf 'SEQUENTIAL\n18005550123;Toll Free Junk\n' > cid.csv
sipp 203.0.113.10:5060 -sf inbound-cid.xml -inf cid.csv -s 15550100 \
  -i 198.51.100.20 -p 5091 -m 1 -trace_msg

The CSV starts with SEQUENTIAL, then one number;name line per call. The scenario file inbound-cid.xml we used:

<?xml version="1.0" encoding="ISO-8859-1" ?>
<!DOCTYPE scenario SYSTEM "sipp.dtd">
<!-- srvScripts lab: one inbound call from the "carrier" to DID [service] with caller ID number [field0] and name [field1]. -->
<scenario name="inbound caller id test">
  <send retrans="500"><![CDATA[
INVITE sip:[service]@[remote_ip]:[remote_port] SIP/2.0
Via: SIP/2.0/[transport] [local_ip]:[local_port];branch=[branch]
From: "[field1]" <sip:[field0]@[local_ip]:[local_port]>;tag=[pid]cid[call_number]
To: <sip:[service]@[remote_ip]:[remote_port]>
Call-ID: [call_id]
CSeq: 1 INVITE
Contact: <sip:[field0]@[local_ip]:[local_port]>
Max-Forwards: 70
Content-Type: application/sdp
Content-Length: [len]

v=0
o=carrier 53655765 2353687637 IN IP[local_ip_type] [local_ip]
s=-
c=IN IP[media_ip_type] [media_ip]
t=0 0
m=audio [media_port] RTP/AVP 0 8
a=rtpmap:0 PCMU/8000
a=rtpmap:8 PCMA/8000
]]></send>
  <recv response="100" optional="true"/>
  <recv response="180" optional="true"/>
  <recv response="183" optional="true"/>
  <recv response="404" optional="true" next="nak"/>
  <recv response="480" optional="true" next="nak"/>
  <recv response="486" optional="true" next="nak"/>
  <recv response="503" optional="true" next="nak"/>
  <recv response="603" optional="true" next="nak"/>
  <recv response="200" rtd="true"/>
  <send><![CDATA[
ACK sip:[service]@[remote_ip]:[remote_port] SIP/2.0
Via: SIP/2.0/[transport] [local_ip]:[local_port];branch=[branch]
From: "[field1]" <sip:[field0]@[local_ip]:[local_port]>;tag=[pid]cid[call_number]
To: <sip:[service]@[remote_ip]:[remote_port]>[peer_tag_param]
Call-ID: [call_id]
CSeq: 1 ACK
Max-Forwards: 70
Content-Length: 0

]]></send>
  <recv request="BYE" optional="true" next="gotbye" timeout="4000" ontimeout="sendbye"/>
  <label id="sendbye"/>
  <send retrans="500"><![CDATA[
BYE sip:[service]@[remote_ip]:[remote_port] SIP/2.0
Via: SIP/2.0/[transport] [local_ip]:[local_port];branch=[branch]
From: "[field1]" <sip:[field0]@[local_ip]:[local_port]>;tag=[pid]cid[call_number]
To: <sip:[service]@[remote_ip]:[remote_port]>[peer_tag_param]
Call-ID: [call_id]
CSeq: 2 BYE
Max-Forwards: 70
Content-Length: 0

]]></send>
  <recv response="200" crlf="true" next="end"/>
  <label id="gotbye"/>
  <send><![CDATA[
SIP/2.0 200 OK
[last_Via:]
[last_From:]
[last_To:]
[last_Call-ID:]
[last_CSeq:]
Content-Length: 0

]]></send>
  <nop next="end"/>
  <label id="nak"/>
  <send><![CDATA[
ACK sip:[service]@[remote_ip]:[remote_port] SIP/2.0
Via: SIP/2.0/[transport] [local_ip]:[local_port];branch=[branch]
From: "[field1]" <sip:[field0]@[local_ip]:[local_port]>;tag=[pid]cid[call_number]
To: <sip:[service]@[remote_ip]:[remote_port]>[peer_tag_param]
Call-ID: [call_id]
CSeq: 1 ACK
Max-Forwards: 70
Content-Length: 0

]]></send>
  <label id="end"/>
</scenario>

The source address must be one your PBX accepts as the trunk (the PJSIP identify match), so run this only on a lab server or from a host you control that is listed as the trunk. Check where each call went in /var/log/asterisk/full: a blocked call passes through app-blackhole. For why a 200 OK alone proves little, see a 200 OK is not proof the carrier got the call.

How we tested

  • Server: FreePBX 17.0.33.2 with Asterisk 22.11.0 on Debian 12, Blacklist module 17.0.1.2, 19–20 October 2026.
  • Calls: SIPp 3.6 sending INVITEs from the lab trunk’s address to DID 15550100 (inbound route to extension 1001), one call per caller ID. Outcome read from the SIP response and the dialplan steps in the Asterisk full log. Extension 1001 was not registered, so “reached the route to extension 1001” in the tables means the call passed every blocking rule, matched that route and then ended with 503 from the unregistered endpoint; no phone rang.
  • Not tested: the Bulk Handler CSV import for the Blacklist, the *30/*31/*32 feature codes, caller ID in P-Asserted-Identity with privacy, and carriers that send caller ID in other formats.
  • 21 October 2026: a caller-ID-only route (no DID) tested with CID Priority Route off and on, with the DID route in place.
  • The lab was returned to its original state afterwards (Blacklist entries, the blocked flag and the test route removed).

FAQ

Why is the FreePBX Blacklist not blocking a number?

Usually because the stored number does not match the caller ID string the trunk delivers, for example 2125550199 on the list and +12125550199 on the call. Check the CDR src value of a real call from that number and add it in exactly that form.

Do I need Apply Config after adding a Blacklist number?

Not for numbers; they are read from the Asterisk database on every call. You do need Apply Config (or fwconsole reload) after changing Block Unknown/Blocked Caller ID.

Can the FreePBX Blacklist block a whole area code?

No, it matches exact values. Use an inbound route with a caller ID pattern such as _1212NXXXXXX and Terminate Call as the destination, on each DID or once with no DID and CID Priority Route ticked.

Why do blocked callers show as answered calls?

The Blacklist dialplan answers the call before sending it to the blocked-call destination. An inbound route with Terminate Call: Hangup rejected the call without answering in our test.

Related: STIR/SHAKEN in Asterisk and FreePBX and toll fraud prevention. Official reference: Sangoma: Blacklist module.

At a glance

FreePBX Blacklist and Caller ID Blocking: Stop Junk Calls (Tested) summary card: In FreePBX 17, use the FreePBX Blacklist (Admin > Blacklist) for single numbers, and turn on Block Unknown/Blocked Calle…
In short: In FreePBX 17, use the FreePBX Blacklist (Admin > Blacklist) for single numbers, and turn on Block Unknown/Blocked Caller ID for anonymous calls. The Blacklist only matches the exact caller…

Share this guide

Free website test

Is your website set up right?

Check SSL, security headers, redirects, robots.txt, sitemap, llms.txt and security.txt in one test. It takes about 30 seconds.