How to Use the cm_dnc.agi Call Menu Script

When a caller presses a digit to opt out during a VICIdial IVR flow, something on the back end has to actually record that opt-out before the call ends. That is the job of cm_dnc.agi. It runs inside a Call Menu, sets the caller's number to DNC (Do Not Call) or NI (Not Interested) status without any agent involvement, and then forwards the call to whatever option you designate DNC (do not call).

A Do Not Call list is the system-level or campaign-level record of numbers your dialer is not permitted to call DNC list. Inserting a number into that list during the inbound IVR flow means no agent ever needs to set a disposition, and the number is suppressed from future dials the moment the record is written. The script is designed as a replacement for the older agi-VDADinbound_NI_DNC_CIDlookup.agi script, with a cleaner Call Menu-native interface and more configuration options.

The five flag arguments

Arguments are separated by three dashes ---. Position 1 controls whether to run as DNC or NI. The default is NI, so if you want the caller added to the Do Not Call table you must explicitly pass DNC here.

Position 2 sets whether to insert into the system-wide vicidial_dnc table when no campaign is specified. The default is YES. If you want DNC entries to go into a campaign's own suppression list rather than the global one, set position 3 to a valid campaign ID and position 2 becomes secondary.

Position 3 accepts a campaign ID. When provided, the script takes DNC settings from that campaign rather than the system default. A campaign is the named outbound job that ties a set of agent seats to a group of lead lists Campaign.

Position 4 is the Call Menu option label to route the call to after the script finishes. The default is B. You set up what option B does inside the Call Menu configuration: it can play a confirmation message, disconnect the call, or transfer to another menu.

Position 5 applies only when a campaign is set in position 3. It controls whether the script searches for the lead in that campaign's lists only (CAMP) or across the whole system (SYS). The default is SYS.

Adding the script to a Call Menu AGI route

In Admin > Call Menus, open the menu that handles your opt-out flow. In the Options section, find the digit route where the caller presses to opt out — for example, pressing 9 during the main IVR prompt. Set that option's Route to AGI, then enter the script name and arguments in the AGI field. A typical entry that marks the caller as DNC using campaign-level settings looks like this:

cm_dnc.agi,DNC---YES---TESTCAMP---B---CAMP

This tells the script: run as DNC, insert into the DNC table by default, use TESTCAMP's settings, send the call to option B after, and search only within TESTCAMP's lists for the lead. Option B on that Call Menu should be configured to play a short thank-you or confirmation recording before ending the call.

How the opt-out flow works

flowchart TD
  A[Caller presses opt-out digit] --> B[Call Menu routes to AGI option]
  B --> C[cm_dnc.agi runs]
  C --> D{DNC or NI mode?}
  D -- DNC --> E[Insert into vicidial_dnc table]
  D -- NI --> F[Mark lead as NI status]
  E --> G[Route to Call Menu option B]
  F --> G
  G --> H[Play confirmation or disconnect]

The script plays no audio of its own. All sound the caller hears comes from the Call Menu's own prompt and option recordings. This keeps the audio experience consistent with whatever voice talent or TTS you have configured for that menu.

One important distinction: NI status marks a lead record's disposition in the calling list, while a DNC entry writes to the suppression table that every campaign checks before dialing Lead list. For regulatory opt-outs, you almost always want DNC. For soft opt-outs where the caller just does not want this particular campaign to call them, NI is sufficient.

For the broader process of wiring any AGI script into a Call Menu through the admin interface, see How to Add an AGI to a Call Menu. The full context for how cm_dnc.agi relates to the wider VICIdial API and AGI ecosystem is in the VICIdial API and AGI overview.

Every VICIfast plan ships a fully configured VICIdial server in under 40 seconds, with AGI scripting and Call Menu support ready from the first login.