Adjusting remote-agent lines with update_remote_agent

You set up an overflow line that VICIdial dials into when your in-house floor fills up. Now traffic is heavy and you want it taking more calls, or it is the weekend and you want it switched off entirely. The update_remote_agent function lets you make those changes from a script instead of the admin screen.

First, the term. A Remote agent is an external phone line VICIdial dials into and keeps connected, so calls can be bridged to a person who is not sitting at a softphone in the dialer. It is the way you fold an outside call center, a backup number, or an overflow desk into your campaign without giving each seat a login.

update_remote_agent is part of the Non-agent API (the back-office HTTP interface served by non_agent_api.php that manages records rather than driving a live call). It updates an existing remote-agent entry. It does not create one, so the line has to be defined already before you can adjust it.

Permissions and fields

The API user needs a user level of 8 or higher and the "modify remote agents" permission. Only one field is required: agent_user, the login of the remote-agent entry (2 to 20 characters). After that, three optional fields do the work:

• status accepts ACTIVE or INACTIVE only. This is your on-off switch.
• campaign_id (1 to 8 characters) points the line at a valid Campaign (an outbound dialing project), so you can move the overflow to whichever campaign is busy.
• number_of_lines (1 to 20) sets how many simultaneous calls VICIdial will bridge to that remote line, which directly shapes its Lines per agent (how many calls a single seat handles at once).

Two example calls show both common moves. The first re-points a line and gives it one line of capacity:

curl "http://server/vicidial/non_agent_api.php?source=test&function=update_remote_agent&user=6666&pass=1234&agent_user=2424&number_of_lines=1&campaign_id=TESTCAMP"

The second simply parks it for the night:

curl "http://server/vicidial/non_agent_api.php?source=test&function=update_remote_agent&user=6666&pass=1234&agent_user=2424&status=INACTIVE"

How status decides the outcome

flowchart TD
    A[Call update_remote_agent] --> B{Remote agent exists}
    B -- No --> C[REMOTE AGENT DOES NOT EXIST]
    B -- Yes --> D{Status value}
    D -- ACTIVE already active --> E[NOTICE already ACTIVE]
    D -- INACTIVE already inactive --> F[NOTICE already INACTIVE]
    D -- Change needed --> G[USER HAS BEEN UPDATED]
    D -- Not ACTIVE or INACTIVE --> H[STATUS MUST BE ACTIVE OR INACTIVE]

Reading the response

A real change returns one line:

SUCCESS: update_remote_agent USER HAS BEEN UPDATED - 6666|7878

The errors are blunt and useful: REMOTE AGENT DOES NOT EXIST if the login is wrong, YOU MUST USE A VALID NUMBER OF LINES if number_of_lines is out of range, YOU MUST USE A VALID CAMPAIGN ID if the campaign is not real, and NO UPDATES DEFINED if you sent only the required field with nothing to change. Each response ends with the Agent login it acted on so you can confirm you hit the right line.

update_remote_agent is the close cousin of the call that edits ordinary accounts. If you have not met that one, the update_user guide covers the same shape of request for regular agents, and the VICIdial API and AGI overview ties the whole non-agent family together.

Scripting overflow up and down on a schedule is the kind of thing a managed box should let you do from minute one, and on VICIfast the API is enabled and locked to your subdomain at provision time. See what each plan includes on our pricing page.