How to change agent settings with the update_user API

A walkthrough of the update_user non-agent API call, the fields it can change, the permissions it needs, and the responses it returns.

An agent's password expired, or you need to bump three people up a user level, or HR sent over five new full names to correct. You could open the VICIdial admin screen and edit each user one at a time. Or you could change them from a script. That second option is what the update_user function is for.

update_user lives in the Non-agent API (the back-office HTTP interface, served by non_agent_api.php, that manages records rather than driving a live call). You send it a single web request and it edits one existing user account. It does not create users and it does not touch a logged-in Agent session beyond a couple of live-record fields, so think of it as the bulk-edit tool for your roster.

Permissions you need first

The API user you authenticate with (not the agent you are editing) must have a user level of 8 or higher and the "modify user" permission enabled. Set those once on the API account in the admin screen. Without them, every call comes back with a permission error and changes nothing.

The one required field

Only one field is required: agent_user, the login (2 to 20 characters) of the account you want to change. Everything else is optional. You add a parameter for each thing you want to update and leave out everything you want left alone. Send no editable fields at all and you get back NO UPDATES DEFINED, which is the API telling you it had nothing to do.

Here is a call that changes a couple of basics at once:

curl "http://server/vicidial/non_agent_api.php?source=test&function=update_user&user=6666&pass=1234&agent_user=2424&agent_full_name=Testing&hotkeys_active=1&active=Y"

What you can change

The optional fields cover most of what you would edit by hand:

Identity and login: agent_pass, agent_full_name, agent_user_level (1 to 9), and email
Membership: agent_user_group, which moves the user into a User group (the permission bucket that decides which campaigns and reports a user can see)
Phone and behaviour: phone_login, phone_pass, voicemail_id, hotkeys_active, active (Y or N), and wrapup_seconds_override
Routing weight: campaign_rank and campaign_grade change this user's standing across every Campaign (an outbound dialing project) at once; ingroup_rank and ingroup_grade do the same across every Ingroup (an inbound queue calls land in)

campaign_rank and ingroup_rank apply to ALL campaigns or in-groups for the user. If you only want to set the rank and grade for one of them, add camp_rg_only=1 with a campaign_id, or ingrp_rg_only=1 with a group_id. Forget that and you will quietly re-rank the user everywhere.

Two handy extras: reset_password takes a length of 8 or more digits, generates a random password of that length, and emails it to the address you pass alongside it; in_groups takes a pipe-delimited list such as SALESLINE|SUPPORT to set which inbound groups the user is allowed to take.

How the request flows

sequenceDiagram
    participant Script
    participant API as non_agent_api.php
    participant DB as VICIdial users table
    Script->>API: update_user agent_user plus fields
    API->>API: Check API user level 8 and modify user
    API->>DB: Find agent_user
    DB-->>API: User row
    API->>DB: Apply changed fields
    DB-->>API: Rows updated
    API-->>Script: SUCCESS USER HAS BEEN UPDATED

Reading the response

A clean run returns a single line:

SUCCESS: update_user USER HAS BEEN UPDATED - 6666|7878

Rank and grade changes come back as their own NOTICE lines, like USER CAMPAIGN RANKS/GRADES HAVE BEEN UPDATED. If you pass a value the field will not accept, you get a specific complaint such as YOU MUST USE A VALID USER LEVEL, and that one field is skipped while the rest still apply. The pattern is the same across the whole interface, which is why it helps to read the line word by word the way the VICIdial API and AGI overview lays it out.

update_user only edits accounts that already exist. To create the account in the first place, use the add_user function. See how to add a user with add_user for the sibling guide.

If you are wiring this into onboarding, pair it with the add_user guide: create the account, then call update_user whenever a setting changes. That keeps your HR system and your dialer roster in step without anyone clicking through the admin screen.

Every VICIfast server ships with this API (application programming interface) (application programming interface, the URL contract your scripts call) already on and locked to your subdomain, so you can script roster changes the day you go live. See what is included on our pricing page.