Guide
How Do I Integrate a CRM With VICIdial? Patterns and Steps
How to integrate VICIdial with a CRM — lead push via the Non-Agent API, screen pop with web forms, click-to-call via the Agent API, and disposition write-back.
- Author
- JH Dialer Engineering Team
- Published
- Reading time
- 2 min read
On this page
Step 1: Decide which system owns which data
Before any code, agree:
- Where leads are created (CRM, web forms, lead vendors).
- Where call outcomes must end up.
- Which fields agents must see during a call.
- What happens on duplicates and failures.
Step 2: Push leads into VICIdial
The Non-Agent API accepts HTTP requests to add or update leads — for example the add_lead and update_lead functions — specifying the target list and lead fields. A CRM workflow, webhook or small middleware service calls it whenever a lead is created or changes.
Use a dedicated API user with only the permissions it needs, and restrict access to the API by IP.
Step 3: Show the CRM record during the call
VICIdial campaigns can open a web form URL with variables substituted from the current call — lead ID, phone number, vendor ID and others. Point it at the CRM record page and the agent sees the right customer as the call connects. The CRM can also be embedded in a panel of the agent screen.
Step 4: Click-to-call from the CRM
The Agent API lets an external application control a logged-in agent’s session — for example asking VICIdial to dial a number for that agent. A “Call” button in the CRM calls a small server-side endpoint, which calls the Agent API. Keep API credentials on the server, never in the browser.
Step 5: Write outcomes back
Campaigns can trigger a Dispo Call URL after each disposition, passing status, lead ID, call length and other variables. Your integration receives it and updates the CRM — status, notes, recording link and next action.
Step 6: Handle failures
Production integrations need retries, logging and alerts. CRMs enforce API rate limits; networks fail. A queue between VICIdial and the CRM prevents lost updates.
Testing checklist
- New lead appears in the right list within the expected time
- Duplicate leads handled per your rules
- Screen pop opens the correct record for inbound and outbound calls
- Click-to-call works only for logged-in agents
- Every disposition reaches the CRM, including after a temporary outage
Prefer someone else to build it? See our CRM integration service.
Frequently asked questions
Do I need a developer to integrate a CRM with VICIdial?
Simple screen pops can be configured without code. Two-way sync, click-to-call and reliable error handling generally need development work.