Phone buttons

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	Every device on the tenant
Group	Users in that group
User	All of that user's devices
SIP device	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.

Form fields

Fields available in the create and edit forms.

General

Label API label: Text shown on the phone next to the key. Keep it short and describe what the key does.
Type API type: What the key does. Picking a type reveals the field it needs.

extension Extension Monitor and one-touch dial an extension. The LED shows its state.

pickup_line Pickup Monitor a pickup line and answer its ringing calls.

line Phone line An outbound line key that dials using a chosen outgoing number.

contact Contact One-press dial of a saved contact number.

redirect Call forward Toggle call forwarding to a number, internal or external.

tempus Tempus Toggle a Tempus status.

multicast Multicast Trigger a multicast paging group.

speed_dial Speed dial Dial a fixed phone number.

function Phone function Run a built-in phone function (see Function).

dtmf DTMF / Tones Send a tone sequence when pressed.

xml XML request Open a URL on the phone screen.

toggle_call_flow Toggle call flow Activate or deactivate a call flow.

none Empty A blank key that occupies a position without performing an action.
Position API number: Which key slot on the phone this button occupies (1 to 255). Positions past the phone key count are ignored.
Editable API editable: 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.
Extension API target_extension_id: The extension this key monitors and dials.

Shown when
Type is Extension
User or pickup line API target_user_id: The pickup line this key monitors and answers.

Shown when
Type is Pickup
Outgoing phone number API caller_identity_id: The outgoing number used when placing a call from this line key.

Shown when
Type is Phone line
Contact phone number API contact_phone_number_id: The saved contact number this key dials.

Shown when
Type is Contact
Number API phone_number: The phone number this key dials or forwards to.

Shown when
Type is Speed dial or Call forward
Phone number API forward_caller_identity_id: The number calls are forwarded to. Choose Internal only to keep the redirect on the PBX.

Shown when
Type is Call forward
Tempus status toggle API status_id: The Tempus status this key toggles.

Shown when
Type is Tempus
Multicast API multicast_id: The multicast group this key pages.

Shown when
Type is Multicast
Function API function_action: The built-in action this key runs.

Shown when
Type is Phone function

contacts Contacts menu Open the phone contacts menu.

missed_calls Missed calls Open the missed-calls list.

group_pickup Group pickup Answer a call ringing elsewhere in the group.

callback Request callback Request a callback from the dialled party.

start_stop_call_recording Start / Stop call recording Toggle recording of the active call.

login_logout Login / Logout Log the user in or out of the device.

do_not_disturb DND Toggle Do not disturb.

redial Redial Redial the last number.
Call flow API call_flow_id: The call flow this key activates or deactivates.

Shown when
Type is Toggle call flow
Tone sequence 0-9*#: The tone sequence (digits 0 to 9, star, hash) sent when the key is pressed.

Shown when
Type is DTMF / Tones
URL: The URL opened on the phone screen when the key is pressed.

Shown when
Type is XML request

Updated 2026-08-12

Phone buttons

Overview#

What it does#

The phone button editor#

Overriding an inherited button#

Auto-assigned lines#

Read-only device preview#

Adding a button#

When an override has no effect#

See also#