How to set the dialplan number for an external-phone agent

The dialplan number field on a VICIdial EXTERNAL phone record is the number the system dials when an Agent logs in. It has one rule: the value must be exactly what you would press on a phone connected to your system to reach that number, digit for digit. Include any outside-line prefix your PBX requires, include the country code if your trunk needs it, and use digits only. No formatting, no guessing — verify the number first by dialing it manually.

What VICIdial does with this field

VICIdial takes the dialplan number exactly as entered and hands it to Asterisk to dial. Asterisk then matches it against your Dialplan routing rules to decide which trunk to send it over. The string must be in the form your dialplan expects. Consumer phone apps often auto-format numbers, but Asterisk pattern matching operates on raw digit strings. A hyphen or a space in the field will either break the match or route to the wrong destination.

On many systems, dialing an external number requires a leading digit such as 9 to grab an outside line before Asterisk routes to a trunk. If that is how your system works, the 9 must be the first digit in the dialplan number field. For a US mobile number 727-555-1212 on a system with a 9 outside-line prefix, the complete dialplan number is 917275551212: 9 for the outside line, 1 for the North American country code, then the ten-digit number.

Building the dialplan number correctly

flowchart TD
  A["Start with the raw agent phone number"] --> B{"Does your system need an outside-line prefix?"}
  B -->|"Yes"| C["Prepend that digit, e.g. 9"]
  B -->|"No"| D["Skip prefix"]
  C --> E{"Does your trunk need a country code?"}
  D --> E
  E -->|"Yes — e.g. US calls need 1"| F["Prepend country code"]
  E -->|"No"| G["Use digits as is"]
  F --> H["Combine all parts into one digit string"]
  G --> H
  H --> I["Dial this string from a system phone to verify"]
  I --> J["Enter verified digit string in dialplan number field"]

The leading-9 outside-line gotcha

The most common reason an external agent's phone never rings is a missing outside-line prefix. Pick up a physical phone connected to your system and dial the agent's number the way you would in normal use. Note every digit you press, including the initial access code. That exact digit sequence is your dialplan number.

The reverse error also fails: including a 9 when the system does not need one. Asterisk attempts to match 9+number against your dialplan rules and either gets no match or hits a rule for a completely different destination. Both errors produce the same symptom — the agent logs in successfully in the browser but their phone never rings. The fix in both cases is to correct the dialplan number field and verify by dialing manually before saving.

Format rules

Enter only digits. No dashes, no parentheses, no spaces, no plus sign. VICIdial passes the string straight to Asterisk and any non-digit character will break pattern matching. The outbound caller ID shown on the agent's phone comes from the separate outbound callerid field on the same phone record — that field does not change how the number is dialed. The Dial prefix rules in your dialplan are what Asterisk uses to decide routing, so the dialplan number must conform to those rules.

If your agents are spread across different area codes or countries, each one needs its own Extension and phone record with the correct dialplan number for that location. A single phone record with a hard-coded number can only reach one phone.

If you are setting up a mobile as the agent line, see how to use a cell phone as your agent line. For the complete phone record walkthrough, see the remote agents guide. To skip building your own server, check our managed VICIdial plans — a dialer ready in under 40 seconds.