Launching the agent's webphone with webphone_url

The webphone_url function reaches into a live Agent session and either hands back the URL of that agent's Webphone or redirects the browser straight to it. It's a small but useful corner of the VICIdial Agent API when you're stitching the dialer into your own agent shell. For the full set of calls, see the VICIdial API overview.

When you'd use it

If your agents log in through a custom portal rather than the stock agent screen, you still need to get them into a working phone. With DISPLAY you can pull the per-session webphone URL into your own UI and render it however you like — an embedded frame, a button, a new tab. With LAUNCH you hand control to VICIdial and let it redirect the agent into the webphone directly. Either way, the URL is the right one for that exact session, which is the part you can't easily build by hand.

How the call works

sequenceDiagram
  participant App
  participant API as api.php
  participant V as VICIdial
  participant Agent
  App->>API: webphone_url (agent_user, value=DISPLAY)
  API->>V: read session webphone url
  V-->>App: webphone url string
  App->>API: webphone_url (value=LAUNCH)
  API->>Agent: redirect browser to webphone

The call needs a session that already exists, because the webphone URL is built from that session's data. No session, no URL — which shows up in the error responses below.

Parameters

• value — REQUIRED. DISPLAY shows only the URL for the webphone if it is enabled; LAUNCH redirects to the webphone URL to launch it.

There are no other knobs — the function is deliberately small. This is a Softphone convenience helper, not a configuration call, so you set the webphone itself up elsewhere and use this only to surface it.

An example call

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

On success the webphone URL is displayed (for DISPLAY) or the browser is launched into it (for LAUNCH). When it can't, you get specific errors: ERROR: webphone_url error - webphone url is empty - 6666 if no webphone is configured for that session, ERROR: webphone_url error - no session data - 6666 if there's no session to read from, and the usual ERROR: agent_user is not logged in - 6666 if the agent isn't on.

Gotchas to watch

The "webphone url is empty" error is the one that trips people up. It doesn't mean the API failed — it means the webphone isn't enabled for that agent, campaign, or server, so there's nothing to hand back. Check the webphone settings before you blame the call. LAUNCH performs a real browser redirect, so only fire it from a context where leaving the current page is fine; if you're inside your own embedded UI, DISPLAY plus your own frame is usually the safer choice. The closely related recording lookup function rounds out the agent-session helpers you'll often call together.

A managed VICIdial box ships with a branded webphone already wired into the agent session, so webphone_url returns a real URL from the first login. See what's included.