How to create a phone alias with the add_phone_alias API

A phone alias groups several phone logins under one name. It lets a single alias stand in for a set of phones, which is handy when an agent moves between devices or you want one handle to cover a small group. The add_phone_alias function creates one over a plain HTTP request, the same way the rest of the Non-agent API works.

As with the other phone calls, the API (application programming interface) user needs user_level 8 or higher and "ast admin access" enabled.

The three required fields

add_phone_alias takes only three fields, all required:

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

The phone_logins field is the heart of it. You list the existing logins you want under the alias, comma-separated, like 100a,100b. Each one has to be a phone that already exists — if any login in the list is missing, the call returns PHONE DOES NOT EXIST and the alias is not created. So add the phone entries first, then group them.

How an alias resolves

flowchart LR
  A[alias_id login] --> B[Phone alias lookup]
  B --> C[Member login 100a]
  B --> D[Member login 100b]
  C --> E[Real phone entry]
  D --> F[Real phone entry]

Each member login still points at a real phone entry, so the alias is a layer on top of existing phones rather than a replacement for them. The members keep their own Extension and registration details; the alias just groups them under one name.

Editing and removing an alias

There is a matching update_phone_alias function. It takes the same three fields to change the name or the member logins, and a delete_alias=Y flag to remove the alias entirely. Editing returns PHONE ALIAS HAS BEEN UPDATED, removing returns PHONE ALIAS HAS BEEN DELETED. A successful create returns PHONE ALIAS HAS BEEN ADDED followed by the alias name and the logins it covers.

To change which phones an alias covers, send update_phone_alias with the new phone_logins list — it replaces the membership rather than merging into it, so always send the full set you want, not just the additions. Like creating, every login you name has to exist, or you get PHONE DOES NOT EXIST and the change is rejected. Deleting an alias only removes the grouping; the underlying phone entries stay exactly as they were.

If you are new to how a phone is stored in the first place, start with what a phone entry is, then the full phones and aliases guide.

VICIfast runs the dialer so these calls are ready out of the box — see pricing.