Dialing

VICIdial DNC lists: internal, campaign, and what is yours

How VICIdial's internal and campaign DNC lists work, the four ways a number gets onto them, the API calls, and what the software leaves to you.

By Published Updated 6 min read
An east Asian woman expressing frustration during a phone call at the workplace.

To the point

VICIdial keeps an internal do-not-call list for the whole system and a separate list for each campaign. Neither is checked until the campaign is told to use it. The software only enforces a list of numbers. Which numbers belong on it is your call.

  • Three ways in: an agent disposition, the admin page, or the add_dnc_phone API (one number per request).
  • Three campaign settings: Use Internal DNC (Y by default), Use Campaign DNC (off by default) and Other Campaign DNC (empty by default).
  • add_lead can scrub at load time with dnc_check and campaign_dnc_check. Neither screens anything unless you send Y.
  • Do not load the roughly 209 million number US federal list into the internal table.

Two lists, and which one a campaign checks

The internal list is the table vicidial_dnc and applies to every campaign. The campaign list is vicidial_campaign_dnc, keyed by campaign. Each is a table of numbers the dialer will refuse to call, nothing more.

A new campaign checks the internal list by default: Use Internal DNC ships as Y. Its own campaign list is checked only when you switch Use Campaign DNC on. Both settings also offer AREACODE, and Other Campaign DNC is empty by default.

Whether you scrubbed against national and state registries, and whether you may call a person at all, is the account holder's responsibility. We explain settings. This is not legal advice.

Set the lists, step by step

Screens below come from our test server, campaign Sunline Solar Q4 callbacks (SUNQ4). Each red marker matches the step with the same number.

In VICIdial's admin

VICIdial campaign page with Use Internal DNC List, Use Campaign DNC List and Other Campaign DNC highlighted
The three DNC switches sit together near the bottom of the campaign page
  1. Use Internal DNC List: check the system-wide list before dialing.
  2. Use Campaign DNC List: check the list that belongs to this campaign.
  3. Other Campaign DNC: also check the list of another named campaign.

Click SUBMIT at the bottom. Nothing changes until you do.

In the Trustane console

Trustane console DNC and drop tab with Internal DNC, Campaign DNC and the list picker highlighted
Campaigns, click the campaign, then DNC & drop
  1. Internal DNC: On means the system-wide list is checked.
  2. Campaign DNC: On means this campaign's own list is checked.
  3. Which list: pick the list, then paste numbers in the box below it, one per line or comma separated.

Four ways a number gets onto a list

Diagram: an agent disposition, the admin page, the API and an opt-out key all write into the same DNC tables
Four entry points, one set of tables

An agent disposition. Every status has flags, and one marks it as DNC. When an agent ends a call with that status, VICIdial adds the number. If agents pick a status called DNC and its flag is off, the lead is closed and the number is not added. Status flags also decide what counts as a sale or a contact in reports, so change them deliberately.

The admin page. Add/Delete DNC takes pasted numbers with a scope (internal or one campaign), a log of who added what, and a download. Deleting needs the separate Delete From DNC Lists permission. Give it to few people.

The API. add_dnc_phone adds one number per request. phone_number is 6 to 20 characters. campaign_id is a valid campaign or SYSTEM_INTERNAL for the internal list. The user needs level 8 or higher and the Modify Lists permission. delete_dnc_phone takes the same fields plus Delete From DNC Lists.

https://YOUR-SERVER/vicidial/non_agent_api.php?source=dnc&user=APIUSER&pass=APIPASS&function=add_dnc_phone&phone_number=8135550100&campaign_id=SYSTEM_INTERNAL

An opt-out key. On a Press-1 call menu, a key routed to opt out runs VICIdial's cm_dnc.agi, which writes the number to the internal or the campaign list and logs it. See Press-1 routing.

10,000 opt-outs is 10,000 requests. We have not timed add_dnc_phone, so we give no figure. For add_lead rates see loading leads with add_lead.

Scrubbing at load time

add_lead has dnc_check and campaign_dnc_check. Each takes Y, N or AREACODE, and both default to empty, so neither screens anything unless you send Y or AREACODE. AREACODE also checks by area code. campaign_dnc_check needs campaign_id in the request. A match is refused with a DNC reply, counted apart from invalid and duplicate numbers.

Our test file had no listed numbers, so the DNC count was 0. We showed the counting but did not run a file full of matches. Try a few known numbers first.

The stock web loader is different. Its scrub is the international DNC option, which reads other tables and needs a system setting. It does not check vicidial_dnc.

What the dialer checks when it dials

With Use Internal DNC on, the dialer checks the list as it fills the hopper. A number added afterward can still sit in the hopper behind hundreds of other leads. If a number must stop at once, add it and also look at what the hopper holds. We did not time how fast a new entry takes effect.

Inbound is separate. An in-group can filter callers against the internal or campaign list and send a match to a "blocked" call menu.

What the software does not decide

  • Whether a number may be called. Consent, line type and the rules where you call are law, and they change.
  • Calling hours. The default time zone method works from country and area code. Ported numbers break that. Check a sample.
  • Drop rules. Measure them on your own traffic.
  • Records. Retention is your decision. See how much disk recordings use.

A routine that holds up

Checklist: switch on, status flag, scrub at load, log API calls, test three numbers, review delete permission
Six checks for any server

Questions people ask

Does adding a number to the list stop the next call?

Not always. The check happens when the hopper is filled, so a number already queued there can still be dialed.

Does the web list loader check my internal list?

No. It uses the international DNC option, which reads different tables. Use add_lead with dnc_check=Y to apply the internal list at load.

Next steps

Set Use Internal DNC on every campaign, then test with three numbers you control. If you want a second look at a server's settings, contact us. The answer will describe settings, not legal outcomes. To see a server of your own, read about our hosting or see pricing.

VICIdial is a trademark of its owner. Trustane is an independent hosting provider.

Sources

  1. VICIdial Non-Agent API documentation (add_dnc_phone, delete_dnc_phone, add_lead)
  2. VICIdial manager manual findings, DNC and compliance sections
  3. Lead loading research, DNC options on add_lead and the web loader
  4. Cover photo by Felicity Tai on Pexels

Trustane

Managed VICIdial hosting

Run it on cores of your own

Managed VICIdial, billed by the hour against a balance you top up.

Or try one server free for 7 days, no top-up.