Finish a concrete integration contract before building the worker
This guide produces a filled data contract and sandbox acceptance plan for a custom VICIdial/Salesforce integration. It does not install a connector or demonstrate a Salesforce write. The downloadable workbook shows identity, pagination, uncertain outcomes and reconciliation using invented records.
Keep agent screen navigation, record synchronization and click-to-call as separate tasks. A web page opening in the agent browser proves neither a record write nor a completed call.
- Download and extract the complete workbook ZIP, then read the filled example first.
- Name the systems, API versions, field owners, identities and evidence needed for your own sandbox.
- Do not call the integration tested until the acceptance checklist contains actual observations.
Download the complete design workbook (ZIP)
Download the design-contract instructions
Choose the right interface for each job
A Web Form or CRM Popup provides an agent-facing link. A Call URL notifies a receiver about a supported event. The Non-Agent API supplies individual documented dialer operations. The worker uses Salesforce REST resources under a separately authorized identity.
Use Dispo for the outcome notification in this design. Start Call URL excludes manual dial calls in the official reference; the Dispo request is server-triggered. Confirm the installed mode, substitutions and endpoint before treating any local receipt test as a native VICIdial test.
Sources for this section
- VICIdial Call URL featuresVICIdial · Checked November 6, 2026
- VICIdial Non-Agent APIVICIdial · Checked November 6, 2026
Define what each direction may change
The filled field map assigns the phone and name to Salesforce; it assigns the call event to VICIdial. A business status has an explicit transition owner instead of a bidirectional mirror. Resolve conflicts before writing code.
The proposed Call_Event__c object and External_Event_Key__c field are custom design choices that must be created and permissioned in the sandbox. They are not pre-existing standard Salesforce fields.
You should seeEvery field has one owner, a direction, a validation rule and a defined behavior when the source is missing or disagrees.
Keep call control outside this record-sync exercise
Do not give a browser Salesforce client secrets or a broad dialer API credential. A future click-to-call feature needs its own user authorization, agent/session binding, supported call-control API and observed call outcome.
For this workbook, leave that capability out of the acceptance claim. The API selection guide explains how to choose a documented function without assuming that a record read establishes call-control permission.
Step 2 — Persist the event, then reconcile the remote write
Put only the minimal reviewed identifiers in the Call URL. The relay stores a receipt, validates the event and obtains any permitted notes through an authorized lookup; notes go in a protected request body to Salesforce, never in the event URL.
Use a durable event key and compare payloads. An identical repeat may reuse the existing event. A changed payload under the same key needs a correction policy. An old event must not blindly replace a newer business status. A receipt acknowledgement means the relay stored the input, not that Salesforce accepted it.
An external-ID upsert can support the dedicated event object after uniqueness is configured. Interpret the response using the pinned resource version; creation and update statuses differ. Multiple external-ID matches are a conflict to resolve, not permission to create another record.
- Before you use it
- This is a design worksheet, not executable code. Define the real call identity and whether correction revisions are separate events.
source_instance = VD_LAB_Acall_identity = reviewed_unique_call_idevent_kind = dispositionidentity = source_instance + call_identity + event_kindidentical_payload = reuse receiptchanged_payload = correction conflictremote_timeout = look up external identity before retryThis sample is a template or reading aid, not a terminal command. There is no output to show.
- Success looks like
- The same event can be reconciled after a retry, restart or lost acknowledgement without relying on an in-memory Set.
- Stop if
- Do not claim exactly-once delivery or remote mutation. The worker and remote resource still need independent acceptance tests.
Step 3 — Read every page and account for every record
The two JSON fixtures form one three-record query. Page 1 says done=false and supplies a nextRecordsUrl; page 2 says done=true. A real worker follows the returned locator on the approved instance and uses the API version supported by that org.
The worked ledger updates an existing mapping for A, resolves an ambiguous create timeout for B by finding the created identity, and quarantines C because its phone is missing. No real requests were sent. The completed arithmetic is 3 fetched = 2 mapped + 1 quarantined + 0 unresolved.
Persist a page checkpoint only after each mapping, accepted result or quarantine decision for that page is durable. Treat the last acknowledged checkpoint and the independently reconciled remote state as different facts after a crash.
You should seeAll three fictional records are accounted for, including the second page and the uncertain create; there is no blind second create.
Download fictional query page 1
Download fictional query page 2
Record the data boundary and the evidence to retain
Fill in which fields cross each boundary, who can read the bridge, how credentials rotate, what is logged, and how long each ledger is retained. Store bearer tokens and broad API secrets outside browser code and public logs.
Identifiers are not automatically anonymous. The filled workbook contains invented aliases and reserved example numbers; replace them only inside an approved sandbox and keep any real acceptance evidence private.
- Before you use it
- Use the filled CSV as a starting point and write your own named owners and observed constraints.
field owner and permitted directionsource/target schema and API versionsidentity, collision and correction policypage checkpoint and retry limitsprotected notes/body transportretention, access and recovery ownerThis sample is a template or reading aid, not a terminal command. There is no output to show.
- Success looks like
- No field or failure path is left to an unstated implementation assumption.
- Stop if
- A blank decision is a blocker for the corresponding write path; it is not an instruction to choose a permissive default.
Step 4 — Run the sandbox acceptance and recovery checklist
Test a valid record, second page, duplicate event, changed same-key event, late event, create timeout, identity collision, missing phone and worker restart. Record the exact request classification and independently read the resulting state.
On failure, pause the worker or restore the prior integration-field value; retain receipts, checkpoints and mappings. Reconcile pending identities before resuming. Do not delete good events to make counts agree.
You should seeThe design task is complete when the workbook has no unowned decision. The integration is complete only after its real sandbox checklist passes; that execution is not claimed here.
Checks and sources
What was checked
- The workbook is an authored design exercise with two query pages and a fully accounted three-record ledger.
- Salesforce query, external-ID upsert and response behavior were checked against the cited primary references; no Salesforce operation was executed.
- No live Salesforce schema, successful CRM write or two-way synchronization screenshot was captured. The usable deliverable is the filled design workbook and explicit sandbox acceptance plan, not a demonstrated cloud integration.
Primary references
Sources
- VICIdial Call URL featuresVICIdial · accessed November 6, 2026
- VICIdial Non-Agent APIVICIdial · accessed November 6, 2026
- Salesforce REST query and paginationSalesforce · accessed November 6, 2026
- Salesforce upsert by external IDSalesforce · accessed November 6, 2026
- Salesforce REST response codesSalesforce · accessed November 6, 2026