Ending an agent's call with external_hangup

The external_hangup function is part of the VICIdial Agent API — the family of calls that act on a specific agent who is already logged into the agent screen. external_hangup does one thing: it hangs up the current customer call on that agent's session, exactly as if the agent clicked the HANGUP button themselves. It is the simplest function in the set, but it is also the one most people reach for when they want an outside system to control what an Agent is doing on a live Status (lead status) call.

When you'd use it

Reach for external_hangup when an external screen pop, CRM, or supervisor tool needs to end the live call without the agent touching the dialer. A common case is a compliance trigger: your CRM detects the customer asked to be removed, and you want the call dropped instantly. Another is a quality tool that ends a call after a fixed talk time. The function only affects the call currently on the agent's screen, so you always pair it with the agent's login name in the agent_user field. For the wider context on how these endpoints fit together, see the VICIdial API and AGI overview.

How the call works

sequenceDiagram
  participant App
  participant API as api.php
  participant V as VICIdial
  participant Agent
  App->>API: external_hangup (agent_user, value=1)
  API->>V: find logged-in agent session
  V->>Agent: drop the live customer call
  V-->>API: SUCCESS
  API-->>App: external_hangup function set

Your application sends a plain HTTP request to api.php. VICIdial validates the API user, finds the named agent's live Agent session, and triggers the same hangup the agent would. The customer call drops and the agent moves to the disposition screen, ready to mark the call result.

Parameters

• agent_user — the login of the agent whose call you want to end. Required.
• value — must be 1. That is the only valid value for this function; it is just a flag that the call should be dropped.

Like every Agent API call you also pass the standard source, user, pass, and function fields. The source string just labels where the request came from so you can trace it in the logs later.

An example call

http://server/agc/api.php?source=test&user=6666&pass=1234&agent_user=1000&function=external_hangup&value=1

A working request returns a single line: SUCCESS: external_hangup function set - 1|6666. The 6666 is the API user that made the call. If something is off you'll get an ERROR line instead — ERROR: no user found - 6666 when the API credentials are wrong, ERROR: agent_user is not logged in - 6666 when the named agent has no live session, or ERROR: external_hangup not valid - 1|6666 if you sent a value other than 1. Read the line, don't just check the HTTP code.

Gotchas and permissions

The big one: the agent must actually be logged in and on a live call. If the call has already ended, or the agent is between calls, the function has nothing to hang up. There is also a race — if you fire external_hangup at the exact moment a call is connecting, the result depends on timing, so build a small retry rather than assuming a single shot always lands. Finally, this is an Agent API call, not a Non-agent API call, so it only works against a session that exists right now. If you need user-level details on which logins are allowed to drive these calls, see VICIdial API user-level permissions.

external_hangup is small but it is the foundation for any outside tool that needs to take the wheel during a live call. If you'd rather skip the server tuning and run VICIdial on a box that provisions in under 40 seconds, see our plans. And once you've mastered ending a call, the natural next step is controlling agent state — see Non-Agent API vs Agent API to keep the two families straight.