Extensions

Extensions are the foundation of your PBX system. They represent numbered endpoints that callers can reach directly or through routing configurations.

Purpose

Use this module to:

• Create and manage extension endpoints
• Assign extensions to users
• Configure extension-specific routing
• Assign a default outbound caller ID per extension
• Sync user extensions to Cloudonix as SIP subscribers
• Reset SIP passwords

Extension Types

OPBX supports multiple extension types for different use cases:

Type	Value	Description	Configuration
User	user	SIP phone extension for a person	Assigned to a user, auto-generated SIP password
Conference	conference	Routes to a conference room	Select conference room
Ring Group	ring_group	Routes to a ring group	Select ring group
IVR	ivr	Routes to an IVR menu	Select IVR menu
AI Assistant	ai_assistant	Routes to an AI provider	Select AI assistant
AI Load Balancer	ai_load_balancer	Routes to AI load balancer	Select load balancer
Forward	forward	Forwards to external number	Enter phone number
Custom Logic	custom_logic	Custom application routing	Container app/block name

Permissions

Action	Owner	PBX Admin	PBX User	Reporter
View extensions	Yes	Yes	Yes	Yes
Create extensions	Yes	Yes	No	No
Update extensions	Yes	Yes	Own only	No
Delete extensions	Yes	Yes	No	No

UI Workflow

Create an Extension

1. Navigate to Extensions in the sidebar
2. Click Create Extension
3. Enter an extension number (3-5 digits, unique within your organization)
4. Select the extension type
5. Configure type-specific settings
6. Save the extension

warning

Extension numbers cannot be changed after creation. If you need a different number, delete the extension and create a new one.

Reset a SIP Password

1. Open the extension details
2. Click Reset Password
3. The new password displays immediately
4. Update the SIP phone configuration

note

Resetting the SIP password disconnects any active registrations. The SIP phone must re-register with the new credentials.

Set a Default Caller ID

An extension can be assigned a Default Caller ID — an active DID owned by your organization that is presented when the user places an outbound call.

1. Open the extension's create or edit dialog
2. Select a DID under Default Caller ID (or leave it unset)
3. Save

An extension's Default Caller ID takes precedence over the caller ID configured on an Outbound Whitelist rule. See the Outbound Calling Overview for the full precedence order and rationale.

Sync to Cloudonix

1. Go to Extensions in the sidebar
2. Click Sync to Cloudonix
3. The system creates SIP subscribers for all USER-type extensions
4. Compare local and Cloudonix state before confirming if desired

Cloudonix Synchronization

User extensions sync to Cloudonix as SIP subscribers. The sync lifecycle is:

• Create USER: Auto-generate a 32-character hex password, insert into DB, then create the Cloudonix subscriber
• Type change TO USER: Generate a password and sync to Cloudonix
• Type change FROM USER: Remove the password and unsync from Cloudonix
• Delete USER: Unsync from Cloudonix, then delete from DB
• Bidirectional sync: Pushes local changes, imports Cloudonix subscribers, and aligns statuses

Key Data Fields

extensions Table

Column	Type	Notes
id	bigint	Primary key
organization_id	FK	Tenant scope
user_id	FK nullable	Only for USER type
extension_number	string(5)	3-5 digits, unique per org, immutable
password	string(32)	SIP auth password (plain text for SIP client sharing)
type	enum	user, conference, ring_group, ivr, ai_assistant, custom_logic, forward, ai_load_balancer
status	enum	active, inactive
voicemail_enabled	boolean	Only for USER type
configuration	JSON	Type-specific config
ai_assistant_id	FK nullable	Direct AI assistant link
default_caller_id_did_id	FK nullable	DID presented as caller ID on outbound calls
cloudonix_subscriber_id	string nullable	Cloudonix sync tracking

The API also returns a nested default_caller_id object (id, phone_number, friendly_name) when the relationship is loaded.

Related API Endpoints

Method	Endpoint	Purpose
GET/POST/PUT/DELETE	/v1/extensions[/{extension}]	Standard CRUD
GET	/v1/extensions/sync/compare	Compare local vs Cloudonix state
POST	/v1/extensions/sync	Perform bidirectional sync
GET	/v1/extensions/{extension}/password	View current SIP password
PUT	/v1/extensions/{extension}/reset-password	Reset SIP password

See the OPBX REST API reference for full schemas.

Best Practices

Numbering Plan

Develop a consistent numbering plan for your organization:

• Reserve 3-digit extensions for departments (for example, 100-199 for sales)
• Use 4-digit extensions for individual users
• Avoid numbers that conflict with feature codes

Security

• Reset SIP passwords periodically
• Disable extensions instead of leaving them active but unused
• Monitor registration logs for unauthorized devices

Related Modules

• User Management — Assign users to extensions
• Phone Numbers — DIDs route to extensions
• Ring Groups — Extensions are ring group members
• AI Assistants — AI_ASSISTANT type extensions
• Outbound Calling Overview — How the per-extension caller ID is used