How to Add Do Not Call List VICIdial
Introduction
This guide explains how to add Do Not Call list VICIdial administrators can use to keep outbound campaigns compliant. DNC handling in VICIdial includes an internal system DNC, campaign-specific DNCs, the vicidial_dnc database table, and options to add numbers from call menus or agent screens. Proper DNC management prevents accidental calls to opted-out numbers and reduces legal risk.
(Legal disclaimer: This article provides technical guidance only and is not legal advice. Consult counsel for compliance with TCPA and local DNC laws.)
Understanding VICIdial DNC Types (Internal vs Campaign)
VICIdial supports multiple DNC methods:
- Internal System DNC: A system-wide list that blocks numbers across all campaigns when enabled. It’s stored in vicidial_dnc.
- Campaign DNC: Per-campaign settings that can override or supplement the internal list. Useful when different campaigns have different compliance rules.
H3: Where DNCs are stored
The primary storage for system-level DNCs is the vicidial_dnc database table. When numbers are inserted here, the dialer will usually scrub lists and avoid calling those numbers during automatic dialing. Confirm your VICIdial build/version for exact behavior.
Preparing Your DNC Data
Before uploading or inserting numbers, prepare a clean CSV or SQL export.
- Normalize phone numbers: remove spaces, punctuation, and leading “+” or country codes if VICIdial expects national formats. Some builds expect numbers without country code; others include it. Test on a small sample.
- Remove duplicates.
- Include a source and timestamp column if you plan automated merges.
- Maintain a master DNC CSV as a backup.
Method 1 — Uploading DNC via Admin GUI
This is the simplest way for many teams.
- Admin > Lists > Add/Delete DNC (or similar path depending on build).
- Choose “Upload” or paste numbers.
- Confirm normalization options.
- Click “Process” and wait for completion.
- Verify count matches expected entries.
Notes:
- The GUI may have limits on file size; split large lists.
- Some versions perform duplicate checks during upload.
Method 2 — Inserting into vicidial_dnc via SQL
For automation or very large lists, use SQL.
Typical steps:
- Backup the vicidial_dnc table.
- Use a staging table to import CSV via LOAD DATA INFILE (MySQL) or INSERT statements.
- Normalize numbers with SQL functions (e.g., REPLACE).
- Use INSERT IGNORE or ON DUPLICATE KEY UPDATE to avoid duplicates.
Example (conceptual, test first):
LOAD DATA INFILE '/path/to/dnc.csv'
INTO TABLE vicidial_dnc
FIELDS TERMINATED BY ',' OPTIONALLY ENCLOSED BY '"'
(phone_number, entry_date, source)
SET phone_number = REPLACE(REPLACE(phone_number, '-', ''), ' ', '');
Always test on a staging DB and ensure columns match your VICIdial schema.
Method 3 — Adding DNC from a Call Menu (AGI)
A common need is letting inbound callers press a key to add themselves to DNC. VICIdial supports an AGI that inserts numbers into vicidial_dnc.
High-level flow:
- Create a Call Menu in Inbound settings.
- Add an AGI route that runs the DNC insert script or built-in AGI.
- Configure flags: run as DNC/NI status, insert into vicidial_dnc, campaign override options, and post-route action.
Example AGI parameters (conceptual):
DNC AGI: dnc_insert.agi|1|YES|SYS|B
- 1 = run as DNC status
- YES = insert into vicidial_dnc
- SYS = search system-wide
- B = branch after execution
After callers press the key, the AGI inserts the caller’s number into vicidial_dnc and optionally routes the call to a confirmation message. Test the call menu end-to-end.
Method 4 — Letting Agents Add Numbers (Agent Screen)
Agents should be able to mark leads as DNC without SQL.
- Add dispositions (“DNC”, “NI – Do Not Call”) mapped to a script action.
- Configure the disposition to run the DNC AGI or trigger insertion.
- Limit permissions: restrict who can delete from DNC. VICIdial has separate delete permissions, but not always separate add permission, so control user roles.
Scrubbing Leads Against DNC (Best Practices)
Scrubbing prevents uploading or dialing DNC numbers.
- Nightly scrub: Run a routine that compares new lists to vicidial_dnc and flags or removes matches. Use batching to handle very large DNC datasets.
- Pre-upload scrub: Compare incoming CSVs against your master DNC CSV before importing to avoid rejections.
- On-import scrub: Some VICIdial installs automatically refuse to import leads matching vicidial_dnc; check your build.
- Third-party scrubbers: For national DNC lists (e.g., US National DNC), consider reliable vendors or built-in integrations like DNC.com for TCPA-focused filtering.
Handling International Numbers & Country Codes
Different countries use different dialing formats. VICIdial matching logic may strip or ignore dial codes. Recommendations:
- Standardize on one format for your system (E.164 or national without leading 0/1) and convert all inputs to that.
- For US campaigns, consider stripping the “+1” or storing numbers without country code if your VICIdial build requires it. Test matching with a few known numbers.
Automation Ideas & Scalable Architectures
Large operations need automation.
- Daily ETL: Pull national DNC updates, normalize, and LOAD DATA into vicidial_dnc during low-peak hours.
- API-based adds: Expose an internal API for agent screens or self-service forms to POST numbers into the DNC table.
- Queue-based processing: For very large imports, use a queue (RabbitMQ, Redis) and workers to insert and validate numbers in batches.
- Monitoring: Track DNC insert counts, scrub misses, and failed imports.
Troubleshooting Common Issues
DNC numbers still dialed?
- Ensure you’re using the correct match format (with/without country code).
- Confirm the DNC method (Internal vs Campaign) and that campaign settings are set to honor system DNC.
Uploads appear to succeed but not block calls
- Verify that vicidial_dnc contains entries and check timestamps.
- Check if your build requires nightly scrubbing or an enabled option to block during dialing.
Agents can delete DNC entries
- Remove delete permissions for non-admins or implement an approval workflow. VICIdial may not provide fine-grained add permission.
Performance Tips for Very Large DNC Datasets
When DNC lists grow into millions of rows, database performance becomes important.
- Indexing: Ensure vicidial_dnc.phone_number has an index for fast joins and lookups.
- Partitioning: For massive tables, consider partitioning by range or hash if your MySQL version supports it.
- Batch inserts: Use bulk LOAD DATA INFILE with transactions disabled for speed, then re-enable indexing.
- Read replicas: Offload reporting queries to read replicas to avoid locking the main DB.
- Monitoring: Watch slow query logs and optimize queries that join vicidial_list with vicidial_dnc.
Merge Strategy for Multiple DNC Sources
You may have internal opt-outs, national registry exports, and vendor-scrubbed lists. Merge carefully.
- Source tagging: Include a source column (e.g., internal, ndnc, vendorX) to track origins.
- Priority rules: Decide which source takes precedence. For example, internal opt-outs may override vendor flags.
- De-duplication: Use INSERT IGNORE or GROUP BY logic during merges.
- Provenance logs: Keep files and timestamps for legal audits.
SQL Snippets & Normalization Examples
Below are common SQL snippets for cleaning and inserting numbers. Run on test DB first.
Strip non-digits and leading country code (MySQL):
UPDATE staging_dnc
SET phone_clean = REGEXP_REPLACE(phone_raw, '[^0-9]', '');
UPDATE staging_dnc
SET phone_clean = CASE
WHEN LEFT(phone_clean,1) = '1' AND LENGTH(phone_clean) = 11 THEN SUBSTRING(phone_clean,2)
ELSE phone_clean
END;
Insert unique numbers into vicidial_dnc:
INSERT IGNORE INTO vicidial_dnc (phone_number, entry_date, source)
SELECT phone_clean, NOW(), 'national_scrub'
FROM staging_dnc;
Find leads still calling after DNC insertion (audit):
SELECT l.lead_id, l.phone_number, d.entry_date
FROM vicidial_list l
LEFT JOIN vicidial_dnc d ON l.phone_number = d.phone_number
WHERE d.phone_number IS NOT NULL
Sample AGI Script Logic (Pseudo-Code)
Below is the logical flow an AGI or small script should follow for call-menu-driven DNC insertion.
- Receive caller’s ANI (caller ID) or user-entered number.
- Normalize the number to system format.
- Check if number already exists in vicidial_dnc.
- If not present, insert a new row with source and timestamp.
- Return success to call menu and optionally play a confirmation message.
Pseudo-code:
ani = get_ani()
phone = normalize(ani)
if not exists(select 1 from vicidial_dnc where phone_number = phone):
insert into vicidial_dnc (phone_number, entry_date, source) values (phone, now(), 'call_menu')
play_confirmation()
A robust AGI also logs failures and retries.
Example Cron for Nightly DNC Update (Linux)
A simple cron job that runs at 2:30 AM to pull a canonical DNC CSV, normalize, and insert.
30 2 * * * /usr/local/bin/update_dnc.sh >> /var/log/vicidial/update_dnc.log 2>&1
update_dnc.sh would:
- Download the DNC source (securely).
- Normalize file to expected format.
- Move to staging and LOAD DATA INFILE to staging table.
- Run SQL normalization & insert into vicidial_dnc.
Audit, Logs & Reporting
Auditing DNC actions reduces risk.
- Insertion logs: Log user ID or system process that added a DNC entry, with IP and timestamp.
- Deletion review: If deletions are allowed, require admin approval and log who approved it.
- Daily reports: Generate daily counts of new DNC entries, failed scrubs, and import errors.
- Retention policy: Retain DNC records per legal requirements; some jurisdictions require permanent records.
Merge Strategy for Multiple DNC Sources
(Repeat / reinforcement) When merging vendor, internal, and national lists, treat the internal opt-out as primary, tag sources, keep provenance, and de-duplicate before inserting into vicidial_dnc.
FAQs (Common Questions)
Q: If I add a number to vicidial_dnc, will it be removed from lists automatically?
A: New imports and the dialer will avoid numbers in vicidial_dnc, but behavior depends on build. Some systems scrub at import time; others during dialing. Verify with test runs.Q: Can callers add themselves to DNC via inbound IVR?
A: Yes. Use a Call Menu with an AGI that inserts the caller’s ANI into vicidial_dnc and plays a confirmation.Q: How do I handle mobile vs landline exclusions for TCPA?
A: Use vendor filters or services that flag cellphone numbers and apply special consent rules. VICIdial integrations (e.g., DNC.com) can help with cellphone filtering.Troubleshooting (Expanded)
Problem: DNC entries exist but calls continue.
Checks:- Confirm matching format (country code, leading zero).
- Check campaign to ensure it honors the system DNC or uses its own campaign DNC list.
- Review last scrub timestamp and failed import logs.
Problem: Upload fails on large CSV.
Solution: Split files, use LOAD DATA INFILE, or run batch inserts via a staging table.Best Practices Summary
- Normalize all numbers to a single canonical format before insertion.
- Use the vicidial_dnc table for system-level blocking and campaign DNCs for campaign-specific rules.
- Provide agents and inbound callers with easy methods to add to DNC (dispositions & AGI).
- Automate nightly scrubs and keep robust logs for audits.
- Limit delete permissions and require approval for any removals.
To recap, how to add do not call list vicidial properly requires attention to formatting, the vicidial_dnc table, and your campaign DNC settings. Following the steps above ensures your operation handles opt-outs reliably and reduces risk when you run outbound campaigns.
FAQs
1. How do I add a number to the Do Not Call list in VICIdial?
You can add numbers to the VICIdial Do Not Call (DNC) list in several ways:
- Use the Admin Panel → Lists → Add/Delete DNC → Upload or enter numbers manually.
- From the Agent Interface, select a DNC disposition during a call.
- Configure an Inbound Call Menu (IVR) with a DNC AGI script to automatically insert numbers when callers choose to opt out.
- Use SQL commands to directly insert numbers into the vicidial_dnc table for bulk updates.
2. What is the difference between Internal DNC and Campaign DNC in VICIdial?
- Internal DNC applies system-wide, meaning once a number is added, it’s blocked across all campaigns.
- Campaign DNC applies only to a specific campaign and allows flexibility when certain campaigns must follow different compliance policies.
Most call centers use both to ensure maximum protection from dialing restricted numbers.
3. How can I scrub my lead list against the DNC database?
VICIdial allows scrubbing during or after list uploads:
- Enable “Check for DNC Numbers” in the campaign or list settings.
- Use SQL to compare new leads with the vicidial_dnc table before inserting them.
- For large-scale setups, schedule a nightly cron job to scrub all new leads automatically.
Third-party integrations like DNC.com or TCPA scrubbing tools can also automate compliance checks.
4. Can inbound callers add themselves to the Do Not Call list automatically?
Yes. By creating a Call Menu (IVR) option that runs a DNC AGI script, callers can press a key (e.g., “Press 9 to be added to our Do Not Call list”). The system automatically inserts their phone number into the vicidial_dnc table and plays a confirmation message. This is one of the most efficient and compliant ways to handle opt-out requests.
5. Why are numbers on my DNC list still being dialed?
If VICIdial continues dialing DNC numbers, check the following:
- Ensure your campaign is set to honor the internal DNC list.
- Verify the format of phone numbers (country code, leading zero, etc.).
- Make sure the DNC list is properly uploaded or inserted into the correct database table.
- Some older VICIdial builds require a manual scrub before dialing—run a test import to confirm settings.
Conclusion
Adding and maintaining a Do Not Call list in VICIdial is essential for regulatory compliance and operational efficiency. By using the right combination of internal and campaign DNC settings, automated scrubbing, and agent or IVR-based opt-out options, you can ensure that your call center respects customer preferences and avoids potential penalties. Always keep your DNC processes up to date, test frequently, and document every update for accountability.