How to transfer a remote-agent call into an in-group via the API

INGROUPTRANSFER is the stage to use when you want to move a call from a Remote agent into a VICIdial Ingroup queue. Unlike transferring to a direct number, an in-group transfer puts the caller into a waiting queue where any available agent in that in-group can pick it up. Your app supplies the in-group name in the ingroup_choices parameter and VICIdial handles the routing from there.

When to use INGROUPTRANSFER

Use this stage when the call needs to reach a team rather than a specific person. For example, a remote agent on a sales call determines the caller needs billing support and your app routes the call into a BILLING in-group, where the next available billing agent answers. This is different from EXTENSIONTRANSFER, which sends the call to a single fixed number. The Closer pattern — passing a qualified lead to a specialist queue — maps naturally to INGROUPTRANSFER.

INGROUPTRANSFER is also the right choice when you want the caller to experience proper queue behavior: hold music, estimated wait time announcements, or skills-based routing to the next available agent. A direct number transfer goes straight to the phone; an in-group transfer goes through the full VICIdial queue engine. The Campaign that handles the in-group determines how callers are queued and routed to agents.

Parameters required

• source, user, pass — standard API auth. The user account needs level 4 or higher with Agent API Access.
• function=ra_call_control — selects the ra_call_control function.
• stage=INGROUPTRANSFER — tells VICIdial this is a queue transfer.
• value — the call ID for the active call on the remote agent, received when the call was first routed to the agent.
• agent_user — the VICIdial username of the remote agent on the call.
• ingroup_choices — a single active in-group name. This must match an in-group that exists and is active on the server. You can also pass the reserved value DEFAULTINGROUP to route to the originating in-group automatically.
• status (optional) — a Disposition code up to 6 characters. Defaults to RAXFER if not provided.

Request flow

sequenceDiagram
  participant App as External App
  participant API as agc/api.php
  participant VD as VICIdial
  participant IG as In-Group Queue
  App->>API: GET api.php?stage=INGROUPTRANSFER&ingroup_choices=SALESLINE&agent_user=1028&value=Y...
  API->>API: Validate auth and parameters
  API->>VD: Find agent session and active call
  VD-->>API: Agent logged in, call confirmed
  API->>VD: Route call to in-group SALESLINE
  VD->>IG: Call enters SALESLINE queue
  VD-->>API: Transfer complete
  API-->>App: SUCCESS: ra_call_control transferred - 1028|Y...|SALESLINE

Error responses specific to this stage

The most common error for INGROUPTRANSFER is ERROR: ingroup is not valid. This fires when the name you passed to ingroup_choices does not match any active in-group on the server. In-group names in VICIdial are case-sensitive, so SALESLINE and SalesLine are treated as different names. Verify the exact name in your VICIdial admin panel under In-Groups before hardcoding it in your integration. The other standard errors — no user found, user not logged in, no active call found — apply here the same as for other stages.

The DEFAULTINGROUP option is explained in detail in when to use DEFAULTINGROUP in an in-group transfer. For a broader view of how remote agents and in-groups connect in VICIdial, read the remote agents guide. To get a fully configured VICIdial system running in under 40 seconds, check our managed VICIdial plans.