Skip to main content

​
Voice extensions

An extension is a set of SIP credentials — a username, password, and optional extension number — that registers a device on your organization’s voice network. Dashboards list them under Voice → Extensions. Users reach the extension from a desk phone, a softphone app (Zoiper, Linphone, Bria), or the in-browser softphone, and colleagues can dial it by its short extension number. Manage both ends of the lifecycle here: issue the credential, provision a device onto it, watch its live registration, rotate or revoke the password, and delete the extension when the device or person leaves.

​
Extensions vs. Colleagues

Two surfaces read the same SIP credentials from different angles:
  • Voice → Extensions (this guide) — the management surface: create, edit, disable, provision, rotate, and delete credentials.
  • Voice → Colleagues — the directory surface your team dials from: live presence (available, on a call, away) with one-click calling. It never edits credentials.
Create and maintain the endpoint in Extensions; reach a teammate in Colleagues. A colleague only appears in the directory once they have a SIP credential, and a disabled credential shows as Disabled there instead of vanishing. Full detail: Colleagues.

​
Create an extension

Open Voice → Extensions and click Create extension. The dialog mounts the same form as the /voice/extensions/new full-page route, so both entry points behave identically — use whichever you reach first. The form groups its fields into four cards:
  1. Identity — the label (required, up to 32 characters). The SIP username is derived from the label server-side, so you never type one by hand. An optional extension number (2–8 digits) gives colleagues a short dial-in, and notes (up to 1000 characters) carry dial-plan or assignment details for your team.
  2. Outbound — whether the extension can place outbound calls, how it picks a caller-ID (inherit the organization’s default, pick one of your owned numbers, or fix a specific number), an optional daily spend cap, an optional concurrent-call cap, and an optional list of countries to block (ISO-2 codes such as US or GB). Leave the cap blank for unlimited; entering 0 disables outbound spend entirely.
  3. Security — optional expiry (expiresAt), 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 the default auto negotiation. Every one of these is a tenant-owned restriction you layer on top of the credential.
  4. Behavior — do-not-disturb, per-leg recording flags (inbound and outbound), forward-on-busy / forward-no-answer / forward-unavailable SIP usernames, and an optional voicemail dial-in PIN (4–8 digits, stored hashed).
On create, the one-time password modal opens. The plaintext password is returned exactly once — copy it before dismissing. Dismissal is gated behind an “I have saved the password” checkbox so the modal cannot be closed by accident.
The SIP username stays stable across password rotations, and the password is never retrievable after creation. If you lose it, rotate a new one from the extension’s detail page (below) rather than creating a second extension.

​
Provision a device

Every extension detail page has a Provision device action that opens the provisioning flow. Three device classes are covered on one page:

​
Browser softphone (no install)

The in-browser softphone connects over the user’s signed-in dashboard session — no SIP username, password, or server settings to enter. Open it from the Browser softphone card on the provision page. When the extension has a direct caller-ID number, the softphone pre-selects it as the outbound caller ID. If no number is set yet, you can still open the softphone and pick a number there.

​
Softphone app (Zoiper, Linphone, generic)

  1. Pick the app the user installed — each has its own provisioning scheme, and the generated QR encodes every advanced field (server, TLS port, transport, realm, SRTP, codec) so there is nothing to type.
  2. Supply the password: paste the one you captured at creation, or use Rotate password inline to issue a fresh one. The plaintext is never stored after the one-time reveal, so the field starts empty on every visit.
  3. Have the user scan the QR from their app (Zoiper → Settings → Accounts → Scan QR; Linphone → Assistant → remote provisioning; other apps follow a generic SIP-URI scan). The page also shows the raw provisioning URI behind a Reveal URI toggle plus a copy button, with the server, TLS port, transport, realm, SRTP, and any forced codec listed below it for manual entry.
Treat the URI like a password — anyone holding it can register as the extension. For certified desk phones, pick the vendor, enter the phone’s MAC address (from the label or the phone’s Status → Network screen), and download a vendor-native config file to import on the phone or drop on your provisioning server. The file embeds the SIP password, so it stays behind the same don’t-share warning as the QR; it also needs the password from step 2 before a download link appears.

​
Live status

Back on the extension detail page, the Live status card shows whether a device is currently registered against this credential on the SIP edge, with the exact UTC-anchored timestamp and source IP of the last REGISTER. A credential is Registered while a device holds an active binding and flips to Not registered when the refresh goes stale (most softphones re-REGISTER roughly every 60–300 seconds, so brief gaps self-heal). The registration badge reads one of three states: Registered, Not registered, or Disabled when the credential is administratively off. From the same card you can Force unregister to evict the device’s active binding — a temporary disconnect. The device re-registers on its next refresh, so for a permanent block also disable the credential in the edit form.

​
Rotate, disable, or delete

  • Rotate password (detail page header, or inline on each list row) — destroys the old password and issues a new one through the same one-time reveal modal. Every device using the credential disconnects and must be reconfigured, so the action is gated behind a confirmation. Rotation keeps the SIP username stable, which makes it the right response to a lost or compromised password.
  • Disable — send PATCH /api/v1/sip-credentials/{id} with { "enabled": false }. The registrar then rejects new REGISTER attempts while the row stays visible (and shows Disabled everywhere). Re-enable with "enabled": true when the device comes back.
  • Delete — the trash action on the list (single row or bulk-select) permanently removes the credential after a confirmation dialog. Deletion is the retirement path for extensions whose owner or device is gone entirely; prefer disable when you expect the endpoint to return.
Deleting does not leak the password — it was never stored after the one-time reveal — but any registered device loses its binding with the credential.

​
Common failures

Registration expiry (stale binding) — the row shows Not registered even though the device worked before. Softphones renew their REGISTER binding on a timer; when a renewal fails or the device’s clock/network drifts, the binding expires and the row flips. Have the device re-register (most recover within a minute), then check its SIP logs for the failed renewal. SIP REGISTER timeouts — the device tries to register but never completes. Verify the server, TLS port, and transport from the provision page’s parameter list, and confirm the password is the current one (a rotation since the device was configured invalidates the old one immediately). Network and firewall blocks — corporate NATs and firewalls frequently block or reshape SIP signalling. The generated URIs route over TLS with the registrar as outbound proxy to survive restrictive NAT, but if a site still cannot register, allow the SIP edge’s TLS port outbound from that network. If you configured an allowed-source-IP list on the extension, the device’s source IP must match it — an unmatched attempt is rejected before authentication. Credentials rejected after IP filtering was added — same cause as above: the extension’s allowed IP ranges no longer cover the device’s egress. Widen the CIDR list or remove it. Device disabled at the admin level — a Disabled credential rejects every REGISTER until re-enabled. Check the enabled flag before debugging the network.

​
API access

Everything the dashboard does is also available over the public API, under /api/v1/sip-credentials: The create and rotate responses are the only places a plaintext password ever appears — capture it in the response handler, because the stored hash is one-way.