How to Build Click-to-Dial With the VICIdial Agent API

Click-to-dial means an agent clicks a phone number in your CRM or internal web tool and VICIdial immediately places the outbound call on their active session — no manual dialing, no copy-pasting. The Agent API — the set of HTTP calls that control what a logged-in agent does in real time Agent API — has exactly the function for this: external_dial.

The Agent API endpoint is https://your-server/vicidial/agent_api.php. It authenticates with a user and pass parameter, the same credentials the agent uses to log in to VICIdial. The difference from the Non-Agent API is that every call here targets a specific agent session — it is not a background data operation, it directly affects what that agent sees and hears on their screen.

How the click-to-dial flow works

sequenceDiagram
  participant CRM as CRM or Web App
  participant API as agent_api.php
  participant Session as Agent Session
  participant Trunk as Outbound Trunk
  CRM->>API: external_dial phone_number agent_user
  API->>Session: verify agent is PAUSED or READY
  Session-->>API: session confirmed
  API->>Trunk: originate call to phone_number
  Trunk-->>Session: call rings on agent softphone
  API-->>CRM: SUCCESS external dial accepted

The external_dial call

Required parameters for external_dial are the agent's user and pass, the phone_number to dial, a phone_code (country prefix, default 1), and a dial_prefix (the outbound trunk prefix your VICIdial uses, typically 9 or 91). You also pass agent_user — the user ID of the agent whose session should place the call — if your CRM is calling the API on behalf of a specific agent rather than using that agent's own credentials.

curl "https://your-server/vicidial/agent_api.php\
?source=crm-ctd\
&user=1000&pass=agentpass\
&function=external_dial\
&phone_number=3055550101\
&phone_code=1\
&dial_prefix=9\
&lead_id=193715\
&campaign_id=SALES"

Pass lead_id if the call is for an existing lead in VICIdial — the agent screen will populate the lead's name, address, and notes automatically. Pass campaign_id to tie the call to a campaign so dispositions feed the right reporting buckets. If the agent is not logged in or is already on an active call, the API returns an error — your CRM should handle this gracefully by showing the agent a message rather than silently dropping the request.

Permissions the agent account needs

The user account making the Agent API call needs the allow_api_access flag set to 1 in the VICIdial Admin under Users. Standard agent-level accounts (user level 1) can make Agent API calls for their own session. If your CRM server is calling the API on behalf of an agent, it is cleaner to use a dedicated API account with the same campaign and user-level permissions as the agent, but not a shared admin credential.

Once the call ends, the agent selects a disposition Disposition from the VICIdial screen. If you want that disposition to flow back to your CRM automatically, pair click-to-dial with a disposition sync job — the pattern in the sibling post covers both directions. This creates a complete loop: CRM pushes the lead, dialer calls it, agent disposes it, CRM gets the outcome.

You can also use the Agent API to check status before dialing. The external_status function returns the agent's current status code: PAUSED, READY, INCALL, and so on. Call it first and only proceed with external_dial if the response shows the agent is available. If they are mid-call, show a message like 'Agent is on a call — try again in a moment' rather than sending a dial request that will fail silently.

After the call ends, the agent selects a disposition Disposition from the VICIdial screen as they normally would. The call gets logged in vicidial_log just like any other outbound call. If you also want that disposition to flow back into your CRM automatically, pair click-to-dial with a polling sync script that queries vicidial_log for rows tied to leads your CRM pushed. Use vendor_lead_code to join back to your CRM's record ID — this is exactly why you should pass it on the add_lead call when you first push the lead.

The click-to-dial pattern scales to call centers of any size. Each agent gets their own browser button or CRM CRM integration. Because the Agent API authenticates per agent session, concurrent clicks from different agents produce independent outbound legs with no collision — VICIdial tracks each uniquely by the Asterisk uniqueid field assigned when the call originates. You can support hundreds of simultaneous click-to-dial requests without any queueing layer on your application side, as long as the VICIdial server has the channel capacity to handle that many outbound calls. Each call is also tied to a lead record Lead in vicidial_list so the agent screen populates automatically with the contact's name and history.

For the full Agent API function list including call transfer, pause, and hangup controls, see how to call the VICIdial Agent API. For the bigger picture of API and AGI options together, see the VICIdial API and AGI overview.

If you want a server where click-to-dial works on day one with a properly configured Agent API endpoint, every VICIfast plan ships a complete VICIdial installation in under 40 seconds.