Cloning an agent account with copy_user

You have one agent account set up exactly the way you like - the right group, the right inbound queues, the right defaults. Now you need twenty more just like it. Rebuilding each one field by field is tedious. The copy_user function takes an existing account and stamps out a new one from it in a single call.

An Agent is a VICIdial user account that logs in to handle calls. This call from the Non-agent API, the back-office set that works on the database rather than a live session, copies one existing user to a new login ID and name.

The four fields it needs

copy_user is leaner than add_user because most settings come from the account you are copying. You supply four required fields:

• agent_user - the new login ID, 2 to 20 characters. Send AUTOGENERATED to have VICIdial pick one.
• agent_pass - the new account's password, 1 to 20 characters.
• agent_full_name - the new person's display name, up to 50 characters.
• source_user - the existing login ID to copy from. It must already exist on the system.

Here is the full call, cloning user 5555 into a new login 1000:

curl "http://server/vicidial/non_agent_api.php?source=test&function=copy_user&user=6666&pass=1234&agent_user=1000&agent_pass=9999&source_user=5555&agent_full_name=Copy+Person"

On success the response begins with SUCCESS and echoes the new login and the source it was copied from. The new account inherits the source user's settings - including its User group and its selected inbound queues - so you only set what is genuinely new.

Notice what is not in the field list. There is no agent_user_level and no agent_user_group, because copy_user takes both from the source account. That is the whole point of the call: you clone a known-good template and the level, group, inbound-queue selections, and other settings come along for free. Setting up that one template account carefully is what makes every later clone safe.

Watch the error responses to catch a bad request early. SOURCE USER DOES NOT EXIST means the source_user you named is not on the system, often a typo. USER ALREADY EXISTS means the new login is taken, so pick another or send AUTOGENERATED. And like add_user, you cannot copy into a level higher than your own API user's level - the spec returns a clear error rather than silently downgrading the new account.

How the call resolves

flowchart TD
  A[copy_user request] --> B{API user can copy users}
  B -->|No| C[ERROR no permission]
  B -->|Yes| D{All required fields present}
  D -->|No| E[ERROR must use all required fields]
  D -->|Yes| F{Source user exists}
  F -->|No| G[ERROR source user does not exist]
  F -->|Yes| H{New login already taken}
  H -->|Yes| I[ERROR user already exists]
  H -->|No| J[SUCCESS user has been copied]

copy_user or add_user

Reach for copy_user when a template account already carries the settings you want to repeat - the same group, the same Ingroup selections, the same call queue that routes inbound work to a set of agents. Reach for add_user when each account is genuinely different, or when no good template exists. The add_user route is covered in our add_user guide.

Both calls are part of the same API (application programming interface), so it is worth reading the VICIdial API and AGI overview to see how user management fits with the rest of the back-office calls.

If standing up and patching the dialer is not how you want to spend your time, VICIfast gives you a managed VICIdial box with the API live from the start - see our plans to get a box in under 40 seconds.