---
title: 'Phone buttons'
summary: 'A programmable key on a phone or SIP device that can be configured to perform a specific action with a single press. Buttons are set on the PBX, a group, a user, or a specific device, and the four levels merge into one layout per device.'
section: features
tags:
- telephony
- blf
- hardware
- reference
updated: '2026-08-12'
---
> A **phone button** is a programmable key on a phone or SIP device that can be configured to perform a specific action with a single press.
## Overview
Buttons are configured at four levels. Each level applies to a different scope, listed here from broadest to most specific:
| Level | Applies to |
|---|---|
| [PBX settings](pbxes.md) | Every device on the tenant |
| [Group](groups.md) | Users in that group |
| [User](users.md) | All of that user's devices |
| [SIP device](sip_devices.md) | That one device |
Each button is assigned a **position** (1 to 255). A device supports a limited number of positions, including any added by expansion modules. Positions beyond the device's capacity are ignored during provisioning.
## What it does
A device's final layout is resolved one position at a time across all four levels:
- **The most specific level wins by default.** A button set on the device overrides the user, which overrides the group, which overrides the PBX. A lower level can override a position defined at a higher level.
- **A locked button cannot be overridden.** Turn off Editable to lock a button so it applies to every level below and cannot be replaced there. When two levels lock the same position, the higher level wins (PBX over group over user). Use a lock for a button that every device must keep, such as a group-pickup key or an emergency speed dial.
When you edit a group, user, or device, buttons inherited from higher levels appear as read-only rows and locked positions are marked. This shows the effective layout before you add your own buttons.
## The phone button editor
Every level opens the same editor. It lists each position with its type, source, label, and value, and merges the four levels into the layout provisioned to the device.
| Outline | Control | What it does |
|---|---|---|
| Purple | Add | Add your own button at an empty position. |
| Orange | Override | Replace an inherited button at this position with your own. |
| Blue | Configured only | Hide empty positions and list only the set buttons. |
| Pink | Search | Filter the list by label or value. |
| Red | Read-only device view | Preview the layout on a specific SIP device, read-only. |
| Green | Pages and modules | Jump between key pages and expansion modules. |
### Overriding an inherited button
| Outline | State | Meaning |
|---|---|---|
| Green | Source shows **User** | Your button replaced the inherited one at this position. The higher-level button is hidden. |
| Orange | Warning triangle | The inherited button at this position is locked, so your button sits there without taking effect. |
The two badges under the table are the legend for this: a padlock means locked by a higher level, and the warning triangle means an override with no effect. A locked position is the one case where adding your own button changes nothing, so check the source column before assuming a button will ring.
### Auto-assigned lines
The first positions are **auto-assigned lines**. They use the **System** source because the system generates them from the SIP account and its outgoing numbers. They cannot be edited and always occupy the first positions.
The count is the extension line at position 1, plus one key per outgoing number (caller identity). A single outgoing number is the default and needs no dedicated key, so additional identity lines appear only when more than one outgoing number is configured. Programmable buttons start after the auto-assigned lines.
### Read-only device preview
When the record has a SIP device, the view dropdown switches from "Template for this user" to that device ("View" followed by the device name). The preview is read-only. It shows how the buttons map to that phone model across its physical keys, pages, and expansion modules.
The preview includes changes you have made to the template but not yet saved, so you can check how a new button lands on each phone before saving. Buttons set on the device itself still win over the template.
On a user with exactly one SIP device, the "Template for this user" view already uses that phone's layout: the grid pages like its hardware and offers its keys and expansion modules. With two or more devices there is no single layout to follow, so the user view lists positions in pages of 12 and each device shows its own layout in its preview.
### Adding a button
Click **Add** on an empty position to open the button form. Select a type, then complete the field it requires.
### When an override has no effect
If a lower level sets a position and a higher level later locks it, the lower button is retained but ignored. The editor marks it with a warning to indicate the button no longer applies.
## See also
- [SIP devices](sip_devices.md) - the hardware that receives the merged layout.
- [Extensions](extensions.md) and [Pickup lines](pickup_lines.md) - common monitoring targets.
- [Multicasts](multicasts.md) - the paging target for Multicast keys.
- [Call flows](call_flows.md) - the target for Toggle call flow keys.
```yaml fields
label:
label: Label
api: label
tab: General
hint: 'Text shown on the phone next to the key. Keep it short and describe what the key does.'
type:
label: Type
api: type
tab: General
hint: 'What the key does. Picking a type reveals the field it needs.'
values:
-
value: extension
label: Extension
text: 'Monitor and one-touch dial an extension. The LED shows its state.'
-
value: pickup_line
label: Pickup
text: 'Monitor a pickup line and answer its ringing calls.'
-
value: line
label: 'Phone line'
text: 'An outbound line key that dials using a chosen outgoing number.'
-
value: contact
label: Contact
text: 'One-press dial of a saved contact number.'
-
value: redirect
label: 'Call forward'
text: 'Toggle call forwarding to a number, internal or external.'
-
value: tempus
label: Tempus
text: 'Toggle a Tempus status.'
-
value: multicast
label: Multicast
text: 'Trigger a multicast paging group.'
-
value: speed_dial
label: 'Speed dial'
text: 'Dial a fixed phone number.'
-
value: function
label: 'Phone function'
text: 'Run a built-in phone function (see Function).'
-
value: dtmf
label: 'DTMF / Tones'
text: 'Send a tone sequence when pressed.'
-
value: xml
label: 'XML request'
text: 'Open a URL on the phone screen.'
-
value: toggle_call_flow
label: 'Toggle call flow'
text: 'Activate or deactivate a call flow.'
-
value: none
label: Empty
text: 'A blank key that occupies a position without performing an action.'
number:
label: Position
api: number
tab: General
hint: 'Which key slot on the phone this button occupies (1 to 255). Positions past the phone key count are ignored.'
editable:
label: Editable
api: editable
tab: General
hint: 'When on, a more specific level can replace this button at its position. When off, the button is locked and applied to every level below.'
target_extension_id:
label: Extension
api: target_extension_id
tab: General
hint: 'The extension this key monitors and dials.'
when: 'Type is Extension'
target_user_id:
label: 'User or pickup line'
api: target_user_id
tab: General
hint: 'The pickup line this key monitors and answers.'
when: 'Type is Pickup'
caller_identity_id:
label: 'Outgoing phone number'
api: caller_identity_id
tab: General
hint: 'The outgoing number used when placing a call from this line key.'
when: 'Type is Phone line'
contact_phone_number_id:
label: 'Contact phone number'
api: contact_phone_number_id
tab: General
hint: 'The saved contact number this key dials.'
when: 'Type is Contact'
phone_number:
label: Number
api: phone_number
tab: General
hint: 'The phone number this key dials or forwards to.'
when: 'Type is Speed dial or Call forward'
forward_caller_identity_id:
label: 'Phone number'
api: forward_caller_identity_id
tab: General
hint: 'The number calls are forwarded to. Choose Internal only to keep the redirect on the PBX.'
when: 'Type is Call forward'
status_id:
label: 'Tempus status toggle'
api: status_id
tab: General
hint: 'The Tempus status this key toggles.'
when: 'Type is Tempus'
multicast_id:
label: Multicast
api: multicast_id
tab: General
hint: 'The multicast group this key pages.'
when: 'Type is Multicast'
function_action:
label: Function
api: function_action
tab: General
hint: 'The built-in action this key runs.'
when: 'Type is Phone function'
values:
-
value: contacts
label: 'Contacts menu'
text: 'Open the phone contacts menu.'
-
value: missed_calls
label: 'Missed calls'
text: 'Open the missed-calls list.'
-
value: group_pickup
label: 'Group pickup'
text: 'Answer a call ringing elsewhere in the group.'
-
value: callback
label: 'Request callback'
text: 'Request a callback from the dialled party.'
-
value: start_stop_call_recording
label: 'Start / Stop call recording'
text: 'Toggle recording of the active call.'
-
value: login_logout
label: 'Login / Logout'
text: 'Log the user in or out of the device.'
-
value: do_not_disturb
label: DND
text: 'Toggle Do not disturb.'
-
value: redial
label: Redial
text: 'Redial the last number.'
call_flow_id:
label: 'Call flow'
api: call_flow_id
tab: General
hint: 'The call flow this key activates or deactivates.'
when: 'Type is Toggle call flow'
extra_dtmf:
label: 'Tone sequence 0-9*#'
tab: General
hint: 'The tone sequence (digits 0 to 9, star, hash) sent when the key is pressed.'
when: 'Type is DTMF / Tones'
extra_xml:
label: URL
tab: General
hint: 'The URL opened on the phone screen when the key is pressed.'
when: 'Type is XML request'
```