Setting up Whitelist-AGI

Contents

Caution: These notes may be out of date. As of February 2020 I plan to build a proper FreePBX module for Whitelist-AGI, which should render these instructions obsolete.

This section provides a step-by-step guide to setting up whitelist-AGI on FreePBX.

You need access to the FreePBX server

While practically all of the configuration can be done from the FreePBX admin web pages, it’s unfortunately not possible to do everything from there. You need to be able to log in as the asterisk user on your FreePBX server to do one thing, which is getting the whitelist.agi script into /var/lib/asterisk/agi-bin and making it executable.

Documenting how log in to your FreePBX as the asterisk user is outside the scope of this documentation. If you need assistance doing this, you’ll need to contact someone knowlegeable with Linux.

Preinstall 1. Ensure you have the required FreePBX modules

You need the following FreePBX modules for installation, configuration, and maintenance of Whitelist-AGI:

  • CallerID Lookup
  • Contact Manager
  • Misc Applications

The following are useful but not required:

  • Bulk Handler
  • CID Superfecta
  • Config Edit

You can use the following command to install the needed modules from the command line (must be root):

fwconsole ma downloadinstall bulkhandler cidlookup contactmanager miscapps superfecta

Preinstall 2. Set up needed destinations

There are three possible results from the whitelist check:

  1. Success: the CID Lookup Source check was successful (the call is whitelisted)
  2. Soft failure: the CID Lookup Source check failed but the caller ID contains a legitimate looking value. Note that this can be tripped up by one of the CID Superfecta data sources that sets the caller’s name to a city.
  3. Hard failure: the CID Lookup Source check failed and the caller name is suspicious: blank, “Anonymous”, “Blocked”, “Spam”, “Unknown”, “Withheld”, only digits, or the value set in the “Artificial CNAM” field of the CID Superfecta “Abandon Lookup” data source. Note that “Private” is not on the list. Many people have a legitimate desire or need to have an unlisted number and should not be treated as a telemarketer or scammer.

As the system administrator it is up to you to determine how you want to handle the results. Suggestions are:

  1. Success: typically this is the destination you would have used on the inbound route if you hadn’t diverted it to whitelisting, such as an attendant, a time group, or your green/red BLF call flow.
  2. Soft failure: one possible destination is an IVR that requests the caller to press “1,” or say their name, or enter a phone number, then sends the call to your normal handling.
  3. Hard failure: Possible destinations are Zapateller, a simple hangup, or Lenny. As of January 2020 the web site Crosstalk Solutions has the Lenny sound files and pointers on how to set them up in Asterisk.

Before proceeding with the installation, set up any needed destinations and test them to ensure they work.

  • You probably already have the destination for the success result: unless you’re planning on doing something unusual it’s the destination you’re currently using for your inbound route(s).
  • If you want to use an IVR for the softfail destination (example, “If this is a sales call, please press 5 to hear 15 seconds of monkeys screaming, else press 1,”) this is the time to set up that IVR and test it.
  • If you want to use Zapateller for your hardfail, it’s already set up in FreePBX.

Don’t worry about how you’ll configure Whitelist-AGI to use the the destinations; at this point all that’s necessary is to ensure they’re available. Configuring Whitelist-AGI is done later in this setup.

Preinstall 3. Build a list of numbers to add to the whitelist

If you don’t pre-seed the whitelist, immediately upon implementation everyone calling into your system is treated as either a softfail or a hardfail. If you would like to have long-time callers and customers on the whitelist before they ever call in you’ll need to add them.

Probably the best way to do this is building a CSV (comma-separated values) file and using the Bulk Importer to add its contents to the whitelist. Details of how the bulk importer work are in step 13.

Due to a limitation in how the bulk importer parses CSV files, if you have a mix of callers with only one number and callers with two (e.g. landline and cell, or line 1 and line 2), you’ll need two CSV files: one for callers with only one number and the other for callers with two numbers.

Here’s a sample CSV file for callers with one number (the area code 232 is not in use as of January 2020):

"groupname","grouptype","displayname","phone_1_number","phone_1_type"
"Whitelist-AGI","External","Frodo Baggins","2325550156","home"
"Whitelist-AGI","External","Planet Express","2325550167","work"
  ... (other entries as needed)
"Whitelist-AGI","External","Princess Leia","2325550176","cell"

And a sample CSV file for callers with two numbers:

"groupname","grouptype","displayname","phone_1_number","phone_1_type","phone_2_number","phone_2_type"
"Whitelist-AGI","External","Lord Eddard Stark","2325550142","work","2324447781","home"
"Whitelist-AGI","External","Sherlock Holmes","2325550134","home","2325550128","cell"
  ... (other entries as needed)
"Whitelist-AGI","External","Will Robinson","2325550110","work","2325550177","home"

1. Update the Asterisk dialplan

Since all of the heavy lifting is done by the AGI script, the dialplan code for whitelisting is relatively straightforward:

[whitelist]
exten => s,1,AGI(whitelist.agi)
 same => n,AGI(notify-send.agi)
 same => n,Set(DP_GOTO=customdests,${WHITELIST_GOTO},1)
 same => n,GotoIf($[${DIALPLAN_EXISTS(${DP_GOTO})}]?${DP_GOTO}:badresult)
 same => n(success),Return()
 same => n(softfail),Return()
 same => n(hardfail),Return()
; Failsafe in case whitelist.agi did not return success/softfail/hardfail 
 same => n(badresult),Noop(Bad result '${WHITELIST_RESULT}' from whitelist.agi)
 same => n,Playback(were-sorry&cannot-complete-temp-error&please-try-call-later)
 same => n,Macro(hangupcall)
; Add the last inbound caller (or an arbitrary number) to the whitelist
exten => add,1,Noop(Add a number to the whitelist)
 same => n,AGI(whitelist.agi,a)
 same => n,Hangup

The recommended file for this code is /etc/asterisk/extensions_custom.conf. Do the following to update it:

  1. Log in to FreePBX as an administrator
  2. Go to Admin > Config Edit
  3. Expand the Asterisk Custom Configuration Files folder
  4. Select extensions_custom.conf
  5. Add the above lines to the file
  6. Click Save, then click Apply Config.

2. Create the AGI script file

If you’re comfortable using Linux and scp/wget/curl or even ftp to copy files from a from an outside source to your filesysten, use that to get a copy of the whitelist.agi script. Put the file into /var/lib/asterisk/agi-bin and use chmod +x /var/lib/asterisk/agi-bin/whitelist.agi to make it executable.

Link to source file: whitelist.agi

If you’re unfamiliar with doing this, one workaround is to use Config Edit to create the AGI script file, then use the Linux command line to move it out of /etc/asterisk. Here are the steps:

  1. In Admin > Config Edit, click on   + Add New File
  2. When prompted, enter whitelist.agi as the file name
  3. View the whitelist.agi file in your web browser
  4. Press Ctrl-A to select all the text
  5. Press Ctrl-C to copy the selected text to the clipboard
  6. On the Config Edit page, paste the text into the input box under the text Working on whitelist.agi
  7. Click Save, then click Apply Config.
  8. Log into the PBX server as the asterisk user and issue the following commands:
      cd /var/lib/asterisk/agi-bin
      mv /etc/asterisk/whitelist.agi . && chmod +x whitelist.agi
  9. Log out

3. Set up the “Whitelist-AGI” destination

In FreePBX, go to Admin > Custom Destinations > Add Destination and set up the fields as follows:

Target
whitelist,s,1
Description
Whitelist-AGI
Notes
Whitelists inbound calls based on the CallerID Lookup Source the CallerdID name as presented by the trunk, and returns a result of “success,” “softfail,” or “hardfail.” Requires a custom destination to be set up for each of these results so you can specify how they are handled. For full information consult the Whitelist-AGI documentation.

To use, set “Return” below to “No.” Then in “Inbound Routes > (route) > General > Set Destination” use “Custom Destinations” > “Call Whitelisting.” For best results, set up a CallerID Lookup Source of type “contactmanager” and group “Whitelist-AGI,” and use that source in Inbound Routes > Other > CID Lookup Source.
Return
No

Click Submit and proceed to the next step

4. Set up the “Whitelist-AGI Success” destination

Set up a new destination with the fields set as follows:

Target
whitelist,s,success
Description
Whitelist-AGI Success: CallerID number found in CID Lookup Source
Notes
Sends a call to the specified destination if the caller ID is found in the CID Lookup Source named in “Inbound Routes > (route) > Other > CID Lookup Source.”

To use, set “Return” below to “Yes” and select the destination. This is the destination you would have used on the inbound route if you hadn’t diverted it to whitelisting, such as an attendant, a time group, or your green/red BLF call flow.
Return
Yes
Destination
(Select your desired destination)

Click Submit and proceed to the next step

5. Set up the “Whitelist-AGI Softfail” destination

Set up a new destination with the fields set as follows:

Target
whitelist,s,softfail
Description
Whitelist-AGI Softfail: CallerID number not found in CID Lookup Source but the name looks good
Notes
Sends a call to the specified destination if the CallerID number is not found in the CID Lookup Source named in “Inbound Routes > (route) > Other > CID Lookup Source” but the caller ID name looks good (see “Whitelist-AGI HardFail” for a list of “bad” caller ID names.)

To use, set “Return” below to “Yes” and select the destination. One possible destination is an IVR that requests the caller to press “1,” or say their name, or enter a phone number, then sends the call to your normal handling.
Return
Yes
Destination
(Select your desired destination)

Click Submit and proceed to the next step

6. Set up the “Whitelist-AGI Hardfail” destination

Set up a new destination with the fields set as follows:

Target
whitelist,s,hardfail
Description
Whitelist-AGI Hardfail: CallerID number not found in the CID Lookup Source and the name looks bad
Notes
Sends a call to the specified destination if the CallerID number is not found in the CID Lookup Source named in “Inbound Routes > (route) > Other > CID Lookup Source” and the caller ID name is blank, digits only, or one of “anonymous,” “blocked,” “SPAM,” “unknown,” “withheld” or the text you set in “Admin > CallerID Superfecta > Abandon Lookup > (wrench icon) > Artificial CNAM.” Note that “Private” is not on the list; calls from unknown private numbers are treated as a soft fail.

To use, set “Return” below to “Yes” and select the destination. One possible destination is Zapateller. Or look up “It’s Lenny” and implement that.
Return
Yes
Destination
(Select the desired destination)

Click Submit and proceed to the next step

7. Set up the “Whitelist-AGI Add” destination

Whitelist-AGI has a limited ability to add numbers to the whitelist by calling *33 from your extension. This step and the one following set up this feature.

Set up a new destination with the fields set as follows:

Target
whitelist,add,1
Description
Whitelist-AGI: Add number to whitelist
Notes
Allows the caller to add the last inbound number or an arbitrary number to the whitelist. Suggested feature code is *33.
Return
No

Click Submit and proceed to the next step

8. Set up the “Whitelist-AGI Add” application

In FreePBX, go to Applications > Misc Applications. Click   + Add Misc Application   and set the fields as follows:

Description
Whitelist-AGI: Add number to whitelist
Feature Code
*33
Destination
Custom Destinations
Whitelist-AGI: Add number to whitelist
  • Click Submit
  • Click Apply Config

9. Set up the Contact Manager group

In FreePBX, go to Admin > Contact Manager. Click   + Add New Group   and set the fields as follows.

Note: the Contact Manager Group name is not configurable. The group must have the name Whitelist-AGI for whitelisting to work.

Name
Whitelist-AGI
Type
External

Click Submit and proceed to the next step

10. Set up the Whitelist-AGI group as a CID Lookup Source

In FreePBX, go to Admin > CID Lookup Sources. Click   + Add CIDLookup Source   and set the fields as follows:

Source Description
ContactManagerWhitelist
Source type
Contact Manager
Cache Results
No
Contact Manager Group(s)
Select Whitelist-AGI from the drop-down list
Caller ID Format
Select Display Name

Now:

  • Click Submit
  • Click Apply Config

11. Add initial numbers to the whitelist

If you compiled one or two CSV files containing an initial list of numbers to add to the whitelist, the is the point where you add them.

In FreePBX > Admin > Bulk Handler:

  • Click Import
  • Click Browse
  • Locate the CSV file on the filesystem and click “Open”
  • Click Submit
  • The bulk importer displays a list of entries found in the file. Review the list for errors and completeness
  • When you are done reviewing the list, navigate to the top of the page so you can see the progress bar
  • Click Import (it should be visible in the lower right-hand corner)
  • The importer runs. If you have a large list it may take a minute (or many minutes for a very large list) to import
  • When Fnished appears beside the Import button, click it
  • Repeat the above steps for any additional CSV files

12. Update Inbound Routes

You’re now at the point where you can start whitelisting callers. Do the following:

In FreePBX Connectivity > Inbound Routes > (route) set the following items:

Set Destination
Custom Destinations > Call Whitelist-AGI
Other > CID Lookup Source
Unless you have an unusual setup, set this to ContactManagerWhitelist
Other > Enable Superfecta Lookup
Enable or disable as desired. The Whitelist AGI script is capable of handling names returned from the Superfecta lookup.

Set up other inbound routes as needed.

Finally:

  • Click Submit
  • Click Apply Config



About

Ramblings about Linux and other things

Archives

Tags