Integrating VICIdial with Google Sheets for Lead Management and Reporting

Why Connect VICIdial to Google Sheets?

Not every call center team has a full CRM budget or the technical resources to maintain a Salesforce integration. Google Sheets fills that gap elegantly. Managers already use spreadsheets for lead lists, daily KPI tracking, and client reporting. Connecting those sheets directly to VICIdial eliminates the manual export-import cycle that wastes hours every week and introduces data entry errors.

A VICIdial Google Sheets integration serves two primary use cases. First, pushing leads from a shared spreadsheet into VICIdial lists so agents can dial them without an admin manually uploading CSV files. Second, pulling call results, agent performance metrics, and campaign statistics from VICIdial into Sheets for dashboards, client reports, and executive summaries. Both directions are achievable with Google Apps Script, the VICIdial Non-Agent API, and scheduled triggers.

This approach works whether you self-host VICIdial or use managed vicidial hosting. The integration runs from Google's infrastructure (Apps Script) or your vicidial server (cron + API), so it does not add load to agent workstations.

Common Use Cases

• Sales managers maintain a lead sheet; new rows auto-import into VICIdial every 15 minutes
• Client-facing performance dashboards update hourly with calls, connects, and conversion rates
• Quality assurance teams review disposition breakdowns in a shared sheet with conditional formatting
• Multi-location teams collaborate on lead lists before a bulk lead import into VICIdial
• Executives view rolled-up campaign metrics without logging into the VICIdial admin interface
• Recycling teams identify callback leads in Sheets and trigger re-import into active dial lists

Sheets integrations are especially popular for smaller teams evaluating vicidial pricing and dialer ROI before investing in enterprise reporting tools. You get 80% of the reporting value at zero additional software cost.

Integration Architecture

Sheets → VICIdial (Lead Import)

Google Apps Script runs on a time-driven trigger (every 5, 15, or 30 minutes). The script reads new rows from a designated sheet tab, formats phone numbers, maps columns to VICIdial list fields, and sends HTTP requests to the VICIdial Non-Agent API add_lead function. After a successful import, the script marks the row with a status column (Imported, Failed, Duplicate) so the same lead is not inserted twice.

VICIdial → Sheets (Reporting Export)

A cron job on your vicidial server queries the database for call logs, agent statistics, or campaign summaries and writes the results to a Google Sheet via the Google Sheets API. Alternatively, Apps Script can pull data from VICIdial using UrlFetchApp to call the Non-Agent API version function and parse the response into sheet rows. The server-side cron approach handles larger data volumes more reliably.

What You Need Before Starting

1. VICIdial with Non-Agent API enabled and an API user account created
2. Google Workspace or personal Google account with access to Google Apps Script
3. A Google Sheet with standardized column headers matching VICIdial list fields
4. HTTPS access from Google's servers to your VICIdial server (public URL or VPN)
5. Service account credentials if using server-to-Sheets export (Google Cloud Console project)
6. Basic familiarity with JavaScript for Apps Script customization

Ensure your vicidial setup includes a stable server with a public hostname or IP. Apps Script runs from Google's cloud and cannot reach private LAN addresses. If your dialer is behind a firewall, configure port forwarding or use a reverse proxy with SSL.

Setting Up Automated Lead Import from Sheets

Design Your Sheet Structure

Create a sheet tab named Leads with columns: first_name, last_name, phone, email, address, city, state, postal_code, source, status, and import_status. The import_status column starts empty and gets populated by the script. Use data validation on the phone column to catch formatting issues before they reach the dialer. Keep one sheet tab per VICIdial list to simplify mapping.

Write the Apps Script

Open Extensions → Apps Script in your Google Sheet. Create a function importLeadsToVicidial() that reads rows where import_status is empty, loops through each row, and calls the VICIdial API. Store your API credentials in Script Properties (File → Project Properties → Script Properties), never hardcoded in the script source. Use UrlFetchApp.fetch() with the POST method and URL-encoded parameters required by the Non-Agent API.

After each API call, write the result to import_status: OK for success, DUPLICATE if the phone already exists, or the error message from VICIdial for failures. Set a time-driven trigger to run the function every 15 minutes. Test with two or three rows before enabling the trigger on a full lead list.

Map Sheet Columns to VICIdial Fields

• Column A (first_name) → first_name parameter
• Column B (last_name) → last_name parameter
• Column C (phone) → phone_number (strip non-digits, prepend country code if missing)
• Column D (email) → email parameter
• Column E (source) → source_id or vendor_lead_code for tracking
• Fixed value list_id → target VICIdial list ID for the campaign

For detailed column requirements and CSV formatting rules, see our complete guide on how to import leads into VICIdial. The same field rules apply whether you upload a file or push via API.

Exporting VICIdial Reports to Google Sheets

Daily Call Summary Dashboard

Create a server-side script (Python or PHP) on your vicidial server that runs nightly via cron. The script queries vicidial_log for the previous day's calls, groups by campaign and disposition, and writes summary rows to a Google Sheet using the gspread Python library or Google Sheets API v4. Include columns for date, campaign, total_calls, connects, sales, conversion_rate, and average_talk_time.

Managers can then build pivot tables, charts, and conditional formatting on top of this data without accessing VICIdial directly. This is particularly useful for client reporting in BPO environments where external stakeholders need visibility into campaign performance.

Near-Real-Time Agent Statistics

For more frequent updates, poll the VICIdial RT Reports data every 5 minutes and push agent login time, calls today, and talk time to a live dashboard sheet. Be mindful of API rate limits and database load — querying vicidial_live_agents and vicidial_agent_log on a tight interval can impact dialer performance on undersized servers. Our guide on understanding VICIdial real-time reports explains which tables and fields to query.

Advanced Integration Patterns

Bidirectional Sync with Status Round-Trip

Advanced setups sync disposition results back to the source sheet. After an agent sets a disposition in VICIdial, a server cron job updates the corresponding row in Google Sheets with the status, call date, and agent notes. This requires storing a unique row identifier (sheet row number or a UUID column) in a VICIdial list custom field during import. Bidirectional sync is powerful but adds complexity — implement import-only first, then add the return path.

Lead Recycling from Sheets

Teams practicing lead recycling best practices can use Sheets to identify leads ready for re-dial. A formula flags leads with NI or NA dispositions older than 7 days, and the import script resets their VICIdial status to NEW and re-inserts them into the active hopper. This gives managers visual control over recycling rules before leads re-enter the dialer.

Troubleshooting Integration Issues

API Authentication and Connection Errors

If Apps Script returns connection errors, verify your VICIdial server is reachable from the public internet on port 443 or 80. Test with curl from an external machine. Check that the Non-Agent API user credentials are correct and the user is not locked out. Review /var/log/astguiclient/vicidial_api.log on the server for failed API attempts.

Phone Number Format Failures

VICIdial rejects phone numbers that do not match expected formats. Strip parentheses, dashes, and spaces in your script before sending. For US numbers, ensure 10 digits with optional leading 1. Log rejected numbers back to the import_status column so managers can fix them in the sheet.

Duplicate Lead Imports

Prevent duplicates by checking import_status before processing a row and querying VICIdial for existing phone numbers in the target list. The add_lead API returns an error for duplicates in some configurations — handle this gracefully and mark the row rather than retrying indefinitely.

Google Apps Script Quotas

Apps Script has daily UrlFetch call limits (20,000 for consumer accounts, higher for Workspace). Batch imports in groups of 50–100 leads per execution and spread large imports across multiple trigger runs. For high-volume operations, move the import logic to your vicidial server and use the Google Sheets API from there instead.

Security Best Practices

API credentials stored in Apps Script Properties are visible to anyone with edit access to the sheet. Restrict sheet sharing to trusted team members. Use a dedicated VICIdial API user with minimal permissions — only the campaigns and lists needed for the integration. Rotate credentials quarterly. Never expose your VICIdial admin URL or API endpoint in a publicly shared sheet.

For regulated industries, consider whether lead PII should live in Google Sheets at all. Sheets data is stored on Google's infrastructure, which may not meet your compliance requirements. In those cases, use Sheets only for aggregated reporting (no PII) and keep lead data exclusively in VICIdial.

When to Graduate Beyond Sheets

Google Sheets integrations work well up to roughly 10,000 leads and a handful of campaigns. Beyond that, consider dedicated CRM integrations like Salesforce or HubSpot, or VICIdial's built-in reporting for real-time reports. Sheets remains an excellent starting point and a permanent solution for teams that prefer spreadsheet flexibility over CRM complexity.

Conclusion

Integrating VICIdial with Google Sheets gives call center managers a familiar interface for lead management and reporting without additional software licenses. Automated lead imports keep agents dialing fresh data, while scheduled report exports put campaign KPIs where stakeholders already work. Start with a one-directional lead import, validate the data flow, then expand to reporting exports and bidirectional sync as your team matures.

Need help configuring API access on your vicidial server or optimizing database queries for report exports? Experienced vicidial support teams can set up the server-side components so your Sheets integration runs reliably from day one.