---
title: 'Phones / SIP devices'
summary: 'A SIP device is one phone connected to your PBX - a desk phone, a softphone, a DECT handset, a conference phone, or anything else that speaks SIP.'
section: features
tags:
  - crud
  - telephony
  - hardware
updated: '2026-08-12'
related_forms:
  - phone_buttons
  - caller_identities
---

> 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](sip_devices-images/registration-state.png)

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](users.md) so it rings on their calls, or directly to an [extension](extensions.md) 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](call_flows.md), 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).

> [!IMPORTANT]
> If a device never registers, check the credentials (manual), the MAC address (auto-deployed), or the network configuration (VLAN, firewall).

> [!WARNING]
> Only one SIP device can be assigned to a given extension at a time. Reassigning to an extension that already has one silently unassigns the previous device. Multiple devices on a user works fine.

## 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](users.md) with an [extension](extensions.md). 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](users.md) - the people SIP devices are typically assigned to.
- [Extensions](extensions.md) - the alternative assignment target for shared / functional phones.
- [Phone buttons](phone_buttons.md) - the BLF / speed-dial keys configured on each device, with PBX -> group -> user -> device inheritance.
- [Pools](pools.md) and [Pickup lines](pickup_lines.md) - where Location and Tags become routing-relevant.

```yaml fields
name:
  label: Name
  tab: General
  hint: 'A descriptive name for this device (for example, "Reception Desk Phone" or "Conference Room").'
mac:
  label: 'MAC address'
  tab: General
  hint: 'The MAC address of the physical phone. Used for auto-provisioning. Required for auto-deployed phones. Enter with or without colons or dashes.'
is_enabled:
  label: Enabled
  tab: General
  hint: '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.'
target:
  label: 'Assigned to'
  tab: General
  hint: '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:
  label: Location
  tab: General
  hint: 'The physical location where this device is installed. Used by pools and reports.'
tags:
  label: Tags
  tab: General
  hint: 'Tags for categorizing and filtering your SIP devices. Used by pools, pickup-line membership, and reports.'
type:
  label: Type
  tab: General
  hint: 'The device type: Auto-deployed phone, Manually provisioned SIP device, Gigaset, or Trunk. Controls which additional fields are shown.'
parentSipDevice:
  label: 'Parent SIP device'
  tab: General
  hint: '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).'
  when: 'Type is Gigaset DECT phone or Trunk SIP Device'
allow_roaming:
  label: 'Allow login'
  tab: General
  hint: 'When on, users can log into this device using their extension credentials (hot-desking). Only available for auto-deployed phones assigned to a user.'
roamingUser:
  label: 'Logged in user'
  tab: General
  hint: 'The user currently logged into this device through roaming login.'
  when: 'Allow login is on'
vlan_phone:
  label: 'VLAN phone'
  tab: General
  hint: "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."
  when: 'Type is Auto deployed phone'
vlan_pc:
  label: 'VLAN PC'
  tab: General
  hint: 'The VLAN ID for the PC passthrough port (0-4095). Separates workstation data traffic from voice traffic. Only available for auto-deployed phones.'
  when: 'Type is Auto deployed phone'
language:
  label: 'Phone language'
  tab: General
  hint: "The display language for the phone's interface (English, German, French, Dutch). Only available for auto-deployed phones."
  when: 'Type is Auto deployed phone'
sip_pwd:
  label: 'SIP password'
  tab: General
  hint: '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.'
  when: 'Type is Manually provisioned phone / SIP device'
extensionShownForInternalCalls:
  label: 'Extension shown for internal calls'
  tab: 'Outgoing phone numbers'
  hint: 'The extension number displayed to other users when this device makes internal calls. Only available when the device is assigned to an extension.'
  when: 'Assigned to is an extension'
callerIdentities:
  label: 'Phone numbers'
  tab: 'Outgoing phone numbers'
  hint: '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_pbxes_outgoing_phone_numbers:
  label: 'Allow default outgoing phone numbers'
  tab: 'Outgoing phone numbers'
  hint: 'When on, this device can also use the PBX-level default outgoing phone numbers in addition to its own.'
phoneButtons:
  label: 'Phone buttons'
  tab: 'Phone buttons'
  hint: 'Phone buttons configured specifically for this device. The device also inherits buttons from the PBX, the assigned group, and the assigned user.'
alt_username:
  label: 'Alternative username'
  hint: 'When enabled, the device registers with this username instead of the default.'
custom_provisioning:
  label: 'Custom provisioning'
  hint: 'Add custom provisioning instructions at the end of the template.'
```