When the webphone won't register: a step-by-step checklist

The agent loads the screen, the webphone tries to come up, and it never shows a registered state. No calls can land because the phone never told the server it is reachable. The browser-based softphone talks to Asterisk over a WebSocket carrying SIP, so registration depends on that socket connecting and a valid SIP login behind it.

A Webphone is just a SIP endpoint that runs in the browser. Its registration, the Phone registration step that announces the extension to the server, fails for a small set of reasons. Walk them in order.

How webphone registration works

The browser opens a secure WebSocket to the box, usually on the WSS port, and tunnels SIP through it. The server's SIP registrar then checks the credentials. If the socket can't open, the cert is untrusted, or the secret is wrong, registration never completes and the phone sits idle.

The quickest way to split the problem in two is the browser developer console. If you see the WebSocket fail to connect, the cause is the URL, the cert, or a blocked port, and the SIP secret is irrelevant because nothing ever reached the registrar. If the socket connects but you see a rejected register, the socket is fine and the credentials are wrong. Decide which half you are in before touching settings.

flowchart TD
  A[Browser opens WSS] --> B{Cert trusted}
  B -- No --> X[Socket fails]
  B -- Yes --> C{Port reachable}
  C -- No --> X
  C -- Yes --> D{SIP secret correct}
  D -- No --> Y[401 register rejected]
  D -- Yes --> E{Mic permission granted}
  E -- No --> Z[Registers but no audio]
  E -- Yes --> F[Registered]

Check these in order

1. WSS URL and port. The webphone needs the correct secure WebSocket URL pointing at the box's FQDN on the right port. A typo in the host, a plain ws instead of wss, or the wrong port and the socket never opens. Confirm it in the phone settings against the server's real hostname.
2. Certificate valid. The WSS connection needs a trusted TLS certificate for that hostname. An expired or self-signed cert makes the browser silently refuse the socket. The SIP over TLS layer is what carries the WebSocket, so a cert problem looks like a dead phone, not an error.
3. SIP secret correct. The registration sends the extension's username and secret to the SIP registrar. If the secret does not match the phone entry on the server, registration is rejected. Re-check the conf secret on the phone matches the one in the server.
4. Port not blocked. A corporate firewall or proxy can block the WSS port outright. Test from the agent's actual network, not just yours.
5. Microphone permission. The browser must be granted mic access. The phone can register but have no audio if the page never got permission, so confirm the browser prompt was accepted and the site is served over HTTPS.

Five checks and the phone almost always comes back. For the broader approach, see the troubleshooting playbook. To confirm whether the server actually saw the register attempt, the Asterisk debug page shows live registry state. If you would rather the cert and WSS endpoint just work, VICIfast issues the TLS cert and wires the webphone for you.