Grouping phones with add_phone_alias

A phone alias is a way to tie several phone logins together under a single name. When an agent logs in with the alias, VICIdial knows which set of physical phones it covers. It is handy when one person rotates between a desk phone, a backup, and a softphone, and you want all of them grouped. The add_phone_alias function creates one of these groups over HTTP.

What an alias is for

Each row you create with add_phone normally represents one device and its Phone registration. An alias sits on top of those rows: you give it an ID, a friendly name, and a comma-separated list of the phone logins it bundles. Every login you name must already exist, whether it is a Hardphone (deskphone) on a desk or a Softphone on a laptop. The alias does not create new phones; it references the ones you have. This call runs through the Non-Agent API, the same administrative endpoint you use to manage extensions and lists.

Permissions

The API user must have user_level set to 8 or higher and "ast admin access" enabled. Anything lower and the request is rejected before it touches the database. The endpoint itself is part of the API (application programming interface) surface VICIdial exposes for administration.

Required fields

• alias_id — 2 to 20 characters, the unique handle for this group
• phone_logins — 2 to 255 characters, the phone logins separated by commas
• alias_name — 1 to 50 characters, a readable label

All three are required. If you leave any out you get ERROR: add_phone_alias YOU MUST USE ALL REQUIRED FIELDS - 6666||||.

An example call

This groups logins 100a and 100b under the alias xyz100:

http://your-server/vicidial/non_agent_api.php?source=test&function=add_phone_alias&user=6666&pass=1234&alias_id=xyz100&alias_name=XYZ+testing&phone_logins=100a,100b

The source parameter is just a short label for whatever triggered the call, which shows up in logs. A success looks like:

SUCCESS: add_phone_alias PHONE ALIAS HAS BEEN ADDED - 6666|x100|testing_x100|cc100,bb100

The tail echoes the alias ID, its name, and the logins it now contains.

How the call is checked

sequenceDiagram
  participant S as Your Script
  participant V as VICIdial API
  participant DB as Phone Table
  S->>V: add_phone_alias request
  V->>V: Check user level and admin access
  V->>V: Check all required fields present
  V->>DB: Do all phone logins exist?
  DB-->>V: Yes
  V->>DB: Insert alias row
  V-->>S: SUCCESS phone alias has been added

Errors to expect

• ERROR: add_phone_alias USER DOES NOT HAVE PERMISSION TO ADD PHONE ALIASES - 6666|0
• ERROR: add_phone_alias PHONE ALIAS ALREADY EXISTS - 6666|x101
• ERROR: add_phone_alias PHONE DOES NOT EXIST - 6666|cc100

The "phone does not exist" error is the one you hit most. It means one of the logins in your comma list is not a real phone yet. Create it with add_phone first, then retry. If the alias ID is already taken, switch to update_phone_alias instead of trying to add it again.

Related calls

To change a group after you build it, see editing a phone group with update_phone_alias. And before you can group logins, you need them to exist, which is covered in adding a phone with the add_phone API.

Where to run it

Phone aliases are a small but useful piece of fleet management, and scripting them keeps your seating chart in step with the dialer. A VICIfast server arrives provisioned and API-ready in under 40 seconds, so you can start grouping phones the same day. See our pricing to get started.