Mod blacklist

From FreeSWITCH Wiki
Jump to: navigation, search


Superseded by




The blacklist module is a tool designed to be called from a dialplan or script which returns a boolean value of 'true' or 'false'. The bulk of this wiki content is paraphrased from mazilo's post on DSLreports.


1. Edit autoload_configs/modules.conf.xml and uncomment the line to enable the load of mod_blacklist or add the line to it if the entry is nonexistent.

2. Edit the autoload_configs/blacklist.conf.xml file to un-comment the list and made the necessary changes to the list as seen below. You cannot use an include-like statement and use a wildcard to include all files in a directory. Each list as to be defined individually.

  • There's probably a better place to put this, maybe in scripts? You could probably even place this list in the dialplan directory.
<configuration name="mod_blacklist.conf" description="Blacklist module">
       <list name="blocked" filename="/usr/local/freeswitch/blacklists/blocked.list"/>

3. Create a directory accordingly, i.e. mkdir -p /usr/local/freeswitch/blacklists

4. Make sure freeswitch has permissions to read and write to the files, without which freeswitch will be unable to read numbers from the list nor will it be able to write to it in the event you need to add a number to the block list. The easiest way to do this is.

chown -R freeswitch:freeswitch /usr/local/freeswitch/blacklists (or whatever your freeswitch user runs as)

5. Edit the list by editing the file or using the api. Numbers entries are delimited by new lines.

NOTE: the below "Calling from the Dialplan" does not work. Use "Working Dialplan" instead!

Working Dialplan

When *98 is dialed along with the subsequent number you'd like to blacklist (*9818135551212) the *98 is stripped and the remaining digits are added to the blacklist "blocked". Follow the instructions on this page for adding the file to store blacklisted numbers. The API is then called with the application "set". Fake is just a fake variable. In the prev example below a 1 was prepended. In my example I choose to only add exactly what was dialed. You could do it either way and is your preference. Note the file being played back is a custom wav file. You'll need to create this or use a default message of some sort. Finally the list is saved.

Adding to Blacklist

<extension name="blacklist_add" >
  <condition field="destination_number" expression="^\*98(\d+)$" >
      <action application="answer" />
      <action application="set" data="fake=${blacklist(add blocked $1)}" />
      <action application="playback" data="/usr/local/freeswitch/recordings/blk_item_saved.wav" />
      <action application="event" data="${blacklist(save blocked)}" />

Checking the Blacklist

<extension name="blacklist_check" >
  <condition field="destination_number" expression="^\*97(\d+)$" >
      <action application="answer" />
      <action application="set" data="blacklist_result=${blacklist(check blocked $1)}" inline="true"/>
  <condition field="${blacklist_result}" expression="^true$" break="always" >
      <action application="playback" data="/usr/local/freeswitch/recordings/blk_item_exists.wav" />
      <anti-action application="playback" data="/usr/local/freeswitch/recordings/blk_not_found.wav"/>

Delete Blacklist Item

<extension name="blacklist_delete" >
  <condition field="destination_number" expression="^\*99(\d+)$" >
      <action application="answer" />
      <action application="set" data="fake=${blacklist(del blocked $1)}" />
      <action application="playback" data="/usr/local/freeswitch/recordings/blk_item_deleted.wav" />
      <action application="event" data="${blacklist(save blocked)}" />

Blacklist Inbound Call By CallerID

The below uses regex to remove the "+" from the caller id. You may already do this somewhere else in your dialplan. Or you may need to handle the inbound caller id in some other fashion. However this will give you the idea and put you in the correct direction. You could also stack conditions if you only want it to apply to a specific trunk or something. Again "monkeys.wav" doesn't exist it is there just as a placeholder.

<extension name="blacklisted" >
  <condition field="${blacklist(check blocked ${regex(${caller_id_number}|^\+([0-9]+)$|%1)})}" expression="^true$" >
      <action application="playback" data="misc/monkeys.wav" />
      <action application="hangup" />

Calling from the dialplan

Left this to show a little history however it did not working properly. In fact in the log I was getting "Invalid Application Blacklist". This is because Blacklist is an API. To correct this use the above dialplan instead. Left it also in case there is something I'm missing. If not please remove.

The following can be used to add a number to a specific blacklist named 'blocked'.

<extension name="blacklist_add"> <condition field="destination_number" expression="^\*25625(\d{10})$">
  <action application="blacklist" data="add blocked 1$1"/>
  <action application="sleep" data="1000"/>
  <action application="blacklist" data="save blocked"/>

Line by line, the first defines the 'feature code' used to call it, you can call *25625 plus ten digits. The next, calls the blacklist application and adds a one to the ten digit number saved to $1 then adds it to the blocked list. The third line is a sleep, not sure if this is necessary but I want to make sure there's ample time to the application to respond. The fourth line is optional, and will write any added numbers via API calls to the actual file.

The following is intended to be put near the top of the dialplan for a given profile. Checks for blacklisted number from list 'blocked' then sends it to our friendly spam averter, Lenny!

<extension name="blacklist_check">
  <condition field="${blacklist(check blocked ${destination_number})}" expression="^true$">
    <action application="bridge" data="sofia/external/"/>

API Commands

 freeswitch@internal> blacklist help
 blacklist check <listname> <item> 
 blacklist add <listname> <item>
 blacklist del <listname> <item>
 blacklist save <listname>
 blacklist reload
 blacklist help


Queries a list for an item. Returns 'true', 'false', and 'Wrong syntax'. Bad syntax returns

[DEBUG] mod_blacklist.c:190 Wrong syntax

Unknown list returns

[ERR] mod_blacklist.c:199 Unknown blacklist [listname]
    • To fix this you need to add/check your configuration in blacklist.conf.xml


Writes data entered to corresponding lists via API commands to the file.

Syntax: blacklist save blocked


Adds a number to a specified list.

Syntax: blacklist add blocked 1234567890


Deletes a number from the specified list. Does not delete the list itself, you'll have to manually delete the file and reload the lists to purge a list.

Syntax: blacklist del blocked 1234567890


Reloads current lists. This will not load new lists if you have changed blacklist.conf.xml. This will also not reload anything you've not written to the lists by using 'blacklist dump'.

Syntax: blacklist reload


Displays the help message defined in API Commands