How to add a phone with the add_phone API

You can add a phone entry to VICIdial without clicking through the admin screen. The add_phone function lets you create a new phone over a plain HTTP request, which is the fastest way to onboard a softphone or feed a provisioning script. This is part of the Non-agent API, the back-end set of calls meant for administration rather than live agent control.

The whole thing is one URL hitting non_agent_api.php on your server, with the fields passed as query parameters. There is no special client to install — curl or any HTTP library works.

Who can call it

The API (application programming interface) user you authenticate with must have a user_level of 8 or higher and "ast admin access" enabled. Without that, the call comes back with USER DOES NOT HAVE PERMISSION TO ADD PHONES. Keep these credentials separate from the ones used by the Agent API, which agents use during a live session — phone administration is a different permission entirely.

The required fields

add_phone refuses to run unless every required field is present. Miss one and you get YOU MUST USE ALL REQUIRED FIELDS. The required set:

• extension — 2 to 100 characters, the dial string for this phone (this is the Extension the agent or device registers as)
• dialplan_number — 1 to 20 digits
• voicemail_id — 1 to 10 digits
• phone_login and phone_pass — the device login and its password
• server_ip — 7 to 15 characters, and it must match a real server that exists
• protocol — one of IAX2, SIP, Zap, or EXTERNAL
• registration_password, phone_full_name, local_gmt, and outbound_cid

For most setups protocol is SIP, since a Softphone like Zoiper or a desk phone speaks SIP. The server_ip has to point at a server already in the system, or the call returns SERVER DOES NOT EXIST.

How the call flows

flowchart TD
  A[Build add_phone URL] --> B[non_agent_api.php]
  B --> C{User level 8 plus admin access}
  C -->|No| D[Permission error]
  C -->|Yes| E{All required fields present}
  E -->|No| F[Missing fields error]
  E -->|Yes| G{Server and login valid}
  G -->|No| H[Server or login error]
  G -->|Yes| I[Phone has been added]

A few optional fields are worth knowing: phone_context defaults to default, is_webphone marks the entry as a browser phone, and on_hook_agent controls whether the phone is treated as on-hook when an agent logs in with it. You can leave them out and take the defaults.

Reading the response

On success you get SUCCESS: add_phone PHONE HAS BEEN ADDED followed by the login, server IP, and protocol. Errors are just as readable: an invalid timezone, a duplicate login, or a server that does not exist each come back as a plain text line you can parse in a script. For a full walk-through of what a phone entry contains, see the phones and aliases guide. If you prefer the admin screen, the steps are in how to add a new phone.

VICIfast provisions and manages the dialer so the API is ready the moment your server is — see pricing.