---
title: Extensions
summary: 'An extension is the internal short number people dial inside your PBX to reach a specific user, phone, or AI assistant.'
section: features
tags:
  - crud
  - telephony
updated: '2026-08-12'
related_forms:
  - ai_prompts
---

> An **extension** is the internal short number people dial inside your PBX to reach a specific user, phone, or AI assistant. From outside, callers reach an extension when a phone number is configured to route to it.

## Overview

An extension is created manually here or provisioned automatically from an external system. The number is what people dial, the **Assigned to** field decides what rings, and the per-direction call flows decide what happens on each side of the call. A user can own only one extension at a time - re-assigning a user who already has one releases the previous binding.

## What it does

The **Assigned to** field is the most consequential setting. It reshapes the form and decides what physically rings:

| Assigned to | What rings |
|---|---|
| **User** | Every SIP device assigned to that user, with their preferences (DND, twinning, forwarding) applied. For personal extensions across multiple devices. |
| **Phone (SIP device)** | Exactly one device, bypassing user-level routing. For lobby phones, conference rooms, lab equipment. |
| **AI integration** | The call is answered by a configured AI voice agent (only when AI is enabled on the tenant). |
| **Unassigned** | Nothing. Useful for reserving a number before the target exists. |

![The extension form with the Assigned to picker highlighted](extensions-images/assigned-to.png)

| Outline | Field | What it does |
|---|---|---|
| <span style="color:#af52de">Purple</span> | Assigned to | Chooses what rings, and reshapes the fields below it. |

Each picker lists only targets that are still free. To re-target an in-use target, release its current extension first.

Two **call flows** control routing per direction. The external flow runs when an outside caller reaches the extension (typically via a phone number routed here). The internal flow runs when another extension dials it. Leave either empty to fall back to the PBX-level default. Override the internal flow when internal calls should be handled differently (for example, skip the queue and ring the user immediately).

**Recording toggles** enable per-direction recording (external, internal, both, or neither).

> [!IMPORTANT]
> Recording toggles are disabled when the tenant-level *Allow users to stop/start recording* setting is off. Enable it on the PBX first.

Most fields become read-only in two cases: **provisioned extensions** (managed by an external sync source - edit at the source and let it sync back) and **extensions consumed by a Smart IVR Assistant** (release by unpublishing or deleting the assistant first).

## How to re-point an extension at a different target

1. Check what the extension and the intended target are bound to now. Each picker lists only targets that are still free, so the one you want may simply not be in the list yet.
2. Release the target's current extension first if it has one. A user can own only one extension at a time, and re-assigning a user who already has one releases their previous binding.
3. Change **Assigned to**. The form reshapes with it: *User* rings every device that user owns with their DND, twinning, and forwarding applied, while *Phone* rings exactly one device and bypasses user-level routing.
4. If the fields are read-only, the extension is either provisioned from an external system, in which case edit it at the source and let it sync back, or consumed by a Smart IVR assistant, in which case unpublish or delete the assistant to release it.
5. Re-check the per-direction call flows afterwards, leaving either empty to inherit the PBX default.

## See also

- [Users](users.md) - the most common assignment target.
- [SIP devices](sip_devices.md) - the alternative target for shared or functional phones.
- [Phone numbers](phone_numbers.md) - how outside callers reach an extension.
- [Call flows](call_flows.md) - what plays on each direction of the call.

```yaml fields
number:
  label: Extension
  tab: General
  hint: "The internal number for this extension. Must be unique across your PBX, including trashed extensions. Up to 16 alphanumeric characters. Numbers on your PBX's reserved list are refused here - review that list in [PBX settings](/admin/pbx/edit?highlight=reserved_extensions&highlight_variant=info#defaults)."
  text: 'A reserved number is refused so that dialling it keeps doing whatever your telephony provider routes it to, rather than ringing a desk. The same check applies however the extension is created: this form, the user import, user provisioning, SCIM and single sign-on.'
name:
  label: Name
  tab: General
  hint: 'Optional display name shown in lists and dropdowns. Pick a name that describes what the extension is.'
assigned_to:
  label: 'Assigned to'
  tab: General
  hint: 'Controls what this extension rings: None, User, Phone (SIP device), or AI integration.'
user:
  label: User
  tab: General
  hint: 'The user who receives calls to this extension. Only users without an existing extension appear in the dropdown.'
sipDevices:
  label: 'Phone / SIP device'
  tab: General
  hint: 'The SIP phone that receives calls to this extension. Only devices without an existing target appear in the dropdown.'
externalCallFlow:
  label: 'Call flow from external'
  tab: General
  hint: 'Handles calls coming in from outside the PBX. Leave empty to use the PBX-level default external call flow.'
internalCallFlow:
  label: 'Call flow from internal'
  tab: General
  hint: 'Handles calls coming from other extensions within the PBX. Leave empty to use the PBX-level default internal call flow.'
description:
  label: Description
  tab: General
  hint: 'Optional note about what this extension is used for.'
record_external_calls:
  label: 'Record external calls'
  tab: General
  hint: 'When on, all external calls to and from this extension are recorded. Disabled if the tenant does not allow changing call recording settings.'
record_internal_calls:
  label: 'Record internal calls'
  tab: General
  hint: 'When on, all internal calls to and from this extension are recorded. Disabled if the tenant does not allow changing call recording settings.'
ai_prompt:
  label: Prompt
  tab: 'AI prompt'
  hint: 'Instructions the AI follows when handling calls for this extension. Leave empty to remove the prompt. Only shown when the PBX is on an AI plan.'
famulor_agent_id:
  label: 'AI integration'
  hint: 'Links this extension to a Famulor AI voice agent that answers its calls, when the AI integration is enabled.'
```