Changing a registered phone with update_phone

Once an extension is registered, you sometimes need to change it: a new SIP password, a different caller ID, or a softphone that should auto-answer. You can do all of that by hand in the admin screen, or you can script it with the update_phone function. It edits a phone entry that already exists, and it can also delete one.

What update_phone does

This call belongs to the Non-Agent API, the HTTP endpoint that handles administrative jobs like managing extensions and lists. A registered phone is a row that maps a SIP peer (the credentials your device uses to log in) to a VICIdial extension. The first time you create that row you use add_phone; after that, update_phone is how you change it. It targets one phone at a time, identified by its extension and the server it lives on.

Whether the phone is a Hardphone (deskphone) sitting on a desk or a Softphone running on a laptop, the same call edits the database row behind its Phone registration. The device picks up the new settings the next time the conf files refresh.

Permissions you need

The API user making the call must have user_level set to 8 or higher and "ast admin access" enabled. Without that, the system refuses the request. If you have not set up an API user yet, start with our guide on API user levels and permissions.

Required and editable fields

Two fields are always required so the function knows which phone you mean:

• extension — 2 to 100 characters
• server_ip — 7 to 15 characters, must be a valid server IP

Everything else is something you can change. Common ones are phone_pass, protocol (one of IAX2, SIP, Zap, EXTERNAL), outbound_cid (6 to 18 digits), phone_full_name, and local_gmt. To turn a phone into a webphone, set is_webphone=Y; to make it answer automatically, set webphone_auto_answer=Y. To clear a field like the voicemail email, send --BLANK-- as its value.

An example call

This updates the SIP password and outbound caller ID on extension 55000:

http://your-server/vicidial/non_agent_api.php?source=test&function=update_phone&user=6666&pass=1234&extension=55000&server_ip=192.168.198.5&protocol=SIP&phone_pass=test&outbound_cid=7275551212

On success you get back:

SUCCESS: update_phone PHONE HAS BEEN UPDATED - 6666|cc100|10.0.9.8|SIP|100

Deleting a phone

Add delete_phone=Y with just the extension and server_ip to remove the entry entirely:

http://your-server/vicidial/non_agent_api.php?source=test&function=update_phone&user=6666&pass=1234&extension=55000&server_ip=192.168.198.5&delete_phone=Y

A delete returns SUCCESS: update_phone PHONE HAS BEEN DELETED - 6666|cc100|10.0.9.8|. If the API user lacks delete rights you instead get NOTICE: update_phone USER DOES NOT HAVE PERMISSION TO DELETE PHONES - 6666|7878.

How the function validates the call

flowchart TD
  A[Call update_phone] --> B{User level 8 plus ast admin?}
  B -- no --> C[ERROR no permission]
  B -- yes --> D{extension and server_ip present?}
  D -- no --> E[ERROR must use all required fields]
  D -- yes --> F{Phone exists on server?}
  F -- no --> G[ERROR phone does not exist]
  F -- yes --> H{delete_phone equals Y?}
  H -- yes --> I[SUCCESS phone has been deleted]
  H -- no --> J[SUCCESS phone has been updated]

Common errors

• ERROR: update_phone USER DOES NOT HAVE PERMISSION TO UPDATE PHONES - 6666|0
• ERROR: update_phone YOU MUST USE ALL REQUIRED FIELDS - 6666||
• ERROR: update_phone SERVER DOES NOT EXIST - 6666|10.0.9.9
• ERROR: update_phone PHONE DOES NOT EXIST ON THIS SERVER - 6666|10.0.9.8|cc101
• ERROR: update_phone NO UPDATES DEFINED - 6666|0

That last one means you sent only the required fields and nothing to change. The pipe-delimited tail of each line echoes back the offending values, which makes scripting the error handling straightforward. If you want a fuller breakdown of those strings, see how to read VICIdial API responses.

Where this fits

If you are managing a fleet of extensions across multiple servers, update_phone is the call you wire into your own provisioning scripts so the dialer database stays in sync with your phones. On VICIfast every box ships ready for this in under 40 seconds, with the API enabled and a clean admin account waiting. See our pricing to get a server you can script against today.