Editing a phone group with update_phone_alias

After you have built a phone alias, the membership changes over time: someone swaps a desk phone, you retire a softphone, or you just want a clearer name. The update_phone_alias function edits an existing group, and with one extra flag it deletes the group entirely. It is the companion to add_phone_alias and works the same way over HTTP.

What you can change

An alias bundles a set of phone logins under one ID and a friendly name. update_phone_alias lets you rewrite the comma-separated list of logins or rename the group. You target the alias by its alias_id, then send the new values. This runs through the Non-Agent API, the administrative HTTP endpoint that also handles extensions and lists. The logins you reference, whether a Hardphone (deskphone) or a Softphone, must already exist with a valid Phone registration before you can add them to the group.

Permissions

The API user must have user_level set to 8 or higher and "ast admin access" enabled. This is the same level every phone-management call on the API (application programming interface) requires, so if add_phone_alias works for you, this one will too. For a refresher on setting that up, see VICIdial API user levels and permissions.

Required fields

• alias_id — 2 to 20 characters, the group you are editing
• phone_logins — 2 to 255 characters, logins separated by commas
• alias_name — 1 to 50 characters

There is one settings field, delete_alias (Y or N, default N). Setting it to Y removes the alias from the system. When deleting, you only need the alias_id.

One thing to keep in mind: this is a full replace, not a merge. The phone_logins value you send becomes the new membership in its entirety. If you want to add one login to a group of three, you send all four in the comma list, not just the new one. Read the current logins first, append, then send the complete set. That avoids the surprise of quietly dropping logins you meant to keep.

Editing the group

This renames alias xyz100 and sets its logins to 100a and 100b:

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

A success returns:

SUCCESS: update_phone_alias PHONE ALIAS HAS BEEN UPDATED - 6666|x100|

Deleting the group

To remove an alias, send just the ID with the delete flag:

http://your-server/vicidial/non_agent_api.php?source=test&function=update_phone_alias&user=6666&pass=1234&alias_id=xyz100&delete_alias=Y

That returns SUCCESS: update_phone_alias PHONE ALIAS HAS BEEN DELETED - 6666|x100|. Deleting the alias does not delete the phones it pointed at; those rows stay put.

How the function decides

flowchart TD
  A[Call update_phone_alias] --> B{User level 8 plus ast admin?}
  B -- no --> C[ERROR no permission]
  B -- yes --> D{alias_id given?}
  D -- no --> E[ERROR must use all required fields]
  D -- yes --> F{Alias exists?}
  F -- no --> G[ERROR phone alias does not exist]
  F -- yes --> H{delete_alias equals Y?}
  H -- yes --> I[SUCCESS alias has been deleted]
  H -- no --> J{All logins exist?}
  J -- no --> K[ERROR phone does not exist]
  J -- yes --> L[SUCCESS alias has been updated]

Errors to expect

• ERROR: update_phone_alias USER DOES NOT HAVE PERMISSION TO UPDATE PHONE ALIASES - 6666|0
• ERROR: update_phone_alias PHONE ALIAS DOES NOT EXIST - 6666|x101
• ERROR: update_phone_alias YOU MUST USE A VALID ALIAS NAME - 6666|x
• ERROR: update_phone_alias PHONE DOES NOT EXIST - 6666|cc100

If you get "phone alias does not exist," you are trying to update a group that was never created. Build it first with add_phone_alias. If you get "phone does not exist," one of the logins in your new comma list is not a registered phone.

Putting it to work

Pair update_phone_alias with your HR or seating system and the dialer always reflects who sits where, with no manual edits. A VICIfast box ships API-ready in under 40 seconds. See our pricing to spin one up.