Set up DNC scrubbing in VICIdial: internal lists and DNC.com

01 / 08

Separate internal filtering from external scrubbing

Use one fictional test number in an isolated list. Check the relevant DNC setting, try each intended call path and record whether the call is blocked; investigate any path that behaves differently.

VICIdial has internal DNC lists and an optional DNC.com integration. Internal enforcement depends on campaign settings and the call path; DNC.com batch and inbound checks are separate, optional integrations. Confirm the installed revision and test each intended path.

This is configuration guidance, not legal advice, and it does not establish that any call is lawful. The Telephone Consumer Protection Act (TCPA) is United States federal law; state, provincial, and other countries' do-not-call and telemarketing rules differ and can be stricter. For the legal-boundary and carrier-signaling material — what a DNC check or STIR/SHAKEN attestation does and does not prove, and how far a technical control actually reaches — see the companion article “VICIdial DNC and STIR/SHAKEN: controls, limits and legal review”; this guide is the hands-on counterpart and does not repeat that legal-review discussion.

In plain language: a lead is one contact record, a phone number plus its call history; a list is a named batch of leads you load and dial as a unit; a campaign is one calling project, meaning which leads get dialed, by which agents, under which dialing settings; a DID (direct inward dial number) is a phone number that routes an inbound call into VICIdial; a carrier is the phone company that carries your calls to the public telephone network; a disposition is the outcome code an agent saves after a call, such as SALE or DNC; a hopper is the queue of leads VICIdial has already decided are eligible to dial next.

• Name the jurisdiction (TCPA plus any state, provincial, or other country rule) that applies to this campaign before you configure anything.
• Decide whether you need system-wide suppression, campaign-only suppression, or both.
• Confirm whether DNC.com is even in use; it requires its own paid account and is entirely optional.

02 / 08

Step 1 — Load and manage the internal DNC list

VICIdial keeps a system-wide internal list in the vicidial_dnc table, one row per phone number, checked across every campaign that turns the check on. A separate table, vicidial_campaign_dnc, pairs a phone number with one campaign_id, so a number can be blocked only for a single campaign without ever touching the system-wide list.

Load and remove entries through Lists → the DNC add/delete screen, or through the add_dnc_phone and delete_dnc_phone Non-Agent API functions. Do not write to either table directly: both supported paths write a matching row to vicidial_dnc_log, which is what lets you prove later who suppressed a number and when.

The admin screen accepts more than one campaign at a time. SYSTEM_INTERNAL targets the global list; ALL_CAMPAIGNS, ALL_ACTIVE_CAMPAIGNS, ALL_DNC_CAMPAIGNS, and ALL_ACTIVE_DNC_CAMPAIGNS apply the same add or delete across every campaign that matches that description, which is convenient but also the fastest way to touch far more campaigns than you intended. Read the target value twice before submitting a delete.

Removing a number is the riskier direction of the two. The delete_from_dnc permission on a user account is what actually allows a deletion to go through; review who holds that permission the same way you would review any other destructive-action grant.

Use only an authorized synthetic number or approved aggregate in this check; keep real phone numbers and record identifiers private. Results for one call path do not prove another path.

SHOW CREATE TABLE vicidial_dnc;SHOW CREATE TABLE vicidial_campaign_dnc;SELECT COUNT(*) AS system_dnc_rows FROM vicidial_dnc;SELECT COUNT(*) AS campaign_dnc_rows FROM vicidial_campaign_dnc WHERE campaign_id='<CAMPAIGN_ID>';

• Confirm whether the number belongs on the system-wide list, a single campaign's list, or both.
• Use the admin screen or the API, never a direct table write.
• List accounts with delete_from_dnc permission, remove grants no longer needed and set a date to repeat the check.

03 / 08

Step 2 — Choose system-level vs. campaign-level scope

Two campaign settings decide whether either list is even consulted: use_internal_dnc controls the system-wide vicidial_dnc table, and use_campaign_dnc controls that campaign's own vicidial_campaign_dnc entries. Each accepts Y, N, or AREACODE — AREACODE blocks every number sharing the same area code as a listed entry, not just an exact match, which is useful when an entire region has opted out of a campaign rather than one number.

A third setting, use_other_campaign_dnc, lets one campaign also honor a second, named campaign's list without merging or duplicating the underlying rows. A fourth, callback_dnc, decides whether a scheduled callback re-checks DNC before it redials; leaving it DISABLED means a callback can still reach a number that was added to DNC after the callback was scheduled.

This is the gotcha that catches most new installs: a number sitting in vicidial_dnc or vicidial_campaign_dnc proves nothing about enforcement on its own. If the campaign's flag is N, the row is simply never read. Always check the list and the flag together, never one on its own.

Use only an authorized synthetic number or approved aggregate in this check; keep real phone numbers and record identifiers private. Results for one call path do not prove another path.

SELECT campaign_id, use_internal_dnc, use_campaign_dnc, use_other_campaign_dnc, callback_dncFROM vicidial_campaignsWHERE campaign_id='<CAMPAIGN_ID>';

• Read use_internal_dnc and use_campaign_dnc together with the DNC tables, not instead of them.
• Decide the AREACODE behavior deliberately; it blocks an entire area code, not one number.
• Set callback_dnc to ENABLED unless you have a specific, documented reason not to.

04 / 08

Step 3 — Configure the optional DNC.com integration

Keep batch and inbound integration separate. Before configuring, obtain the current provider HTTPS scrub endpoint, private API login and project/campaign identifiers from your DNC.com account. Verify the installed script accepts that account/API version; the historical project example is a configuration reference, not current provider authorization.

In Admin → Settings Containers, create or reopen the private container ID DNCDOTCOM. Paste the reviewed key/value contract below only after replacing placeholders. VICI_LISTS uses hyphen-separated IDs, not an inclusive numeric range. The selected statuses must exist on this installation and remain excluded from campaign Dial Statuses until reviewed.

For this conservative worksheet create DCHOLD, DCCLR and DCDNC as non-dialable campaign statuses through the campaign’s status controls. Clean classification DCCLR is held for review, not automatically made callable. DCDNC/DCHOLD suppress or quarantine external results; do not infer lawful calling from a provider code.

1. Save/reopen the reviewed private container. For a first batch use one inactive isolated list with provider-approved test fixtures; never submit customer numbers merely to learn the interface. Record prior lead statuses.
2. Confirm the actual installed AST_DNCcom_filter.pl path and run its documented --lists=<ISOLATED_LIST_ID> invocation only in an independently authorized provider test. Check exit/result and vicidial_dnccom_filter_log for exactly those lead IDs; a clean exit alone is insufficient.
3. For inbound screening, set only the spare test DID’s Filter Inbound Number to URL and its Filter URL to the local DNCcom_inbound_filter.php with phone=--A--phone_number--B--. Use the approved HTTPS host/path and R10 only for the documented North American ten-digit normalization. Reopen the DID.
4. Verify inbound blocking separately using a provider-approved fixture and a bounded authorized test; inspect vicidial_dnccom_scrub_log and the intended caller result. An outbound batch log does not prove the DID filter.
5. If either result is wrong, disable only this test job/filter, retain the container/logs and restore the recorded DID fields. Restore only known changed lead statuses through Admin/update_lead; do not delete real suppression entries to make a test pass.

DNC_DOT_COM_URL => <CURRENT_PROVIDER_HTTPS_SCRUB_URL>LOGIN_ID => <PRIVATE_ACCOUNT_API_LOGIN>PROJ_ID => <ACCOUNT_PROJECT_ID>CAMPAIGN_ID => <ACCOUNT_CAMPAIGN_ID>VERSION => <SUPPORTED_ACCOUNT_API_VERSION>VICI_LISTS => <ISOLATED_LIST_ID>VICI_STATUS_SKIP => SALE-DNCSTATUS_X => DCHOLDSTATUS_C => DCCLRSTATUS_O => DCHOLDSTATUS_E => DCHOLDSTATUS_W => DCHOLDSTATUS_G => DCHOLDSTATUS_H => DCHOLDSTATUS_L => DCHOLDSTATUS_F => DCHOLDSTATUS_V => DCHOLDSTATUS_I => DCHOLDSTATUS_M => DCHOLDSTATUS_B => DCHOLDSTATUS_P => DCDNCSTATUS_D => DCDNCSTATUS_S => DCHOLDSTATUS_T => DCHOLDSTATUS_Y => DCHOLDINBOUND_FILTER => USADNC,PROJDNC,LITIGATOR,INVALIDINBOUND_CACHE => 0

You should seeConfiguration is complete only when the private container, non-dialable status mapping, isolated list and separate DID filter all reopen as intended. Provider batch/inbound acceptance remains unperformed here.

• Confirm which list IDs are actually included in VICI_LISTS before the first run.
• Set VICI_STATUS_SKIP to exclude already-worked statuses such as SALE, so a rescrub cannot overwrite a completed disposition.
• Schedule the outbound batch job on inactive lists or after hours, since it is documented as batch-only.

05 / 08

Where a lead actually gets blocked in the call path

Suppression is checked at more than one point, and knowing which one fired matters when a call gets through that should not have. A batch worker, AST_DB_DNC_filter.pl, can pre-scrub a freshly loaded list against the system and campaign DNC tables and flip a matching lead's status to DNCL for a system match or DNCC for a campaign match, before that lead is ever eligible to dial.

Hopper fill selects eligible leads for hopper-based dialing. A lead absent from the hopper is not selected by that hopper path; manual-number entry and callbacks require their own checks.

Hopper-based outbound dialing and manual-number entry can follow different paths. Check DNC behavior separately for each mode and for scheduled callbacks, including the installed meaning of callback_dnc. Inbound DID screening is configured separately from outbound hopper selection.

The DNC disposition status itself — the one an agent or an API sets after a live contact asks to be removed — is a different thing again. That status records a request going forward; it does not retroactively prove the earlier call should have been blocked.

Use only an authorized synthetic number or approved aggregate in this check; keep real phone numbers and record identifiers private. Results for one call path do not prove another path.

• Trace a suspect call through the batch pre-scrub, hopper fill, and callback flag in that order.
• Check inbound DIDs separately; they do not share the outbound hopper path.
• Do not treat a DNC disposition on one call record as proof the number was suppressed beforehand.

06 / 08

Prove one manual-number DNC refusal in an isolated lab

Worked path: manual-number entry, with internal DNC filtering enabled. This is a future authorized test recipe; no new call or rejection capture is claimed. Use a private isolated MANUAL campaign, an approved station and a known-working internal-only route so an unexpected filter failure cannot reach a customer/carrier.

Example raw phone_number 9001001 and phone_code 1 refer to the course’s internal19001001 route only if that exact route was independently prepared and verified. Store the raw9001001 in the DNC list, not the constructed19001001. Substitute your approved fixture consistently.

1. Before activation, record campaign Dial Method, Manual Dial Filter, Use Internal DNC, Use Campaign DNC, other-campaign DNC and callback settings. Confirm the effective test route is internal only and the synthetic number is absent from DNC before this new test. If already present, record the existing state and do not remove it.
2. On this source-checked SVN4037 branch, set Manual Dial Filter DNC and Use Internal DNC Y on the isolated campaign;save/reopen. The DNC filter gate is required for manual-number entry. Keep unrelated flags unchanged and obtain the test window before station login.
3. Open Lists → DNC add/delete. Select ADD and SYSTEM_INTERNAL, enter raw9001001 once and submit. Read the result and verify the exact membership plus its vicidial_dnc_log ADD row. Use only the synthetic fixture;never use a real subscriber for this exercise.
4. In a fresh authorized test Agent session, remain PAUSED. Open MANUAL DIAL, enter the raw test number and phone code in their own fields, and submit once. Expected result on this branch is the DNC refusal, not a connected customer call. Do not bypass the rejection or switch filters to continue.
5. Record time, user, campaign, raw number, path and the exact returned DNC message. Have the telephony owner confirm no customer Originate/channel was created for that attempt and compare the relevant request/log. List membership plus an unrelated error is not a pass.
6. If any customer leg starts, hang up the owned test leg, pause/stop the campaign and preserve evidence. Check the saved Manual Dial Filter, number normalization and installed path;do not retry blindly.
7. For cleanup, log out the test station and restore recorded campaign/Active values. Remove this DNC entry only if the test created it and the owner approves its scoped reversal;use the supported delete path and verify its audit row. Existing DNC entries remain protected.

#!/usr/bin/env bashset -euo pipefailREADONLY_CNF=/etc/vicidial-readonly.cnfPHONE='<PHONE_NUMBER>'sudo mysql --defaults-file="$READONLY_CNF" -e "SELECT phone_number FROM vicidial_dnc WHERE phone_number='$PHONE';"sudo mysql --defaults-file="$READONLY_CNF" -e "SELECT phone_number, campaign_id FROM vicidial_campaign_dnc WHERE phone_number='$PHONE';"sudo mysql --defaults-file="$READONLY_CNF" -e "SELECT lead_id, list_id, status FROM vicidial_list WHERE phone_number='$PHONE';"

Inspect the actual campaign DNC control

Open to enlarge

You should seePass requires the intended DNC refusal and no customer call, alongside matching configuration/membership/audit evidence. The installed primary source has a DNC gate before manual origination;this article supplies no newly executed acceptance.

07 / 08

Keep an auditable record of every suppression

vicidial_dnc_log records every add and delete against either DNC table with the acting user, an add-or-delete action, a campaign_id (or -SYSINT- for the system list), and a timestamp. Read it by phone number to answer who suppressed this number, when, and through which list.

The admin screen additionally writes a matching vicidial_admin_log row with the section, the exact action, and the SQL that ran, which is useful when you need to show an administrative action rather than just the resulting row. For DNC.com, vicidial_dnccom_filter_log records each outbound batch result per lead (old status, new status, and the raw response), and vicidial_dnccom_scrub_log records each inbound real-time result per phone number with separate invalid, DNC, project-DNC, and litigator flags.

Together these four sources are the record you keep: the two DNC tables say what is currently suppressed, and these logs say how it got that way. Retain them at least as long as your compliance owner requires, and never let a bulk cleanup delete log rows just to shrink a table.

Use only an authorized synthetic number or approved aggregate in this check; keep real phone numbers and record identifiers private. Results for one call path do not prove another path.

SELECT campaign_id, action, action_date, userFROM vicidial_dnc_logWHERE phone_number='<PHONE_NUMBER>'ORDER BY action_date DESCLIMIT 1000;

08 / 08

Troubleshoot a bad scrub, stop it, and roll back safely

If statuses change unexpectedly, inspect the batch selection and VICI_STATUS_SKIP. If a call reaches a listed number, check the campaign flags, call path and any queued lead. If inbound screening fails, inspect the DID filter configuration and provider responses; none of these symptoms has a single guaranteed cause.

If a batch run mis-set statuses, stop the cron job first, then use vicidial_dnccom_filter_log to find exactly which lead_id and list_id rows changed and what their old_status was. Restore only those rows through the admin lead screen or the update_lead API function, never a bulk update statement.

If you need to reverse an internal DNC add, use the Admin delete screen or the delete_dnc_phone API function, gated by the delete_from_dnc permission from step 1, rather than a direct delete against the table. That path writes the same audit row that later proves the reversal happened. Rollback here means a documented reversal through the same supported interface that made the original change, not a manual SQL fix applied under pressure.

Recheck the list entries and campaign flags, then verify the affected call path on a non-customer test route. The database reads alone do not prove enforcement.

Any cron, status or recovery action described here is prospective. Verify the installed-version procedure and preserve existing records; no rollback or restore has been performed.

• Stop the batch job before investigating, not after.
• Restore only the specific rows a log identifies, never with a bulk statement.
• After checking the affected rows and flags, test enforcement on each relevant non-customer call path.