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
- 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
- Navigate to Extensions in the sidebar
- Click Create Extension
- Enter an extension number (3-5 digits, unique within your organization)
- Select the extension type
- Configure type-specific settings
- 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
- Open the extension details
- Click Reset Password
- The new password displays immediately
- Update the SIP phone configuration
note
Resetting the SIP password disconnects any active registrations. The SIP phone must re-register with the new credentials.
Sync to Cloudonix
- Go to Extensions in the sidebar
- Click Sync to Cloudonix
- The system creates SIP subscribers for all USER-type extensions
- 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 |
cloudonix_subscriber_id | string nullable | Cloudonix sync tracking |
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