VICIdial phones: the complete guide

A phone entry in VICIdial is the account that an agent's device registers to so it can ring, answer, and place calls. Whether the agent uses a desk phone, a softphone on their laptop, or a web phone inside the browser, none of it works until there is a matching phone record in the admin section telling Asterisk that this device is allowed on the system. This guide walks through the whole picture: what a phone entry is, how to add one and how to change it later, the handful of fields you must fill in, the two settings people mix up most often, the protocols you can choose, and the housekeeping fields like status and server IP. It is the map for the cluster; each focused article below is the detail.

If you run a phone-heavy call center, you will touch this screen a lot, so it pays to understand it once rather than guessing every time. The order of the sections roughly follows the order you fill the form. Read it top to bottom the first time, then come back to whichever spoke article you need.

What a phone entry actually is

In VICIdial admin, ADMIN then PHONES lists every phone account on the system. Each row is one device's login: the credentials and settings that let a single piece of hardware or software connect to Asterisk and become usable by an agent. When a Softphone starts up and sends its username and secret, Asterisk checks them against the auto-generated configuration that a phone entry produced. If they match, the device registers and can take calls; if they do not, it sits there failing to connect. So a phone entry is the bridge between a real device and the dialer.

The full breakdown of the screen, the columns in the list, and what a phone record represents is in what a VICIdial phone entry is. For a SIP (Session Initiation Protocol) or IAX2 device, the entry is also what triggers Asterisk to write the matching peer config, so the act of saving a record is what makes the network side real. That bridge between record and config is the single idea everything else in this guide hangs off.

Adding a phone versus modifying one

You create a phone with the ADD A NEW PHONE link on the left menu. The add screen deliberately shows only the first 17 fields, the ones you need for a valid record, so it stays short. Everything else, the long list of webphone toggles, voicemail options, and notes fields, appears only after you save the record for the first time. That is why a freshly opened add form looks so much simpler than the modify form you see afterward: it is the same record, just revealed in two stages.

The step-by-step of creating a record is in how to add a new VICIdial phone. Once the record exists, you open it from the LIST ALL PHONES screen by clicking MODIFY, which is where the full set of options lives; that flow is covered in how to modify a VICIdial phone. A good habit is to add the minimum to save, confirm the device registers, then go back into modify and tune the extras.

The fields you must fill in to save

The add form will refuse to save unless eight things are set: the extension, the dial plan number, the server IP, the login, the password, the full name, the protocol, and the local GMT. Miss any one of them and the submission bounces back. None of these are exotic, but each has a specific meaning, and a couple of them are the source of nearly every support ticket about phones.

• Extension: the device's name as Asterisk sees it, without the protocol prefix.
• Dial Plan number: the number you dial to make this phone ring.
• Server IP: which server the phone is active on.
• Agent Screen Login and Login Password: the web agent interface credentials.
• Full Name: a label used in the list of active phones.
• Protocol: SIP, PJSIP, IAX2, Zap, or EXTERNAL.
• Local GMT: the timezone offset where the phone is physically located.

Each required field, what it does, and the values that are valid for it is laid out in the VICIdial phone required fields. Get these eight right and the record saves; the rest is refinement.

How a phone comes to life

Before going field by field, it helps to see the whole sequence from creating the record to an agent taking calls. The diagram below traces it.

flowchart TD
  A[Add a phone in Admin] --> B[Set the eight required fields]
  B --> C[Save the record]
  C --> D[Asterisk auto-creates the conf]
  D --> E[Softphone registers with login and secret]
  E --> F[Agent logs into the agent screen]
  F --> G[Phone rings and places calls]

Read it left of the save as your work and right of the save as the system's work. You fill the eight fields and submit; within about a minute Asterisk writes the matching peer configuration; the device then registers using the login and the registration secret; and once the agent logs into the agent screen, the phone is ready to ring. The one-minute gap after saving is normal and is why a brand new phone sometimes will not register for the first few seconds. EXTERNAL phones skip the conf-writing step entirely because they have no Asterisk device of their own.

Extension versus dial plan number

These two fields sit next to each other and do completely different jobs. The phone extension is the device's name as Asterisk sees it, with the protocol and slash stripped off. If a SIP phone is SIP/test101, then the extension is test101. The Extension is the identity of the device; it is not a number you dial. For SIP, PJSIP, and IAX phones this field must not contain dashes, and across all types you should stick to letters, numbers, and dashes only, with no spaces or special punctuation.

The dial plan number, by contrast, is the number you actually dial to make the phone ring. It is defined in the Asterisk Dialplan, in the extensions configuration, and it is how one device reaches another internally. The deep dive on the device name is in what the VICIdial phone extension is, and the dialable number gets its own piece in what the VICIdial dial plan number is.

There is one trap worth flagging here. Certain dial plan numbers are reserved by VICIdial for internal features, and if you try to use one you get a Reserved Dialplan Number warning. A phone with a reserved number cannot be dialed, so you must pick another. The reserved blocks include the 8159 through 8501 range and the 138300 through 138399 range. What the warning means and how to choose a safe number is in how to fix the Reserved Dialplan Number warning.

Login password versus registration password

This is the confusion that produces more failed registrations than anything else on the phone screen, so it deserves its own section. There are two password fields, and they protect two completely separate things.

The Login Password is only for logging into the web-based agent interface. It is the password the human types when they sign in to the agent screen. It has nothing to do with whether the device can connect to Asterisk.

The Registration Password, which used to be called the Conf File Secret, is the SIP (Session Initiation Protocol) or IAX secret written into the auto-generated Conf file for this phone. This is the value the device itself uses to authenticate when it registers. The limit is 20 characters, accepting letters, numbers, dashes, and underscores, and the default is the word test. The whole concept of device-side authentication is covered in what the VICIdial registration password is, and the side-by-side comparison that clears up the mix-up is in VICIdial login versus registration password.

Because the default secret is test, leaving it untouched is a real security hole; anyone who knows your extension naming can register a rogue device. A strong registration password is at least 8 characters with upper-case and lower-case letters and at least one number. How to set one that the device side will accept without breaking Phone registration is walked through in how to set a strong VICIdial phone password. When a device fails to connect, the value in the Registration string it sends almost always disagrees with this field, not with the login password.

Choosing a protocol

The Client Protocol field tells VICIdial how the device talks to Asterisk, and it changes what gets generated behind the scenes. There are five choices.

• SIP and PJSIP: the common choices for VoIP desk phones, softphones, and web phones. Saving the record auto-creates a matching peer in the Asterisk config.
• IAX2: an alternative VoIP protocol, also auto-configured on save, common between Asterisk servers.
• Zap: channelbank or hardware-card phones, which need the account set up by a system administrator first.
• EXTERNAL: remote or speed-dial numbers that place calls through the dialplan and need no Asterisk device config of their own.

For SIP (Session Initiation Protocol) and IAX phones, Asterisk writes the settings automatically within about a minute of saving the form, which is the gap shown in the diagram above. Each saved SIP peer then becomes a target the system can ring or register. EXTERNAL is the odd one out: it is really just a phones-list label for a number you want to reach, with no registration involved at all. Most call centers use SIP or PJSIP for nearly every agent and reserve EXTERNAL for the occasional permanent hotline number.

Status, active account, and server IP

A few control fields decide whether the phone can actually be used and where. The Status field is the master switch: only ACTIVE and ADMIN allow the GUI client to work, with ADMIN additionally granting access to the admin web site. Any other status blocks both the agent client and admin access, which is a clean way to disable a phone without deleting it. Active Account separately controls whether the phone appears in the list of phones inside the GUI client.

Server IP selects which server the phone is active on, which matters the moment you run more than one box. A handful of other fields round out the record without being load-bearing: Voicemail Box ties the phone to a mailbox and the VOICEMAIL button; Outbound CallerID sets the CID (caller ID) for calls placed from the web client, though the campaign caller ID overrides it once the agent logs into a campaign; Admin User Group restricts which admins can see the entry and defaults to --ALL--; Phone Type and Company are purely administrative notes. There are also voicemail-to-email options, which is where a per-phone Voicemail drop to an inbox is configured, and a long block of Webphone toggles for the built-in WebRTC phone if you use it.

A note on phone aliases

Once a phone exists, VICIdial lets you create phone aliases, which let a single agent login be spread across more than one server. The practical use is load balancing: instead of pinning every agent to one box, an alias points the same login at several servers so the system can place the agent wherever there is capacity. You do not need aliases to run a small center, and most operators never touch them, but they are the answer when one server's worth of agents is no longer enough and you want to grow without re-issuing every credential. Treat them as an advanced option you reach for only when capacity, not configuration, is the bottleneck.

Where this fits on a managed VICIdial

Everything above is the same whether you run VICIdial yourself or on a managed host. On a VICIfast-provisioned server, the admin section, the phones list, and the auto-generated Asterisk config all behave exactly as described; the difference is only in how the server got there. Standing up a new branded VICIdial takes under 40 seconds, after which you log into admin and add your phones the normal way. The dialer is yours, the carrier is yours, and the phone entries are yours to manage. See our pricing for what each plan includes, then add phones as you would on any VICIdial box.

Where to go next

This page is the overview; the focused articles go deep on each piece. Start with what a phone entry is, then learn how to add a new phone and how to modify a phone. Make sure you have the required fields right before you save.

For the two fields that trip people up most, read what the phone extension is alongside what the dial plan number is, and keep the Reserved Dialplan Number fix handy for when the warning appears. On the password side, login versus registration password clears up the confusion, the registration password explained covers the device secret, and setting a strong phone password keeps you off the default test secret.

Want working phones without standing up your own dialer? Start with a VICIfast plan and have a branded, secure VICIdial ready the same day, then add your phones in admin in minutes.