Skip to content
Voxbi Cockpit APIs
API Guides

Phones / SIP devices

A SIP device is one phone connected to your PBX: a desk phone, a softphone, a DECT handset, or anything else that speaks SIP. It is the PBX-side mirror of a real phone, so a user with no device record has nothing to pick up when their extension rings.

Overview

A SIP device is the PBX-side mirror of a real or virtual phone. A user's call rings the SIP devices assigned to them, so without a device record even a fully-configured user has no phone to pick up. Four types share the same record but expose different fields:

Type What it is When to use
Auto-deployed phone A managed desk phone the PBX provisions automatically over the network. The default for new desk phones.
Manually provisioned SIP device Any phone or softphone where you handle the SIP credentials yourself. Third-party softphones, SIP clients on personal hardware.
Gigaset A DECT cordless handset registered through a Gigaset base station. Roaming staff inside the office.
Trunk A device that registers through a SIP trunk gateway. Devices behind an external gateway.
The SIP device list, showing type, assignment and registration state per device
The SIP device list, showing type, assignment and registration state per device

The list is where you confirm a device registered. Read it before testing a call, because an unregistered device does not announce itself anywhere else.

What it does

Assign a device to a user so it rings on their calls, or directly to an extension for a shared or functional phone. A user can have several devices, and they all count as that user's phones. The device only decides what physically rings, not what a caller hears - that comes from the upstream call flow, IVR, or queue.

Before it can send or receive calls, a device must register with the PBX. Auto-deployed phones register automatically through provisioning. Manual devices need the SIP username and password entered on the phone. An unregistered or disabled device cannot be reached, so the call falls through to the next step in the flow. The Allow login toggle decides whether a hot-desking user can claim a shared phone for their session.

Two operations go beyond standard editing:

  • Easy deploy - opens a 30-minute window for a freshly-unboxed phone to fetch its provisioning config.
  • Push notify - tells a device to refresh its configuration immediately (after BLF reassignments, language changes, and similar).

How to get a new desk phone ringing

The usual "it does not ring" call is a device that never registered, which is not an error state: the call simply falls through to the next step in the flow.

  1. Make sure the person exists as a user with an extension. The extension is what people dial; the device is what rings.
  2. Create the device and pick its type. Auto-deployed phone for a managed desk phone, Manually provisioned for a softphone or third-party handset.
  3. Assign it, to the user for a personal phone or straight to an extension for a shared one. Check the extension is free first: assigning to one that already has a device silently unassigns the previous device.
  4. Get it to register. Auto-deployed phones need the MAC address and Easy deploy, which opens a 30-minute window for the phone to fetch its config, so power it on inside that window. Manual devices need the SIP username and password typed into the phone itself.
  5. Confirm the device shows as registered before testing the call. Test only after that.
  6. If it never registers, work through the three causes in order: credentials (manual), MAC address (auto-deployed), then network (VLAN, firewall).
  7. After later changes to buttons, language, or labels, use Push notify rather than waiting for the phone to notice.

See also

  • Users - the people SIP devices are typically assigned to.
  • Extensions - the alternative assignment target for shared / functional phones.
  • Phone buttons - the BLF / speed-dial keys configured on each device, with PBX -> group -> user -> device inheritance.
  • Pools and Pickup lines - where Location and Tags become routing-relevant.

Form fields

Fields available in the create and edit forms.

General

Name

A descriptive name for this device (for example, "Reception Desk Phone" or "Conference Room").

MAC address

The MAC address of the physical phone. Used for auto-provisioning. Required for auto-deployed phones. Enter with or without colons or dashes.

Enabled

When off, the device cannot register or make calls. Active registrations are torn down immediately. Use to quarantine a misbehaving phone without deleting the record.

Assigned to

The user or extension this device is assigned to. Determines which calls ring on the device. Choose between User and Extension in the target type selector.

Location

The physical location where this device is installed. Used by pools and reports.

Tags

Tags for categorizing and filtering your SIP devices. Used by pools, pickup-line membership, and reports.

Type

The device type: Auto-deployed phone, Manually provisioned SIP device, Gigaset, or Trunk. Controls which additional fields are shown.

Parent SIP device

The parent gateway device this phone is registered through. Only applies to Gigaset handsets (parent is the base station) and Trunk devices (parent is the gateway).

Shown when

Type is Gigaset DECT phone or Trunk SIP Device

Allow login

When on, users can log into this device using their extension credentials (hot-desking). Only available for auto-deployed phones assigned to a user.

Logged in user

The user currently logged into this device through roaming login.

Shown when

Allow login is on

VLAN phone

The VLAN ID for the phone port (0-4095). Tags the phone's SIP traffic so your network keeps voice on its own segment. Only available for auto-deployed phones.

Shown when

Type is Auto deployed phone

VLAN PC

The VLAN ID for the PC passthrough port (0-4095). Separates workstation data traffic from voice traffic. Only available for auto-deployed phones.

Shown when

Type is Auto deployed phone

Phone language

The display language for the phone's interface (English, German, French, Dutch). Only available for auto-deployed phones.

Shown when

Type is Auto deployed phone

SIP password

The SIP authentication password for this device. Retrieving the current password is logged for security. Leave empty to preserve the existing password. Only visible for manually provisioned devices.

Shown when

Type is Manually provisioned phone / SIP device

Outgoing phone numbers

Extension shown for internal calls

The extension number displayed to other users when this device makes internal calls. Only available when the device is assigned to an extension.

Shown when

Assigned to is an extension

Phone numbers

The outgoing phone numbers (caller identities) used when this device makes external calls. Each entry has a phone number, an optional suffix, and a label.

Allow default outgoing phone numbers

When on, this device can also use the PBX-level default outgoing phone numbers in addition to its own.

Phone buttons

Phone buttons

Phone buttons configured specifically for this device. The device also inherits buttons from the PBX, the assigned group, and the assigned user.

Alternative username

When enabled, the device registers with this username instead of the default.

Custom provisioning

Add custom provisioning instructions at the end of the template.

Updated