Parking and unparking a call with the park_call function

Putting a caller on hold so you can pick them up again from a known spot is what Call park does, and park_call is the Agent API function that drives it from outside the agent screen. It sends a customer or a third party to the campaign's park extension and grabs them back, with extra options for IVR parking and swapping. For where it fits among the other agent endpoints, see the VICIdial API overview.

When you'd use it

Use it when a custom button or workflow needs to park a live call instead of the agent clicking the park button by hand. Common cases are sending the customer to an on-hold IVR while the agent looks something up, holding a third party during a Three-way call, or swapping which of the two parties is on the line. Because the park and IVR extensions are defined per campaign, you don't pass them, the function reads them from the campaign the agent is logged into.

How the call works

sequenceDiagram
  participant App
  participant API as api.php
  participant V as VICIdial
  participant Cust as Customer
  App->>API: park_call (agent_user, value)
  API->>V: read campaign park extension
  V->>Cust: move to park or grab back
  V-->>API: SUCCESS function set
  API-->>App: confirmation line

You name the action in value, VICIdial looks up the right park or park-IVR extension from the campaign, and moves the chosen party. A grab pulls them back from park onto the agent's Agent session. If you're new to how these agent-side calls differ from the back-office ones, the non-agent vs agent API breakdown is worth a read.

Parameters

• agent_user — the agent's login the action runs against.
• value — REQUIRED, the action. PARK_CUSTOMER and GRAB_CUSTOMER park and retrieve the customer.
• PARK_IVR_CUSTOMER and GRAB_IVR_CUSTOMER send the customer to the park IVR; they come back after finishing it, or you grab them.
• PARK_XFER and GRAB_XFER do the same for the third-party transfer line.
• SWAP_PARK_CUSTOMER and SWAP_PARK_XFER park one party and grab the other in a single move.
• HANGUP_XFER_GRAB_CUSTOMER hangs up the third-party line and grabs the customer back from park.

An example call

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

Grabbing them back is the same call with value=GRAB_CUSTOMER. A clean run returns SUCCESS: park_call function set - PARK_CUSTOMER|6666. The errors you'll hit are ERROR: agent_user is not logged in - 6666 and ERROR: agent_user does not have a lead on their screen - 6666.

The gotcha

The agent has to have a lead on screen for a park to work; that error message is the most common surprise, because an agent can be logged in and idle without a lead loaded. The other thing to watch is the park and park-IVR extensions, they're campaign settings, so if a campaign has no park IVR configured, the IVR actions have nowhere to send the caller. Confirm those extensions exist before you build buttons around them. To move a parked call onward to another agent or number, you'll want the transfer_conference function.

Park and IVR extensions are yours to tune when you run your own box. VICIfast provisions a single-tenant VICIdial server, HTTPS and API ready, in under 40 seconds. Look at the plans to get started.