Connect VICIdial to Vtiger or Salesforce safely: a test-only CRM sync pattern

01 / 07

VICIdial's own CRM hooks, before any custom integration

Before building anything, check what VICIdial already does for you. CRM Popup Login/Address opens a new window on agent login to a campaign, populated the same way as a web form: begin the address with the literal three letters VAR, then use --A--user_custom_one--B-- (and the four other user_custom fields) to carry your own correlation values straight into the CRM's URL. The field lives on the campaign's own detail screen, under the top-level Campaigns menu — not under Admin.

Web Form, Start Call URL and Dispo Call URL cover the rest of a call's lifecycle: Web Form opens when the agent clicks its button in the agent screen; Start Call URL is not seen by the agent but is called every time a call is sent to one; Dispo Call URL fires when the agent finishes dispositioning the call, carrying the disposition, talk time and call notes with it — CALL_URL_FEATURES.txt states the Dispo Call URL specifically is always called from the webserver, not the agent's browser. All three accept the same --A--field--B-- substitution and the same lead-data field list, including lead_id, campaign and every user_custom field. See vicidial-call-urls for the full mechanism — the VAR prefix rule, GET-request semantics, delivery guarantees and an idempotent-receiver pattern — and vicidial-agent-api-guide plus vicidial-non-agent-api-guide for the two APIs this article falls back to below; none of that is re-taught here.

These native fields need no server-side integration service and no VICIdial credentials outside VICIdial itself: VICIdial substitutes the variables and delivers the finished address on its own, whether that means the webserver calling it directly or the agent's browser opening it as a window. That is why they come first, not the small integration service in the rest of this article.

Two more shipped details matter once you go beyond the basic address. CALL_URL_FEATURES.txt documents &CF_uses_custom_fields=Y for the Web Form address specifically: append it to the query string or a custom list field never resolves; CRM Popup Address is "populated just like the web form address," so the same parameter is worth trying there too, but confirm it on your build before relying on it. The same documentation describes LOCALFQDN for the web form URL when agents reach the agent screen through more than one network path: it lets VICIdial rewrite the address per agent to whichever hostname that agent actually used to log in, instead of a fixed one baked into the field, so one saved URL keeps working across every segment.

If a field the CRM expects is sometimes blank on the VICIdial side, a DISPO_FILTER Settings Container can substitute a replacement value before the Dispo Call URL fires — CALL_URL_FEATURES.txt gives replacing a blank state field with a fixed placeholder as its own worked example. That is a VICIdial-side data-hygiene option worth knowing before your field map assumes the CRM has to absorb every blank field itself.

VARhttps://<CRM_HOST>/login?user=--A--user_custom_one--B--&campaign=--A--campaign--B--

02 / 07

Choose one direction and one owner for every field

Start with one narrow flow: CRM sandbox contact → VICIdial test lead, or completed VICIdial test disposition → CRM sandbox activity. Avoid bidirectional sync until a single direction is reliable, because two systems writing the same phone number or status creates silent overwrite and duplicate problems.

Write a field map: internal correlation ID, source record ID, display name, approved test phone field, disposition and last-update timestamp. Define the owner for each field. A CRM is not automatically the source of truth just because an agent sees it first. VICIdial's own vendor_lead_code field — part of the same available-fields list the Call URLs draw from — is usually the safer join key than a phone number, since it exists specifically to hold an external system's identifier.

The native fields above already answer part of this decision: a Dispo Call URL is VICIdial-to-CRM only, so if that direction and that trigger point covers your need, you may not need the rest of this article's integration service at all. Reach for a custom service only for what native fields cannot cover — reading CRM data into VICIdial, running on a schedule, or reacting to something other than login, call-start or disposition.

03 / 07

Use the VICIdial API boundary, not direct browser automation

Native Call URL fields are one-directional and event-triggered: VICIdial calls out when something happens and stops there. They cannot pull a CRM record into VICIdial, run on a schedule, or perform an arbitrary read or write beyond what a single event fires. That gap — not a shortcoming of the native fields, just the edge of what a fire-and-forget URL can do — is what the rest of this article's integration service is for.

VICIdial documents an Agent API for controlling an already logged-in agent session and a Non-Agent API for work outside the interactive agent screen. Read the API file from the exact VICIdial version installed in your lab; available functions and authorization settings are version-dependent.

Put API calls in a server-side integration service. It should authenticate to VICIdial and the CRM with dedicated least-privilege accounts, redact logs, rate-limit retries and keep an audit record. Do not embed secrets into an agent web form or have a browser call a privileged API directly.

04 / 07

Guided example: make a harmless outbound test payload

This object is deliberately generic. It is a local contract between your integration service and a CRM sandbox; it is not a direct call to either vendor and uses no real contact data.

const event = {  eventId: 'lab-vici-001',  source: 'vicidial-lab',  action: 'disposition_review',  vicidialLeadId: 'TEST-001',  crmRecordId: 'SANDBOX-001',  disposition: 'TEST_ONLY',  occurredAt: new Date().toISOString()};

05 / 07

Guided example: prove Salesforce sandbox authentication safely

Salesforce’s developer documentation uses OAuth for API access. Create an external client app and use a flow appropriate to your organization; do not treat a copied user password or a long-lived access token as an integration design. Test against a sandbox and call a harmless endpoint such as limits before creating records.

Keep the client secret and refresh/access tokens in the integration service’s secret store. The example intentionally uses placeholders and should not be pasted with production values.

# Use a sandbox base URL and values supplied by your Salesforce administrator.curl --fail-with-body "$SALESFORCE_SANDBOX_INSTANCE/services/data/vXX.X/limits" \  -H "Authorization: Bearer $SALESFORCE_ACCESS_TOKEN" \  -H 'Accept: application/json'

06 / 07

Apply the same boundary to Vtiger

Use Vtiger’s documented REST API and its supported authentication method for the deployed edition. Create a sandbox test record, read it, then create one clearly labeled test note or activity. Confirm API names, editions and permissions in the administrator’s current Vtiger documentation; do not rely on an old forum snippet as a schema contract.

If you use webhooks or polling, make delivery idempotent: retain the source event ID and refuse to create the same CRM activity twice. A network timeout does not prove the CRM did not receive the first request.

The same one-directional-versus-full-API distinction applies here: Vtiger's REST API can be polled or pushed to from your integration service, but VICIdial has no native Vtiger-specific hook. Every Vtiger touchpoint in this guide goes through the API boundary above, not a Call URL field.

07 / 07

Verify IDs, permissions and deletion before expanding

For each test, capture the VICIdial test ID, CRM sandbox ID, event ID, request timestamp, HTTP status and reviewer result. Confirm that a least-privilege account cannot read unrelated leads or update unrelated CRM objects. Then execute the agreed deletion/cleanup path and verify it completed.

Only after the team accepts the audit trail, field map and rollback should you add another field or direction. Agent screen-pop and click-to-call are separate changes: they can use the Agent API, but still need role checks, session handling and a lab proof.

Roll back the native fields the same way you roll back the integration service: blank the CRM Popup Address and set CRM Popup Login back to N on the campaign, confirm the field reads empty on the detail screen, and only then decommission the sandbox CRM record and the least-privilege accounts.

Log the CRM's own rate-limit or API-usage response alongside your test record. Both Salesforce and Vtiger meter API calls per organization or per license; a test loop that ignores that limit can degrade a shared sandbox for other teams, which is exactly the kind of blast radius a lab exercise is supposed to avoid.

• One direction and one field owner are documented.
• Secrets stay server-side and test accounts are least-privilege.
• The sandbox test record and integration log can be traced and removed.
• Native CRM Popup and Call URL fields are blanked and confirmed empty if the test is rolled back.