How to register a SIP phone with the add_phone API

Adding phones one by one in the admin screen is fine for a handful of agents. When you are onboarding a whole team, or provisioning extensions from your own back office, scripting it is faster and less error-prone. The Non-Agent API gives you add_phone to create a phone entry without touching the GUI.

What add_phone does

It adds a phone to the system - the same record the admin Phones screen creates. That record is what a SIP (Session Initiation Protocol) device, or Softphone, or Webphone authenticates against when it registers. The credentials you set here (phone_login, phone_pass, registration_password) become the login the device uses, and the extension becomes the SIP peer Asterisk knows it by.

This is the API behind Phone registration at scale: create the record, hand the device its login, and the next time it comes online it registers against your server.

Permissions you need first

This one asks for a different grant than the list functions. The API user must have user_level 8 or higher and "ast admin access" enabled - the permission that governs Asterisk-level configuration. "Modify lists" is not enough here. Permission levels are broken down in VICIdial API user level and permissions.

The required fields

add_phone has a long required list because a phone is more than a username. The ones you must send:

• extension - the extension number, 2 to 100 characters
• dialplan_number - the dialplan entry, 1 to 20 digits
• voicemail_id - the voicemail box, 1 to 10 digits
• phone_login and phone_pass - the device's registration credentials
• server_ip - must be a valid server_ip already in the system
• protocol - one of IAX2, SIP, Zap, or EXTERNAL
• registration_password, phone_full_name, local_gmt (timezone, default -5.00), and outbound_cid

Optional fields let you set phone_context (default 'default'), email, admin_user_group, a template_id, and the webphone flags is_webphone and webphone_auto_answer.

Example call

http://your-server/vicidial/non_agent_api.php?source=test&function=add_phone&user=6666&pass=1234&extension=55000&dialplan_number=55000&voicemail_id=55000&phone_login=55000&phone_pass=test&server_ip=192.168.198.5&protocol=SIP&registration_password=test&phone_full_name=Extension+55000&local_gmt=-5.00&outbound_cid=7275551212

Note the + signs standing in for spaces in phone_full_name - URL-encode any field that contains a space.

How the call flows

sequenceDiagram
    participant C as Your script
    participant API as non_agent_api.php
    participant DB as VICIdial DB
    C->>API: add_phone (extension, login, server_ip...)
    API->>API: check user_level and ast admin access
    API->>DB: server_ip valid?
    API->>DB: phone_login free?
    DB-->>API: ok
    API->>DB: insert phone row
    API-->>C: SUCCESS: PHONE HAS BEEN ADDED

Reading the response

A successful add returns: SUCCESS: add_phone PHONE HAS BEEN ADDED - 6666|cc100|10.0.9.8|SIP|100. The errors you will run into:

• ERROR: add_phone USER DOES NOT HAVE PERMISSION TO ADD PHONES - 6666|0 - the API user lacks user_level 8 or "ast admin access".
• ERROR: add_phone YOU MUST USE ALL REQUIRED FIELDS - 6666|1000||||||||||| - one of the many required fields is missing.
• ERROR: add_phone SERVER DOES NOT EXIST - 6666|10.0.9.9 - the server_ip you sent is not a registered server.
• ERROR: add_phone PHONE ALREADY EXISTS ON THIS SERVER - 6666|10.0.9.8|cc101 - that extension is taken on that server.
• ERROR: add_phone PHONE LOGIN ALREADY EXISTS - 6666|cc100 - the phone_login is already in use; pick another.
• ERROR: add_phone YOU MUST USE A VALID TIMEZONE - 6666|-5 - local_gmt needs the full format, e.g. -5.00.

Once the record exists, the device can register and you have a working extension. To edit or delete one later you use update_phone, the sibling function on the next page of the same API. Loading numbers and leads onto a Lead list uses the same call pattern, covered in how to add a lead with add_lead.

Run it on a hosted box

The Non-agent API ships with every VICIdial install, so add_phone is available the moment your server comes up in under 40 seconds. VICIfast runs the API for you on every plan - see pricing.