How to fix an external-phone agent whose phone never rings

An agent can work from a home or mobile phone by logging in against an external phone record instead of a Softphone — a software phone running on a computer. The agent logs in, and within a few seconds their phone should ring and connect them to the dialer. When that ring never comes, the problem is almost always one field on the phone record. Here is how to find it.

How the external phone login works

You create a phone record under Admin then Phones with a phone type of external and a client protocol of EXTERNAL. The dialplan number field holds the agent's actual phone number, written exactly as you would dial it from a phone on your system. When the agent logs into the agent interface with that phone login, the system places a call to the dialplan number and bridges them in. The ring is the system calling the agent — not the other way round — so anything wrong with that outbound number stops the ring before it starts.

The fields that stop the ring

• Dialplan number — the most common culprit. It must be the full number as dialed from your system, including any outside-line prefix such as a 9. A missing prefix means the system dials an incomplete number and nothing rings.
• Status and active account — Status must be ACTIVE and active account set to Y. An inactive record is skipped silently.
• Server IP — must match the box the agent is logging into. A mismatch and the system never tries the call.
• Client protocol — must be EXTERNAL for an external phone. If it is set to a SIP (Session Initiation Protocol) protocol — the signaling that sets up and tears down a normal registered call — the system expects a registered device, not an outbound dial.

Confirm the digits before anything else

Before you dig into protocol or server settings, dial the agent's number by hand from a phone on the dialer using the exact dialplan number you entered. If your own dial does not ring the agent, neither will the system's. If you have shell access and the digits look right, a SIP trace — a capture of the call setup messages — will show whether the call left the box and what the carrier said back.

flowchart TD
  A[Agent logs in but phone never rings] --> B{Dialplan number complete with prefix}
  B -->|No| C[Fix the number and add the prefix]
  B -->|Yes| D{Status ACTIVE and active account Y}
  D -->|No| E[Activate the record]
  D -->|Yes| F{Server IP matches the login box}
  F -->|No| G[Correct the Server IP]
  F -->|Yes| H{Client protocol is EXTERNAL}
  H -->|No| I[Set protocol to EXTERNAL]
  H -->|Yes| J[Dial the number by hand to confirm]

Most no-ring tickets end at the dialplan number with a missing prefix. For the full setup of this kind of agent, see running a VICIdial agent on a home phone, and for how external phones fit the wider remote-agent model, the remote agents guide is the place to start. If you would rather not chase phone-record fields at all, our managed plans come with the dialer already tuned and ready.