How to create an agent account with the add_user API

Your HR system just onboarded ten new hires, and every one of them needs a VICIdial login before their first shift. Creating ten accounts by hand in the admin screen is slow and error-prone. The add_user function lets your own software create each account with a single call.

An Agent in VICIdial is a user account that logs in to take or place calls. This call from the Non-agent API, the back-office set that acts on the database rather than driving a live session, adds one new user to the system.

The five required fields

Five fields are mandatory. Note that these use an agent_ prefix to distinguish the new account from the API user (the user and pass that authorize the call):

• agent_user - the new login ID, 2 to 20 characters. Send AUTOGENERATED to let VICIdial pick one.
• agent_pass - the account password, 1 to 20 characters.
• agent_user_level - a single digit, 1 through 9, controlling what the account can do.
• agent_full_name - the person's display name, up to 50 characters.
• agent_user_group - the User group the account belongs to, which must already exist.

A user group is a label that bundles accounts together for permissions and reporting. Here is a minimal call:

curl "http://server/vicidial/non_agent_api.php?source=test&function=add_user&user=6666&pass=1234&agent_user=1000&agent_pass=9999&agent_user_level=1&agent_full_name=Testing+Person&agent_user_group=AGENTS"

Spaces in the full name become a plus sign in the URL, as Testing+Person shows. On success the response begins with SUCCESS and echoes the new login, level, and group.

Optional fields worth setting

Several optional fields save you a second trip to the admin screen. phone_login and phone_pass tie the account to a phone. hotkeys_active turns on Hotkeys, the keyboard shortcuts agents use to disposition calls fast. And in_groups takes a pipe-delimited list such as SALESLINE|SUPPORT to pre-select which inbound groups the agent can take calls from. An Ingroup is one of those inbound queues that routes calls to a group of agents.

There are five custom_one through custom_five fields too, each up to 100 characters, for stashing your own reference data on the account - an HR ID, a team name, a region. They have no effect on dialing; they are storage you can read back later. And wrapup_seconds_override sets a per-agent wrap-up time, the pause after a call ends before the next one starts, if you want this account to differ from the campaign default.

How the call resolves

flowchart TD
  A[add_user request] --> B{API user can add users}
  B -->|No| C[ERROR no permission]
  B -->|Yes| D{All five required fields present}
  D -->|No| E[ERROR must use all required fields]
  D -->|Yes| F{User group exists}
  F -->|No| G[ERROR user group does not exist]
  F -->|Yes| H{Login already taken}
  H -->|Yes| I[ERROR user already exists]
  H -->|No| J[SUCCESS user has been added]

If you are creating many accounts that share the same settings, building each one from scratch is wasteful. The copy_user call clones an existing account instead - see our guide to copy_user for that shortcut.

For the full set of back-office calls, see the VICIdial API and AGI overview. And if you would rather not stand up and maintain the dialer yourself, VICIfast gives you a managed VICIdial box with the API ready to call - see our plans to get one in under a minute.