---
title: 'Phone numbers'
summary: 'A phone number is one of your external telephone numbers - a DID - the number outside callers dial to reach your tenant. Each one carries its own incoming routing, carrier setup, and outbound-permission list.'
section: features
tags:
  - crud
  - telephony
  - routing
  - did
updated: '2026-08-12'
---

> A **phone number** is one of your external telephone numbers - a DID (Direct Inward Dialing) - the number outside callers dial to reach your tenant.

## Overview

A phone number connects the outside world to your PBX. Inbound calls arrive through a **SIP carrier**, and the number's **handling strategy** decides where they go from there. The same record also controls **outbound caller identity**: who may present this number when dialling out.

Numbers are provisioned by your carrier and appear in Cockpit automatically, stored in E.164 format (`+352 12 34 56 78`). The number field is read-only, and a number disappears only when the carrier de-provisions it.

## What it does

The handling strategy switches between six routing modes. Changing the mode reshapes the form below.

| Mode | What it does | When to use |
|---|---|---|
| **Default** | Match the dialled digits to an extension and run its call flow. Run a fallback flow if no match. | A number that covers a block of direct-dial extensions. |
| **Rewrite** | Strip a prefix from the incoming digits, optionally add a different one, then run Default-style matching. | Carrier delivers numbers in a format that does not match your extension scheme. |
| **Call Flow** | Send every inbound call straight to a chosen call flow. | Single-purpose numbers: support hotline, sales line, emergency line. **Most numbers should be on this mode.** |
| **Extension** | Inbound calls go directly to one specific extension. | A personal direct-dial line for one person. |
| **User** | Inbound calls go directly to one specific user and all their devices. | Same as Extension but keyed to the user. |
| **SIP Device** | Inbound calls go directly to one specific SIP device. | Lobby phones, conference rooms - the device matters more than who is at it. |

The form labels this field **Incoming call routing**. When in doubt, pick **Call Flow** and write the logic in the flow. Extension, User, and SIP Device are convenient shortcuts but lose flexibility - no schedule, no IVR, no fallback.

![A phone number set to Call flow routing, with the routing selector highlighted](phone_numbers-images/handling-strategy.png)

| Outline | Field | What it does |
|---|---|---|
| <span style="color:#af52de">Purple</span> | Incoming call routing | Picks the mode. The fields beside it change with the mode chosen. |

> [!WARNING]
> Switching the mode does not preserve settings from the previous mode. Going Default to Call Flow and back loses the earlier selections.

The **Assignations** tab is the permission list for outbound caller ID. Users, groups (members inherit), and SIP devices listed here may present this number when dialling out. This controls outbound presentation only - it does not make the number ring for anyone.

## How to point an inbound number at a team

1. Build the destination first: the [queue](queues.md) or [group](groups.md) that answers, and a [call flow](call_flows.md) that reaches it. A number pointed at nothing leaves inbound callers nowhere to land.
2. Open the number. The number itself is read-only, provisioned by your carrier.
3. Set the handling strategy to **Call Flow** and pick the flow. Extension, User, and SIP Device are shortcuts that give up schedules, IVRs, and fallbacks, so prefer Call Flow for anything a team answers.
4. Decide the mode before you save and move on. Switching modes does not carry settings over, so a round trip through another mode loses what you picked.
5. Test with a real inbound call.
6. Only if people also need to *present* this number when dialling out, add them on the **Assignations** tab. That tab is outbound presentation only and never makes the number ring for anybody, which is the usual reason a number "is not reaching" a team that was added there and nowhere else.

## See also

- [Call flows](call_flows.md) - what the handling-strategy pickers actually point at.
- [Extensions](extensions.md) - the internal targets reached by Default-mode extension matching.
- [SIP carriers](sip_carriers.md) - the routes that deliver and dispatch calls.

```yaml fields
is_active:
  label: Active
  tab: General
  hint: 'When off, the PBX ignores this number entirely. Use to stage configuration before a porting is completed.'
number:
  label: Number
  tab: General
  hint: 'The external phone number in E.164 format. Read-only - set during provisioning by the carrier.'
name:
  label: Name
  tab: General
  hint: 'A friendly display name to help identify this number''s purpose (for example, "Main Office" or "Support Line").'
language:
  label: Language
  tab: General
  hint: 'The announcement language for calls to this number. Leave empty to inherit the system default; pick a language to play the matching announcement variant.'
defaultCarrier:
  label: 'Default carrier'
  tab: General
  hint: 'The primary SIP carrier used for outgoing calls made with this number as the caller ID.'
fallbackCarrier:
  label: 'Fallback carrier'
  tab: General
  hint: 'The backup SIP carrier used if the default carrier is unavailable. Must be different from the default carrier.'
handling_strategy.type:
  label: 'Incoming call routing'
  tab: General
  hint: 'Determines how incoming calls to this phone number are routed. Options: Default, Rewrite, Call Flow, Extension, User, SIP Device. Changing this value shows or hides other handling strategy fields.'
handling_strategy.default_callflow_id:
  label: 'Call flow'
  tab: General
  hint: 'The call flow used when an incoming call arrives and the dialled digits match an extension. Visible when type is Default or Rewrite.'
handling_strategy.no_ext_match_callflow_id:
  label: 'Fallback call flow when no extension is found'
  tab: General
  hint: 'The fallback call flow used when an incoming call arrives but no extension match is found. Visible when type is Default or Rewrite.'
handling_strategy.prefix_to_remove:
  label: 'Prefix to remove'
  tab: General
  hint: 'Leading digits stripped from the incoming number before attempting to match an extension. Visible when type is Rewrite.'
handling_strategy.prefix_to_add:
  label: 'Prefix to add'
  tab: General
  hint: 'Digits prepended to the remaining number after the prefix has been removed, before matching an extension. Visible when type is Rewrite.'
handling_strategy.call_flow_id:
  label: 'Call flow'
  tab: General
  hint: 'The call flow that all incoming calls to this number are routed to, bypassing extension matching entirely. Visible when type is Call Flow.'
handling_strategy.extension_id:
  label: Extension
  tab: General
  hint: 'The extension that all incoming calls to this number are routed to directly. Visible when type is Extension.'
handling_strategy.user_id:
  label: User
  tab: General
  hint: 'The user that all incoming calls to this number are routed to directly. Visible when type is User.'
handling_strategy.sip_device_id:
  label: 'Phone / SIP device'
  tab: General
  hint: 'The SIP device that all incoming calls to this number are routed to directly. Visible when type is SIP Device.'
userAssignations:
  label: Users
  tab: 'Outgoing phone number'
  hint: 'Users allowed to use this phone number as their outgoing caller identity.'
groupAssignations:
  label: Groups
  tab: 'Outgoing phone number'
  hint: 'Groups whose members are allowed to use this phone number as their outgoing caller identity.'
sipDeviceAssignations:
  label: 'Phones / SIP devices'
  tab: 'Outgoing phone number'
  hint: 'SIP devices allowed to use this phone number as their outgoing caller identity.'
```