Whitelist-AGI Design goals


I had the following goals in mind when designing and programming Whitelist-AGI:

You are in control

The system administrator has control over how incoming numbers (and names) are handled, including:

  • Where to route a call that passes the whitelist check
  • Where to route a call that’s not on the whitelist but has a reasonaable name
  • Where to route a call that’s not on the whitelist and the name is hidden or is otherwise not useful
  • Who is and is not on the whitelist

Outbound numbers are added to the whitelist

Telephone numbers called by endpoints on the system are automatically added to the whitelist. If a person at one of those numbers ever returns a call they won’t be treated as an unknown calller. If CallerID names are available for these outbound numbers (either because they had called in previously or they return a call) the names are attached to the number. If no name is available, the number is stored in a special list ofr outbound numbers.

You can update the whitelist

The whitelist is stored in the Contact Manager, in an external group called Whitelist-AGI. You can use the contact manager to add, review, update, or delete entries, and perform bulk entries.

In addition, the feature code *33 allows the caller to whitelist the last inbound number to that extension, or an arbitrary number.


The Whitelist-AGI script is designed to return a result as quickly as possible. Updates to the whitelist are handled by a background process that runs independently of the main script, allowing FreePBX to handle the call while the script is working on the database.

Minimal Asterisk and Linux knowledge required

While implementing the whitelist feature requires setting up several things in FreePBX, the user needs to know only one thing about Asterisk and Linux, namely how to connect to the Asterisk server, log in as the asterisk user, and issue a couple of commands.


The Whitelist-AGI script is responsible for setting up its own default settings and cache. Once the administrator has installed the script and done the FreePBX setup, the script is ready to work the next time a call comes in on an inbound route where whitelisting is active.