Phone Numbers (DIDs)

Direct Inward Dialing (DID) numbers are the phone numbers that external callers dial to reach your organization. This page explains how to manage phone numbers and configure their routing.

Purpose

Use this module to:

• Add and label phone numbers
• Configure inbound call routing
• Enable or disable numbers
• Choose from multiple destination types

Phone Number Format

OPBX stores phone numbers in E.164 international format:

• Starts with a plus sign (+)
• Followed by country code
• Followed by national number

Example: +14155551234 (US number, 415 area code)

A non-E.164 mode is available for internal or special-use numbers.

warning

Phone numbers are immutable after creation. If you need to change a number, delete the old entry and add a new one.

Routing Types

When a call arrives at a DID, OPBX routes it to a destination:

Routing Type	Routes To	Best For
Extension	A specific extension	Direct lines
Ring Group	A group of extensions	Department coverage
IVR Menu	Interactive voice menu	Main company number
Business Hours	Time-based routing	Open/closed handling
Conference Room	Conference bridge	Dedicated conference lines
AI Assistant	AI voice agent	Automated support
AI Load Balancer	Distributed AI agents	High-volume AI routing

Permissions

Action	Owner	PBX Admin	PBX User	Reporter
View phone numbers	Yes	Yes	Yes	Yes
Create phone numbers	Yes	Yes	No	No
Update phone numbers	Yes	Yes	No	No
Delete phone numbers	Yes	Yes	No	No

UI Workflow

Add a Phone Number

1. Navigate to Phone Numbers in the sidebar
2. Click Add Phone Number
3. Enter the number in E.164 format (for example, +14155551234)
4. Enter an optional friendly name
5. Select the routing type
6. Choose the destination
7. Save the configuration

tip

Use a consistent format for all numbers. Include the plus sign and country code to ensure proper routing.

Change Routing

1. Find the number in the Phone Numbers list
2. Click to edit
3. Select a new routing type
4. Choose the new destination
5. Save changes

Routing changes take effect immediately. Active calls are not affected, but new calls follow the new routing.

Phone Number Status

Status	Behavior
Active	Routes calls to the configured destination
Inactive	Calls are rejected

Set a number to Inactive when:

• The number is being ported
• You want to temporarily block calls
• The number is reserved for future use

Key Data Fields

did_numbers Table

Column	Type	Notes
id	bigint	Primary key
organization_id	FK	Tenant scope
phone_number	string(20)	Globally unique, immutable
friendly_name	string nullable	Display label
routing_type	enum	extension, ring_group, business_hours, conference_room, ai_assistant, ivr_menu, ai_load_balancer
routing_config	JSON	{extension_id: N} etc.
status	enum	active, inactive
cloudonix_config	JSON nullable	Cloudonix metadata

Related API Endpoints

Method	Endpoint	Purpose
GET/POST/PUT/DELETE	/v1/phone-numbers[/{phoneNumber}]	Standard CRUD

See the OPBX REST API reference for full schemas.

Best Practices

• Label numbers with their purpose (Sales, Support, Main)
• Use consistent routing patterns for similar numbers
• Document which numbers are published externally
• Test each number after configuration

Related Modules

• Extensions — Extension routing target
• Ring Groups — Ring group routing target
• IVR Menus — IVR routing target
• Business Hours — Time-based routing target