How to Integrate VICIdial with Salesforce

Why Integrate VICIdial and Salesforce

VICIdial excels at high-volume dialing, hopper management, and agent desktops built for throughput. Salesforce excels at pipeline management, account history, and revenue forecasting. Without integration, agents toggle between screens, managers reconcile conflicting dispositions, and marketing cannot trust campaign attribution.

A solid integration pushes call outcomes to Salesforce automatically, pulls fresh leads into the dialer on a schedule, and preserves vendor_id or lead_id mapping so recycle logic in VICIdial does not fight duplicate rules in CRM. The business case is straightforward: fewer manual exports, faster follow-up on warm leads, and auditable activity timelines on every account.

Integration complexity depends on your vicidial hosting model, Salesforce edition, and whether you need real-time bidirectional sync or nightly batch. This guide focuses on patterns that work in production without requiring a full custom CTI rebuild.

Integration Architecture Options

Batch File and API Sync

The most common starting point uses scheduled jobs: export new or updated leads from Salesforce via SOQL or Bulk API, transform to VICIdial list format, and import through ADMIN API or command-line loader. Dispositions flow outbound through a script that reads vicidial_log or vicidial_agent_log and posts Task or Call objects to Salesforce REST API.

Batch sync is simpler to secure and debug. Latency measured in minutes is acceptable for many B2B outbound teams. It pairs well with lead import best practices and avoids overloading Salesforce API limits during peak dialing.

Middleware and iPaaS

Tools like Zapier, Make, or enterprise iPaaS platforms sit between systems when you lack dedicated integration developers. Triggers on Salesforce Lead create push rows to VICIdial; webhooks or polled VICIdial exports create Salesforce Tasks on disposition. Middleware adds vicidial cost but shortens time to value.

Real-Time Agent Screen Pop

Advanced setups use Salesforce Open CTI or Lightning components fed by VICIdial API lookups when a call connects. Agents see account context instantly and disposition back to both systems. Real-time pop demands stable latency between vicidial server and Salesforce, usually sub-200 ms on API round trips for acceptable UX.

Prerequisites Before You Start

1. Salesforce org with API access enabled and integration user licensed.
2. Connected App in Salesforce with OAuth client credentials and appropriate scopes.
3. VICIdial NON-AGENT API user with permissions for lead upload and call log read.
4. Network allowlisting between Salesforce IP ranges and your vicidial server or middleware host.
5. Field mapping document: Salesforce Lead Id maps to VICIdial vendor_lead_code or source_id.
6. Disposition crosswalk table: VICIdial status codes map to Salesforce picklist values.
7. TLS certificates valid on VICIdial web/API endpoint if using HTTPS callbacks.

Complete baseline vicidial setup and SIP carrier configuration before CRM integration. A broken dialer integrated with Salesforce still breaks, only now with synchronized error records.

Step-by-Step: Salesforce to VICIdial Lead Flow

1. Define SOQL query for callable leads: status, owner, timezone, DNC flags, and phone fields normalized to E.164.
2. Export on schedule via Salesforce Bulk API or scheduled Apex to CSV or JSON.
3. Transform records to VICIdial list format: phone_number, list_id, security_phrase, vendor_lead_code.
4. POST to VICIdial non_agent_api.php with function=add_lead or upload leads via list loader.
5. Tag imported leads with source_id equal to Salesforce Lead Id for reverse updates.
6. Mark Salesforce leads as In Dialer using a custom field to prevent duplicate export.
7. Log import batch ID in both systems for support troubleshooting.

Normalize phone numbers during transform. Salesforce stores formatted strings; VICIdial dials digits. Failed normalization is the top reason integrated leads show zero contact rate despite good list quality in CRM.

Step-by-Step: VICIdial Disposition to Salesforce

1. Poll vicidial_agent_log or subscribe to post-call hooks if you run custom AGI.
2. Match vendor_lead_code or source_id to Salesforce Lead or Contact Id.
3. Map VICIdial status to Salesforce Task Status or custom Call Result field.
4. Create Task with subject, call duration, recording URL if stored, and agent comments from VICIdial notes.
5. Update Lead status or Opportunity stage based on disposition rules.
6. On SALE or qualified dispositions, assign owner for non-dialer follow-up in Salesforce.
7. Handle API 4xx errors with dead letter queue; never silently drop dispositions.

Include call recording links only if your storage meets Salesforce security review and customer consent requirements. Many teams store recordings on the vicidial server and link internally rather than exposing public URLs.

Field Mapping and Deduplication

Agree on a single primary key across systems. Salesforce Lead Id stored in VICIdial vendor_lead_code is the most supportable pattern. Avoid mapping only on phone number; recycled lists and household duplicates collide quickly.

• Lead source and campaign ID: drive reporting alignment between VICIdial campaign and Salesforce campaign member.
• Timezone offset: must sync for compliant calling windows and callback scheduling.
• DNC and opt-out flags: Salesforce updates must suppress VICIdial dialing within minutes.
• Custom fields: limit to fields agents actually use; clutter slows screen pop UI.

When Salesforce updates a lead mid-day, decide whether VICIdial receives update_lead API calls or waits for next batch. Real-time DNC should win immediately; title field changes can wait.

Security and Compliance

Store OAuth refresh tokens encrypted on the integration host, not in plain text on the vicidial dialer web root. Use least-privilege Salesforce profiles: integration user reads and writes only required objects. Rotate API keys quarterly.

Call recordings and transcripts may contain PCI or PHI. Salesforce compliance boundaries differ from your vicidial hosting environment. Legal should approve data flows before enabling recording URLs in Task bodies.

Audit logs in both directions prove who changed what when regulators or clients ask. Vicidial support teams can assist with API logging; Salesforce Event Monitoring covers CRM side.

Troubleshooting Common Integration Failures

Duplicate Leads in VICIdial

Cause: export job reruns without checking In Dialer flag. Fix: atomic update in Salesforce after successful import; use upsert logic keyed on vendor_lead_code.

Dispositions Not Appearing in Salesforce

Cause: API limit exceeded, invalid picklist mapping, or mismatched lead ID. Fix: monitor Salesforce API usage dashboards; validate picklist values in sandbox; grep integration logs for INVALID_FIELD errors.

Slow Screen Pop

Cause: Salesforce API latency or unindexed SOQL. Fix: cache account snippets on middleware layer; index custom fields used in lookup queries; place integration worker geographically near Salesforce pod.

Authentication Errors

Cause: expired refresh token or IP restriction on Connected App. Fix: reauthorize OAuth; add middleware egress IPs to Salesforce login IP ranges; confirm clock sync on vicidial server for JWT if used.

Testing and Rollout Strategy

Never test in production on a live consumer list. Use Salesforce sandbox paired with a VICIdial test campaign and ten internal numbers. Script the full loop: create lead, import, dial, disposition, verify Task.

Roll out one sales team or campaign first. Compare contact rate and data match rate daily for two weeks. Parallel run old manual export process until error rate drops below agreed threshold.

Train agents on unified disposition definitions. If VICIdial NI means something different than Salesforce Not Interested picklist, reports diverge even when integration is technically healthy.

Cost and Hosting Considerations

Salesforce API calls and VICIdial storage both scale with call volume. Factor middleware licensing and developer maintenance into vicidial pricing comparisons. Managed vicidial hosting providers sometimes offer prebuilt Salesforce connectors; validate whether they support your custom fields and recycle rules from lead recycling.

Dedicated integration workers prevent heavy Salesforce polling from starving dialer CPU on a single vicidial server. Split roles when agent count exceeds fifty or call volume exceeds six figures daily.

Conclusion

VICIdial and Salesforce integration is a workflow problem dressed as an API problem. Define keys, map dispositions, automate both directions, and monitor failures like you monitor drop rate.

Start with batch sync if you are new to both platforms, then add real-time pop when agents demand it. Done right, sales leadership sees truth in CRM while operations keeps velocity in the dialer, and your vicidial cost delivers measurable pipeline instead of spreadsheet reconciliation overtime.