---
title: 'PBX settings'
summary: "The PBX is your organization's tenant in Cockpit. Every other entity is scoped to it, and this page holds its organization-wide settings."
section: features
tags:
  - telephony
  - settings
  - administration
updated: '2026-08-12'
related_forms:
  - phone_buttons
  - caller_identities
  - ai_features
  - sso_setup
  - user_provisioning
  - identity_providers
---

> Your **PBX** is your organization's tenant in Cockpit. Every other entity is scoped to it, and there is one PBX per tenant.

## Overview

Here you set the PBX's own configuration. Some of it is organization-wide defaults, and the rest applies only at the PBX level.

## What it does

Values set here are PBX-wide defaults. Every group, user, and device inherits them unless it sets its own, so you configure a value once and override it only where it needs to differ.

Telephony changes are **staged**: saving does not apply your changes to live calls immediately. They take effect only when you click **Push configuration**, the button at the top of every Telephony page. This button shows the current state (up to date, changes pending, updating, or locked), lets you review what is pending, and logs every push. Use **Lock push** to lock the push configuration so no one can apply pending changes until you unlock it, preventing a premature push while work is still in progress. The lock records who set it.

### Single Sign-On

Your users can sign in to Cockpit with their existing **Microsoft** or **OpenID Connect** account instead of a separate Cockpit password. The settings on the **Authentication** tab turn this on and control whether new users are created automatically. See the [Set up Single Sign-On (SSO)](sso_setup.md) guide for a step-by-step walkthrough, an explanation of each setting, and how Microsoft accounts create users and their extensions.

### User provisioning

Your own system can keep Cockpit's users in sync over an API: you post the complete list of people who should exist, and Cockpit creates, updates, and removes accounts, extensions, twinnings, and badges to match it. The **User provisioning** tab holds the endpoint URL, the key that authenticates it, and the IP addresses allowed to use it. See the [Set up user provisioning](user_provisioning.md) guide for the request shape, a worked example, and what the sync does and does not remove.

## See also

- [SIP carriers](sip_carriers.md) - the carriers selected as PBX defaults.
- [Call flows](call_flows.md) - the default internal and external flows.
- [Default music on hold](default_music_on_holds.md) - the catalog for the PBX-default hold music.
- [Users](users.md), [Groups](groups.md) - the downstream entities that inherit from PBX defaults.
- [Phone buttons](phone_buttons.md) - the inheritance cascade rooted at the PBX layer.
- [Phone numbers](phone_numbers.md) - the caller-identity hierarchy whose base layer lives here.

```yaml fields
name:
  label: Name
  tab: Defaults
  hint: 'The display name of your PBX, shown throughout the admin panel.'
comment:
  label: Comment
  tab: Defaults
  hint: 'An optional note for your own reference.'
default_call_ring_duration:
  label: 'Default call ring duration'
  tab: Defaults
  hint: 'How long a call rings (in seconds) before it is forwarded or dropped.'
  text: 'This is the default for all extensions unless overridden individually.'
musicOnHold:
  label: 'Music on hold'
  tab: Defaults
  hint: 'The sound file callers hear when placed on hold.'
  text: 'You can choose from your uploaded music-type sound files.'
ring_tone:
  label: 'Ring tone pattern'
  tab: Defaults
  hint: 'The ring cadence for incoming calls on SIP devices.'
  text: 'Choose from country-specific patterns: Luxembourg, Germany, France, Belgium, Netherlands, USA, UK, Portugal, Switzerland, Austria, Italy, Spain, Bulgaria, or South Africa.'
defaultCarrier:
  label: 'Outgoing call carrier'
  tab: Defaults
  hint: 'The SIP carrier used for outgoing calls by default, unless a more specific outgoing call route applies.'
fallbackCarrier:
  label: 'Outgoing call fallback carrier'
  tab: Defaults
  hint: 'A backup SIP carrier that takes over if the default carrier is unavailable.'
defaultInternalCallFlow:
  label: 'Default internal call flow'
  tab: Defaults
  hint: 'The call flow used for internal calls between extensions within this PBX.'
defaultExternalCallFlow:
  label: 'Default external call flow'
  tab: Defaults
  hint: 'The call flow used for incoming external calls when the dialled extension is found.'
noExtMatchCallFlow:
  label: 'No extension match external call flow'
  tab: Defaults
  hint: 'The call flow that runs when an incoming external call does not match any extension.'
  text: 'If you leave this empty, the default external call flow is used instead.'
max_incoming_channels:
  label: 'Max channels'
  tab: Defaults
  hint: 'The maximum number of calls that can come in at the same time.'
  text: 'Once this limit is reached, additional callers hear the sound file configured below.'
maxIncomingChannelsSoundFile:
  label: 'Sound file for max incoming channels'
  tab: Defaults
  hint: 'The announcement played to callers when all incoming channels are in use.'
  text: 'Choose from your uploaded announcement-type sound files.'
it_admin_notification_email:
  label: 'IT admin notification email'
  tab: Defaults
  hint: 'The email address that receives system notifications from the PBX.'
reserved_extensions:
  label: 'Reserved extensions'
  tab: Defaults
  hint: 'Comma-separated numbers that nobody can create as an extension on this PBX. Use it for numbers that must keep reaching what your telephony provider routes them to - typically the emergency and service numbers of your country - rather than ringing a desk.'
  text: 'Which numbers must stay free differs from country to country, so the list is yours to set. It is enforced everywhere an extension can be created: this admin panel, the user import, user provisioning, SCIM and single sign-on. Numbers already used by an extension are not removed for you - those extensions keep working until you delete them, they are flagged in the extensions list, and you will see a reminder after saving.'
default_call_pickups_for_new_extensions:
  label: 'Default call pickups for new extensions'
  tab: Defaults
  hint: 'When turned on, every new extension is automatically added to the default call pickup group.'
show_users_first_name_first:
  label: 'Display users as "First name Last name"'
  tab: Defaults
  hint: 'When on, names show as "First name Last name" instead of "Last name First name".'
capitalize_users_last_name:
  label: "Capitalize users' last names"
  tab: Defaults
  hint: 'When turned on, last names are displayed in uppercase throughout the interface.'
show_via_in_missed_call:
  label: 'Show "via" in missed call notifications on phones'
  tab: Defaults
  hint: 'When turned on, the "via" line is shown in missed-call notifications on SIP phones.'
split_internal_external_calls:
  label: 'Split internal and external calls for single line users'
  tab: Defaults
  hint: 'When a user has only one line, show separate internal and external lines.'
call_block_logged_out_sip_devices:
  label: 'Block calls from logged-out SIP devices'
  tab: Defaults
  hint: 'When turned on, roaming SIP devices that are not logged in to a user cannot place calls.'
automatic_firmware:
  label: 'Automatic firmware updates'
  tab: 'Phones / SIP devices'
  hint: 'When turned on, phone firmware is updated automatically during provisioning.'
allow_roaming:
  label: 'Allow login'
  tab: 'Phones / SIP devices'
  hint: 'Allows users to log in to any SIP device with their extension credentials (hot-desking).'
enable_soop_status:
  label: 'Tempus status'
  tab: 'Phones / SIP devices'
  hint: 'Shows Tempus presence status in client applications.'
lldp:
  label: 'Enable LLDP'
  tab: 'Phones / SIP devices'
  hint: 'Enables LLDP so phones can automatically discover network settings like VLAN assignments.'
phones_default_vlan_pc:
  label: 'VLAN PC'
  tab: 'Phones / SIP devices'
  hint: 'The default VLAN ID for the PC port on new phones.'
  text: 'Accepted values: 0 to 4096.'
phones_default_vlan_phone:
  label: 'VLAN phone'
  tab: 'Phones / SIP devices'
  hint: 'The default VLAN ID for the phone port on new phones.'
  text: 'Accepted values: 0 to 4096.'
language:
  label: 'Phone language'
  tab: 'Phones / SIP devices'
  hint: 'The display language for newly provisioned phones.'
  text: 'Choose English, German, or French.'
phones_web_admin_password:
  label: 'Web admin password'
  tab: 'Phones / SIP devices'
  hint: 'The password for the web admin interface on SIP phones.'
  text: 'Leave it empty to keep the current one. Revealing the current password is logged in the change log.'
multicast_sites_ip_addresses:
  label: 'Multicast sites IP addresses'
  tab: 'Phones / SIP devices'
  hint: 'IP addresses for multicast sites, used for paging and intercom across network segments.'
  text: 'You can add up to 5 entries.'
phone_provisioning_yealink:
  label: 'Yealink provisioning URL'
  tab: 'Phones / SIP devices'
  hint: 'The provisioning URL for Yealink phones.'
  text: "Read-only, generated from your PBX domain. Copy it into the phone's auto-provision server URL setting."
phone_provisioning_gigaset:
  label: 'Gigaset provisioning URL'
  tab: 'Phones / SIP devices'
  hint: 'The provisioning URL for Gigaset phones.'
  text: "Read-only, generated from your PBX domain. Copy it into the phone's provisioning settings."
phone_directory_gigaset:
  label: 'Gigaset phone directory URL'
  tab: 'Phones / SIP devices'
  hint: 'The phone directory URL for Gigaset devices.'
  text: "Read-only. Copy it into the phone's online directories configuration."
callerIdentities:
  label: 'Outgoing phone numbers'
  tab: 'Outgoing phone numbers'
  hint: 'Your outgoing phone numbers (caller identities) at the PBX level.'
  text: 'Each entry has a phone number, an optional extension suffix (use * as a wildcard for the actual extension number), and an optional label. You can drag entries to reorder them.'
sso_enabled:
  label: 'SSO sign-in'
  tab: Authentication
  hint: 'Turns on Single Sign-On so your users can log in with their company credentials.'
  text: 'Enabling this reveals the SSO configuration fields below.'
sso_type:
  label: 'SSO type'
  tab: Authentication
  hint: 'The SSO protocol to use.'
  values:
    -
      value: openid_connect
      label: 'OpenID Connect'
      text: 'Generic OIDC provider.'
    -
      value: microsoft
      label: Microsoft
      text: 'Microsoft Entra ID (Azure AD). Users sign in with the Microsoft account your organization issued them.'
  text: 'Visible only when SSO is enabled.'
force_sign_in_with_sso:
  label: 'Force SSO sign-in on Cockpit'
  tab: Authentication
  hint: 'When turned on, users must sign in through SSO. Signing in with a Cockpit password is no longer possible.'
  text: 'Visible only when SSO is enabled.'
allow_sign_up_with_sso:
  label: 'SSO provisioning'
  tab: Authentication
  hint: 'When turned on, Cockpit creates a user account and its extension automatically the first time someone signs in via SSO, and keeps them in sync on each sign-in. When off, only people who already have a Cockpit account can sign in, and Cockpit never creates or changes accounts from the provider.'
  text: 'Applies to both SSO types (Microsoft and OpenID Connect). Requires at least one identity provider email domain below so Cockpit can match a new user to this PBX. Exactly who is allowed to be created, and which roles they receive, depends on the SSO type - see the Single Sign-On setup guide for details. Visible only when SSO is enabled.'
identityProviders:
  label: 'Identity providers'
  tab: Authentication
  hint: 'Your identity provider settings (client ID, secret, discovery URL, and related endpoints).'
  text: 'For OpenID Connect: name, description, status, client ID, client secret, discovery URL, authorization URL, token URL, userinfo URL, logout URL, and issuer. For Microsoft: only the tenant ID is needed. You can configure one provider.'
identityProviderEmailDomains:
  label: 'Identity provider email domains'
  tab: Authentication
  hint: 'Email domains used to map a newly provisioned SSO user to this PBX.'
  text: 'Required and visible only when SSO provisioning is enabled. A new user whose email matches one of these domains is created in this PBX. You can add multiple domains.'
sso_identity_fields_mapping:
  label: 'SSO identity field mapping'
  tab: Authentication
  hint: 'Maps claims from your OpenID Connect provider to user fields in the PBX (for example, email, first name, last name, extension).'
  text: 'You can define up to 5 mappings. Visible for OpenID Connect providers (whether or not SSO provisioning is enabled): the mapping is used on every sign-in to read the email and name claims that match and update the user. Microsoft accounts use a fixed, documented schema, so no mapping is needed.'
user_provisioning_url:
  label: 'User provisioning URL'
  tab: 'User provisioning'
  hint: 'The SCIM API endpoint for automatic user provisioning.'
  text: "Read-only. Copy it into your identity provider's provisioning configuration."
user_provisioning_key:
  label: 'User provisioning key'
  tab: 'User provisioning'
  hint: 'The secret API key for authenticating provisioning requests.'
  text: 'You can regenerate it using the refresh button. Regenerating invalidates the previous key immediately.'
user_provisioning_ip_addresses:
  label: 'User provisioning IP addresses'
  tab: 'User provisioning'
  hint: 'The IP addresses allowed to call the provisioning API. Requests from other IPs are rejected.'
  text: 'You can add up to 5 entries.'
show_all_users_in_voxbi:
  label: 'Show all users in Voxbi'
  tab: 'Voxbi apps'
  hint: 'When turned on, every PBX user is visible in the Voxbi app regardless of group membership.'
enable_tempus_menu:
  label: 'Enable Tempus menu'
  tab: 'Voxbi apps'
  hint: 'Shows the Tempus time-tracking menu in Voxbi client apps.'
allow_call_recording:
  label: 'Allow call recording'
  tab: 'Call recordings and AI'
  hint: 'Shows whether call recording is enabled for this PBX.'
  text: 'Managed at the platform level. Cannot be changed here.'
allow_changing_record_calls:
  label: 'Allow users to stop/start recording'
  tab: 'Call recordings and AI'
  hint: 'When turned on, users can start and stop recording during a call from their device.'
recordings_destination:
  label: 'Destination for recordings'
  tab: 'Call recordings and AI'
  hint: 'Where recordings are stored.'
  values:
    -
      value: customer
      label: Customer
      text: 'Customer-managed storage.'
    -
      value: mixvoip
      label: Mixvoip
      text: 'Platform-managed storage.'
recording_start_at:
  label: 'Start the recording'
  tab: 'Call recordings and AI'
  hint: 'When recording begins.'
  values:
    -
      value: on_start
      label: 'When the call starts'
      text: 'Captures ringing and the conversation.'
    -
      value: on_bridge
      label: 'When the call has been answered by a phone'
      text: 'Captures only the conversation.'
ai_profile:
  label: 'AI profile'
  tab: 'Call recordings and AI'
  hint: 'The AI profile assigned to your PBX, which determines which AI features are available.'
  text: 'Managed at the platform level by Voxbi support. Shown here for reference only.'
ai_features:
  label: 'AI features'
  tab: 'Call recordings and AI'
  hint: 'AI features enabled for this PBX, such as call summaries, transcription, translations, keyword mapping, call tagging, and sentiment analysis.'
  text: 'Which features you can toggle depends on the AI profile assigned to your PBX.'
transcript_retention_days:
  label: 'Transcript retention (days)'
  tab: 'Call recordings and AI'
  hint: 'AI Assistant transcripts older than this are purged automatically to comply with GDPR.'
  text: 'Leave blank to use the platform default. Set to 0 to disable automated purging.'
phoneButtons:
  label: 'Phone buttons'
  tab: 'Phone buttons'
  hint: 'The default phone buttons for all SIP devices on this PBX.'
  text: 'Inherited by every phone. Can be overridden at the group, user, or device level.'
voxbiLogos:
  label: 'Voxbi apps'
  tab: Branding
  hint: 'Logos shown in the Voxbi desktop app. Upload PNG, JPG, JPEG, or SVG up to 10 MB.'
yealinkWallpapers:
  label: 'Yealink wallpapers'
  tab: Branding
  hint: 'Background wallpapers pushed to Yealink phones. Upload PNG, JPG, JPEG, or SVG up to 10 MB.'
  text: 'Beta. Only appears when the feature is enabled for your PBX.'
```