Click-to-dial from your app with external_dial

The external_dial function is the workhorse of the Agent API. It places a manual dial call on a logged-in Agent screen, which is exactly what you want when a user clicks a phone number in your CRM and expects the agent to start dialing. If the Agent API pattern is new to you, read how to call the Agent API first, then the VICIdial API overview for the full set.

When you'd use it

Click-to-dial is the headline use: a record opens in your app, the agent clicks call, your backend fires external_dial, and the number rings out on the agent's screen. It pauses the agent after their current call, enters the number, and dials. You can ask it to search the campaign's Lead list for a matching record or create a fresh one, and you can preview the lead instead of dialing immediately. It is also how you script a power-through-a-list flow from outside VICIdial.

How the call works

sequenceDiagram
  participant App
  participant API as agent_api.php
  participant V as VICIdial
  participant Agent as Agent screen
  App->>API: external_dial (agent_user, value, search)
  API->>V: verify agent is logged in
  V->>Agent: pause after current call
  V->>Agent: load number and dial
  V-->>App: SUCCESS external_dial function set

VICIdial waits for any active call to finish, pauses the agent, enters the number you passed, and dials it on the agent screen. The HTTP response comes back as soon as the action is queued, not when the customer answers.

Parameters

• value — any valid phone number to dial, or MANUALNEXT to mimic the Dial Next Number button. Either value or lead_id is required.
• lead_id — any valid lead_id. If both value and lead_id are given, lead_id wins.
• phone_code — the country code, like 1 for USA/Canada or 44 for the UK.
• search — YES searches the campaign's vicidial_list for the number and opens that lead; NO creates a new record for the call.
• preview — YES previews the lead without dialing; NO dials immediately.
• focus — YES shifts browser focus to the vicidial.php agent screen with an alert; NO leaves focus alone.
• vendor_id — optional, any valid vendor lead code.
• dial_prefix — optional prefix added to the front of the dial string for this call.
• group_alias — optional outbound caller ID drawn from an existing group alias.
• alt_dial — optional, when using lead_id, dial the ALT number, the ADDR3 number, or SEARCH within the lead.
• dial_ingroup — optional, place the call as an in-group outbound call.
• outbound_cid — optional caller ID for this call. Only works if Outbound Call Any CID is enabled in System Settings.

An example call

http://server/agc/api.php?source=test&user=6666&pass=1234&agent_user=1000&function=external_dial&value=7275551212&phone_code=1&search=YES&preview=NO&focus=YES&dial_prefix=88&group_alias=DEFAULT

A good result looks like SUCCESS: external_dial function set - 7275551212|6666|1|YES|NO|YES|123456|1232020456|9|TESTING|7275551211|. The tail echoes the number, the API user, the phone_code, your search and preview and focus flags, and the lead_id that was used. Parse the SUCCESS prefix and log the rest.

Gotchas worth knowing

The agent has to be logged in, or you get ERROR: agent_user is not logged in. The agent also needs permission to place manual dial calls, or you get ERROR: agent_user is not allowed to place manual dial calls. Two more sharp edges: outbound_cid only works when Outbound Call Any CID is on, and if you fire the same number twice before the first one clears you get ERROR: phone_number is already in this agents manual dial queue. A defined Dial prefix that points at the wrong trunk is the usual cause of a call that connects nowhere. If you instead want to set a result rather than place one, see the external_status guide.

Every VICIfast box exposes the Agent API over HTTPS on a Branded subdomain from the moment it is provisioned, so wiring click-to-dial into your CRM is a same-day job. See our pricing to get a server.