Skip to main content

Pairing Workflow

This guide provides a step-by-step walkthrough for pairing your OPBX instance with Cloudonix. The pairing process connects OPBX to Cloudonix's telephony infrastructure.

Prerequisites Checklist​

Before starting, ensure you have:

  • OPBX installed and running
  • Cloudonix account created
  • Domain UUID from Cloudonix
  • Domain API Key from Cloudonix
  • (For local development) ngrok or similar tunnel running

Step-by-Step Process​

Step 1: Access OPBX Settings​

  1. Open your browser and navigate to OPBX (http://localhost/ui)
  2. Log in as the organization owner
  3. Click Settings in the navigation menu
  4. Locate the Cloudonix Integration section

Step 2: Enter Domain UUID​

  1. In the Domain UUID field, paste your Cloudonix Domain UUID
  2. The field accepts UUID format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Example: 12345678-1234-1234-1234-123456789abc

Step 3: Enter Domain API Key​

  1. In the Domain API Key field, paste your Cloudonix API key
  2. This is the key you generated in the Cloudonix Portal
Example: XI1234567890abcdefghijklmnopqrstuv

Step 4: Validate Credentials​

  1. Click the Validate & Save button

  2. OPBX will:

    • Connect to Cloudonix API
    • Verify your credentials are valid
    • Retrieve your domain profile settings

  3. If successful:

    • You'll see a success message
    • Additional fields may be auto-populated

  4. If failed:

    • Check the error message
    • Verify your Domain UUID and API Key are correct
    • See Troubleshooting for help

Step 5: Review Auto-Populated Settings​

After successful validation, OPBX automatically populates:

FieldSourceCan Modify
Domain NameCloudonix domainNo (read-only)
No Answer TimeoutCloudonix domain settingYes
Recording FormatCloudonix domain settingYes
PackageCloudonix billing infoNo (read-only)

Step 6: Configure Webhook Base URL​

  1. Enter your Webhook Base URL
  2. Local Development: Use your ngrok URL 
    Example: https://abc123.ngrok-free.app
  3. Production: Use your public domain 
    Example: https://pbx.yourcompany.com

This URL is used by Cloudonix to send webhooks to OPBX.

Step 7: (Optional) Generate Requests API Key​

For enhanced security:

  1. Click Generate next to Requests API Key (if available)
  2. Or paste your own Requests API Key from Cloudonix
  3. Click the copy icon to save the generated key
Save This Key

If you generate a new key, copy it immediately. It will not be shown again.

Step 8: Save Settings​

  1. Click Save Settings

  2. OPBX will:

    • Store settings in the local database
    • Create/update Voice Application in Cloudonix
    • Configure webhook endpoints

  3. You'll see a success message when complete

What Happens During Save​

When you save settings, OPBX performs several operations:

1. Local Storage​

Settings are encrypted and stored in the OPBX database.

2. Voice Application Creation​

OPBX creates a Voice Application in Cloudonix (if one doesn't exist):

  • Name: OPBX - [Organization Name]
  • Webhook URL: Points to your OPBX instance
  • Default Application: Set as domain default

3. Webhook Configuration​

OPBX automatically configures webhook endpoints:

EndpointPurpose
/api/voice/routeRequest routing instructions
/api/webhooks/cloudonix/session-updateCall state events
/api/webhooks/cloudonix/cdrCall detail records

Verification Steps​

After completing the pairing:

1. Check Settings Status​

The Settings page should show:

  • Status: Configured
  • All required fields filled
  • Green checkmarks indicating valid credentials

2. Test Webhook Delivery​

  1. Navigate to the Extensions page
  2. Create a test extension
  3. The extension should sync to Cloudonix as a subscriber
  4. Check Cloudonix Portal to verify the subscriber exists

3. Verify Voice Application​

In Cloudonix Portal:

  1. Go to Voice Applications
  2. Verify an app named "OPBX - [Your Org]" exists
  3. Check that webhook URLs point to your OPBX instance

Troubleshooting Save Issues​

If saving fails:

ErrorSolution
"Invalid credentials"Verify Domain UUID and API Key
"Network error"Check connectivity to Cloudonix
"Voice application creation failed"Check API permissions
"Webhook URL unreachable"Verify ngrok is running / URL is correct

Complete Flow Diagram​

Next Steps​

After successful pairing:

  1. Extension Synchronization - Sync your extensions to Cloudonix
  2. Webhook Configuration - Understand webhook events
  3. Create Extensions - Start creating extensions

Related Documentation: