cm_fpg.agi: Add a Caller to a Filter Phone Group

cm_fpg.agi inserts a caller's phone number into a VICIdial Filter Phone Group from within a Call Menu, blocking future outbound dials to that number.

A Filter Phone Group is a named list of numbers that VICIdial will skip when loading leads into the dialing queue Filter phone group. Once a number is in a group assigned to a campaign, the campaign will never dial it. The cm_fpg.agi script lets a Call Menu add the caller's inbound CID, or a number the caller enters themselves, into one of those groups in real time without an agent doing anything.

This is useful in a few scenarios: a caller presses an opt-out digit and you want them blocked from outbound dials without going through the DNC table, or you are running a campaign Campaign where certain number ranges should be excluded dynamically based on the caller's own input. The script plays no audio and hands control straight back to the Call Menu option you designate.

The three flag arguments

Arguments are separated by three dashes ---. Position 1 is the Filter Phone Group ID to insert into. This is the text ID you created when you built the group in Admin > Filter Phone Groups. Position 2 is the Call Menu option to route to after the insertion runs. The default is B. Position 3 is optional: if you supply a number here, that number is inserted instead of the caller's inbound CID. This is the method you use when the caller has entered a number via DTMF and you want to insert that collected value.

Two ways to wire the script

The first way is the AGI route method, where the script is triggered by a digit press on the Call Menu option. In Admin > Call Menus, set the Route for the relevant option to AGI, then enter the script name and arguments in the AGI field:

cm_fpg.agi,TEST_FPG---B

When the caller presses that digit, the inbound CID is inserted into the group named TEST_FPG, and the call moves to option B.

The second way uses the Custom Dialplan Entry section of the Call Menu. This is the approach when the caller types a number and you want to insert whatever they entered rather than their inbound CID. The ${EXTEN} variable captures the digits the caller pressed:

exten => _XXXXXXXXXX,1,AGI(cm_fpg.agi,99test---C---${EXTEN})

Here the ten-X pattern matches any ten-digit number the caller enters, inserts it into the group named 99test, and routes to option C. The ${EXTEN} in position 3 passes the collected digits directly to the script as the number to insert.

How the insertion decision flows

flowchart TD
  A[Caller presses digit or enters number] --> B[Call Menu triggers AGI route]
  B --> C[cm_fpg.agi runs]
  C --> D{Position 3 supplied?}
  D -- Yes --> E[Insert entered number into FPG]
  D -- No --> F[Insert inbound CID into FPG]
  E --> G[Route to designated Call Menu option]
  F --> G
  G --> H[Next Call Menu action]

After the number is inserted, VICIdial's dialing logic will skip that number on the next hopper refresh for any campaign that has this Filter Phone Group assigned. The hopper is the short queue of leads waiting to be dialed Hopper. Numbers already sitting in the hopper when the insertion runs may still be called if they were loaded before the block took effect, so for time-sensitive opt-outs, combining this script with a DNC entry via cm_dnc.agi gives you immediate coverage on both the outbound and DNC dimensions.

The Filter Phone Group ID is case-sensitive. TEST_FPG and test_fpg are treated as different groups. Confirm the exact ID in Admin > Filter Phone Groups before wiring the script.

Unlike the DNC table, Filter Phone Groups are scoped per campaign. The same number can be in one campaign's filter group while remaining dialable by another campaign. This makes cm_fpg.agi more surgical than a global DNC entry when you want to suppress a number for one program without affecting others.

For the step-by-step process of attaching any AGI route to a Call Menu option through the VICIdial admin panel, see How to Add an AGI to a Call Menu. The broader API and AGI context is in the VICIdial API and AGI overview.

Every VICIfast plan gives you a production-ready VICIdial server with Call Menus, Filter Phone Groups, and AGI scripting configured and ready in under 40 seconds.