Core Concepts

Understanding these fundamental concepts is essential for effectively using OPBX.

Organizations (Tenants)

An Organization represents a tenant in the OPBX multi-tenant architecture. Each organization is a completely isolated environment with its own:

• Users
• Extensions
• Phone numbers
• Call logs
• Settings
• Configuration

Why Multi-Tenant?

This design enables:

• Service Providers: Manage PBX for multiple clients from one platform
• Franchises: Independent locations with centralized oversight
• Enterprises: Separate departments with shared infrastructure
• Data Isolation: Complete separation of data between organizations

Organization Properties

Property	Description
Name	Display name for the organization
Slug	URL-friendly identifier (auto-generated)
Timezone	Primary timezone for the organization
Status	Active, Suspended, or Deleted

tip

Most users will only ever work with one organization. Platform managers can oversee multiple organizations.

Users and Role-Based Access Control

User Roles

OPBX uses role-based access control (RBAC) with four distinct roles:

Owner

• Full Access: Complete control over the organization
• Billing: Access to billing and subscription settings
• User Management: Can create, modify, and delete all users
• Critical Operations: Can delete the organization
• Best For: Company administrators, IT directors

PBX Admin

• Configuration Access: Full PBX configuration rights
• Extensions: Create and manage extensions
• Phone Numbers: Configure DIDs and routing
• Ring Groups: Set up hunt groups
• IVR Menus: Create voice menus
• Cannot: Access billing, delete organization
• Best For: IT staff, phone system administrators

PBX User

• Assigned Extension: Has one extension assigned
• Personal Settings: Can modify own extension settings
• Voicemail: Access to personal voicemail
• Call History: View own call logs
• Cannot: Access admin features, view other users' data
• Best For: Regular employees, phone users

Reporter

• Read-Only Access: View reports and analytics
• Call Logs: Access all call logs (read-only)
• Statistics: View dashboards and metrics
• Cannot: Modify any settings or data
• Best For: Managers, auditors, analysts

Role Permissions Matrix

Feature	Owner	PBX Admin	PBX User	Reporter
View Dashboard	✅	✅	✅	✅
Manage Users	✅	✅	❌	❌
Manage Extensions	✅	✅	Own only	❌
Manage Phone Numbers	✅	✅	❌	❌
Configure Ring Groups	✅	✅	❌	❌
Set Up IVR	✅	✅	❌	❌
View Call Logs	✅	✅	Own only	✅
Access Billing	✅	❌	❌	❌
Delete Organization	✅	❌	❌	❌

User Status

Users can have one of three statuses:

Status	Description
Active	User can log in and use the system
Inactive	User cannot log in, but data is preserved
Suspended	Temporarily blocked, can be reactivated

Extensions and Users

What is an Extension?

An Extension is a telephone endpoint in the PBX system. It represents:

• A physical desk phone
• A softphone application
• A user agent for making/receiving calls

Extension vs User

While closely related, extensions and users are distinct:

Extension Numbering

Extensions use numeric identifiers:

• Format: 1-20 digits
• Common Range: 100-999
• Examples: 101, 102, 1001, 2000

Best Practice

Use a numbering scheme:

• 100-199: Management
• 200-299: Sales
• 300-399: Support
• 1000+: Remote workers

SIP Credentials

Each extension gets auto-generated SIP credentials:

Field	Example	Purpose
Username	101_acme	SIP authentication
Password	Auto-generated	SIP authentication
Domain	acme.cloudonix.io	SIP server address

These credentials are used to configure desk phones or softphones.

Voicemail

Extensions can have voicemail enabled:

• PIN: 4-10 digit code to access voicemail
• Greeting: Custom or system default
• Email: Voicemail notifications (if configured)

Call Forwarding Rules

Extensions support flexible call forwarding:

Rule	Description	Example
No Answer	Forward after X seconds	→ Voicemail after 20s
Busy	Forward when on another call	→ Ring group
Unavailable	Forward when offline	→ Voicemail

Call Routing Fundamentals

Inbound Call Flow

Routing Destinations

Destination	Use Case
Extension	Direct to specific user
Ring Group	Distribute to a team
IVR Menu	Interactive voice response
Voicemail	Leave a message
Hangup	Terminate call

Outbound Calling

Extensions can make outbound calls:

1. User dials number from extension
2. OPBX validates outbound permissions
3. Call routed through Cloudonix
4. Connected to external number

Ring Groups (Hunt Groups)

Ring groups distribute incoming calls to multiple extensions:

Ringing Strategies

Strategy	Behavior	Best For
Simultaneous	All members ring at once	Sales teams (first available)
Round Robin	Rotate through members evenly	Support (fair distribution)
Sequential	Follow priority order	Escalation paths
Least Recent	Ring least recently called	Balanced workload

Cloudonix Integration Overview

What is Cloudonix?

Cloudonix is a Cloud Platform as a Service (CPaaS) that provides:

• SIP trunking and VoIP infrastructure
• Phone number (DID) provisioning
• Call routing and media handling
• Webhook integrations

Why Integration is Required

OPBX is the management layer, Cloudonix is the VoIP infrastructure:

The Pairing Workflow

To enable VoIP functionality:

1. Configure Credentials: Enter Cloudonix API token in OPBX settings
2. Validate Connection: OPBX tests connectivity to Cloudonix
3. Sync Extensions: OPBX creates SIP endpoints in Cloudonix
4. Configure DIDs: Map phone numbers to OPBX webhooks
5. Test Calling: Verify inbound and outbound calls work

warning

Without Cloudonix integration:

• Extensions won't receive calls
• Outbound calling won't work
• Phone numbers can't be configured

The system will function for user management, but telephony features require Cloudonix.

Webhook Communication

Cloudonix communicates with OPBX via webhooks:

• Voice Routing: Cloudonix → OPBX (/api/voice/route)
• Call Events: Cloudonix → OPBX (CDR, session updates)
• Authentication: Secured with API keys

Summary

Understanding these concepts enables you to:

• Organizations: Set up isolated environments for different clients or departments
• Users: Control who can access and manage what
• Extensions: Configure phone endpoints with voicemail and forwarding
• Routing: Design efficient call flows using ring groups and IVRs
• Cloudonix: Enable VoIP by pairing with the telephony infrastructure

---

Ready to continue?

→ Cloudonix Pairing to enable VoIP
→ Users to learn about user management
→ Extensions to configure phone endpoints