Skip to main content

​
Extensions and desk phones

An extension is the SIP identity — a username, password, and optional short extension number — that a person or device uses to place and receive calls. A desk phone is the physical handset you attach to an extension through zero-touch provisioning (ZTP). This guide covers both ends of the onboard: create the extension, register the phone, and confirm it is live. Create and maintain extensions under Voice → Extensions; provision the phones under Voice → Desk phones. Both surfaces sit next to each other on the Voice hub.

​
SIP credential types

One extension powers several ways to answer it:
  • Browser softphone — no install, no SIP details to enter. The extension opens the in-browser softphone from its detail page and connects on the owner’s signed-in dashboard session. Ideal for hot-desks and shared workstations.
  • Softphone app — a desktop or mobile app such as Zoiper, Linphone, or Bria, configured by scanning a QR code or by pasting the provisioning URI. The QR carries server, TLS port, transport, realm, SRTP, and codec fields, so nothing is typed.
  • Physical desk phone — a Polycom, Yealink, Cisco, or Grandstream handset that pulls its config from a provisioning URL (zero-touch provisioning, below) or a downloaded vendor config file.
  • PBX — an on-site PBX such as Asterisk or FreeSWITCH registers as a SIP trunk instead of an extension. Use the trunk surface for that: Connect a SIP trunk. Extensions and trunks are separate channel types — pick the right one before wiring numbers.

​
Create an extension

Open Voice → Extensions and click Create extension. The dialog and the dedicated /voice/extensions/new page are the same form, so either entry point works. Fill in:
  1. Identity — a label (required, up to 32 characters). The SIP username is derived from it — you never type one. Add an optional extension number (2–8 digits) so colleagues can dial it directly from Voice → Colleagues, plus optional free-text notes.
  2. Outbound — outbound calling allowed or not, caller-ID pick (inherit the workspace default, choose one of the workspace’s owned numbers, or fix a specific number), an optional daily spend cap, an optional concurrent-call cap, and an optional list of country codes to block. Leave a cap blank for unlimited; enter 0 to block outbound spend entirely.
  3. Security (optional) — an expiry, allowed source-IP ranges (CIDR such as 10.0.0.0/24), an allowed User-Agent match, and a forced codec if you do not want default auto-negotiation.
  4. Behavior (optional) — do-not-disturb, per-leg recording flags, SIP username for forward-on-busy / forward-no-answer / forward-unavailable, and a voicemail PIN (4–8 digits, stored hashed).
Save the one-time password. Creation returns the plaintext password exactly once — the dialog requires you to tick “I have saved the password” before it can close. The extension’s SIP username stays stable across password rotations; if you lose it, rotate a new one from the detail page instead of creating a second extension. To hand the extension to a permanent desk phone, pair a Desk phone device to it (next section) — the phone REGISTERs over that identity. Mapping to an agent is optional: agents see the extension in Voice → Colleagues as a click-to-call entry, and dispatch rules can point to the extension’s username.

​
Zero-touch provisioning

Voice → Desk phones registers physical handsets in three steps:
  1. Register the phone. Click Register desk phone and enter its MAC address from the label or the phone’s Status → Network screen (colons, dashes, dots, or whitespace are accepted; the dialog normalizes them). Pick the vendor, optionally pair a SIP credential, and add a label and model (e.g. Reception, VVX 450).
  2. Copy the provisioning URL. The registration returns a URL the phone’s vendor redirect server needs on next boot. Paste it into Polycom ZTP, Yealink RPS, Cisco EDOS, or Grandstream GDMS — the dialog labels which one. The URL is also on the device’s row afterwards.
  3. Factory-reset the phone. On next boot it fetches its rendered config, authenticates to the SIP edge, and registers against the paired extension. The URL carries a signed token, so treat it like a password — anyone holding it can provision the phone as that extension.
Each new phone gets a 30-day claim window — register within that time or the row flips to Expired in the table.

​
Bulk CSV import

For fleets, skip the single dialog. In Voice → Desk phones, click Bulk import and upload a CSV with a header row. Required columns are mac and vendor; label and model are optional. Order- and case-insensitive, and common header aliases are accepted (mac address, make, manufacturer, name, description):
Each valid row registers one phone sequentially, and the result panel reports registered / failed / skipped counts with per-line reasons — a duplicate MAC or unknown vendor affects only that row, not the batch. Fix the rejected lines and re-upload while the good rows stay registered. The import permission is sized for fleets of this shape: up to 50 phones per hour per workspace. Two classes of row fail up front and are skipped before anything posts:
  • Invalid MAC — the cell does not reduce to a 12-digit hex address.
  • Unknown vendor — the value is not one of polycom, yealink, cisco, or grandstream.
Rows with a duplicate MAC or a server-side validation error land in the Failed list in the result panel with the row’s line number and reason.

​
Live status and online indicator

After registration, the Live status card on the extension’s detail page (back under Voice → Extensions → click the extension) shows whether a device is currently registered to this credential on the SIP edge — with the UTC timestamp and source IP of the last REGISTER. Statuses are Registered, Not registered (the binding expired), or Disabled (the credential is administratively off). Most softphones and phones re-REGISTER every 60–300 seconds, so brief gaps self-heal; a persistent Not registered points at a network, NAT, or stale-password issue. From the same card you can Force unregister to evict a binding, or Rotate password for a lost or compromised plaintext.

​
Troubleshoot provisioning loops

Symptoms and checks, in the order to run them:
  • Phone never boots the config. Factory-reset it again and confirm the redirect server (Polycom ZTP / Yealink RPS / Cisco EDOS / Grandstream GDMS) carries the exact provisioning URL you copied. The URL token is bound to one MAC — registering the wrong MAC on the redirect server leaves the phone in a loop.
  • Config fetched, registration loops. The provisioning worked; the phone now loops REGISTER attempts. Check the extension’s Live status card — if it flips Registered → Not registered, the re-register timer is failing. Confirm the password hasn’t rotated, and that the phone can reach the SIP edge over TLS from its network.
  • NAT and SIP-ALG. Corporate firewalls with SIP Application Layer Gateway rewrite SIP headers and break the binding. Disable SIP-ALG on the network router, or route over the TLS port Orbit provisions (the generated configs already prefer TLS) and allow the SIP edge outbound. If you set an allowed-source-IP list on the extension, the phone’s egress IP must match it — an unmatched REGISTER is rejected before authentication.
  • Re-provision cleanly. Rotate the extension’s password at Voice → Extensions, delete the device at Voice → Desk phones, re-register the phone against the new URL, and factory-reset it. A force unregister alone is temporary; a stale device row is not.

​
More