Switching an agent's inbound groups with change_ingroups

change_ingroups is the VICIdial Agent API function that changes which inbound groups a logged-in Agent is taking calls from, without the agent logging out and back in. An Ingroup is a named inbound queue — sales line, support line, callbacks — and an agent on a campaign that allows inbound calls is subscribed to some set of them. This function lets an outside tool reshape that set on the fly.

When you'd use it

Use it when a workforce or routing tool needs to move agents between queues as volume shifts. Calls piling up on the sales line? Add the sales in-group to a few support agents. Want an agent off callbacks for a while? Remove just that one in-group. You can also flip the blended flag in the same call so the agent starts or stops taking outbound auto-dialed calls alongside their inbound ones. It is the API equivalent of the supervisor reaching into Skills-based routing and re-pointing an agent's Agent session live.

How the call works

sequenceDiagram
  participant App
  participant API as api.php
  participant V as VICIdial
  participant Agent
  App->>API: change_ingroups (agent_user, value, ingroup_choices)
  API->>V: check change_agent_campaign permission
  alt allowed and ingroups exist
    V->>Agent: update selected in-groups
    V-->>App: SUCCESS change_ingroups function set
  else not allowed
    V-->>App: ERROR user not allowed to change agent in-groups
  end

VICIdial confirms the API user has permission, checks that the named in-groups exist, then updates the agent's selection. The change is live — the agent starts receiving from the new set without re-logging in.

Parameters

• agent_user — the login of the agent to change. Required.
• value — CHANGE replaces all in-groups with the ones you list, ADD only adds the listed ones, REMOVE only removes the listed ones.
• ingroup_choices — optional for CHANGE, required for ADD and REMOVE. A space-delimited list, written with plus signs in the URL, ending with a dash, e.g. +TEST_IN+SALESLINE+-
• blended — YES sets the agent to also take outbound auto-dialed calls, NO sets them to inbound only. Not applicable on MANUAL or INBOUND_MAN dial method campaigns.
• set_as_default — optional YES or NO. YES overwrites the agent's saved settings in the user modification screen. Default is NO.

An example call

http://server/agc/api.php?source=test&user=6666&pass=1234&agent_user=1000&function=change_ingroups&value=CHANGE&set_as_default=YES&blended=YES&ingroup_choices=+TEST_IN+SALESLINE+-

Success comes back as SUCCESS: change_ingroups function set - YES| TEST_IN SALESLINE -|6666. The errors map to real conditions: ERROR: campaign does not allow inbound calls if the agent's campaign isn't inbound-capable, ERROR: ingroup does not exist when you name a queue that isn't there, ERROR: ingroup_choices are required for ADD and REMOVE values if you forget the list, and ERROR: user is not allowed to change agent in-groups for the permission case below.

Permissions and gotchas

The API user making this call must have change_agent_campaign set to 1 on their user record, or every request comes back as not allowed. Worth knowing too: once you change an agent's in-groups this way, that agent can't pick their own in-groups again until they log out and back in, even if Agent Choose In-Groups is enabled for them. So don't use it casually on agents who normally self-select. For where this sits among the other endpoints see the VICIdial API and AGI overview, and for the permission flags read VICIdial API user-level permissions.

change_ingroups is how you turn static queue membership into something a routing engine can steer in real time. If you want a managed VICIdial server that provisions in under 40 seconds to build that on, see our pricing.