Get Join URL

The getJoinUrl endpoint generates a new /join URL that can be used to create a new session for an existing user. By associating the new session token with the same user ID, all sessions will appear as the same user in the user list, ensuring accurate user counts.

Important

The sessionToken must belong to a connected HTML5 client session. A session token obtained from an API join (redirect=false) without a running client is rejected (e.g. "Meeting not found" on BBB 3.x).

This feature is particularly useful for:

• Hybrid environments where multiple screens in the same room each require a distinct session with different layouts
• Session transfers enabling seamless user session transfers to another device (e.g., mobile device scanning a QR code displayed on a computer)
• Multi-device scenarios where a user wants to join the same meeting from multiple devices simultaneously

API Endpoint

GET http://yourserver.com/bigbluebutton/api/getJoinUrl?[parameters]

Parameters

Usage Examples

Basic Usage

use BigBlueButton\BigBlueButton;
use BigBlueButton\Parameters\GetJoinUrlParameters;

$bbb = new BigBlueButton();

// Get a new join URL for an existing session
$getJoinUrlParams = new GetJoinUrlParameters('existing-session-token-123');

$response = $bbb->getJoinUrl($getJoinUrlParams);

if ($response->success()) {
    $newJoinUrl = $response->getUrl();
    echo "New join URL: " . $newJoinUrl;
} else {
    echo "Error: " . $response->getMessage();
}

Advanced Usage with Session Replacement

use BigBlueButton\BigBlueButton;
use BigBlueButton\Parameters\GetJoinUrlParameters;
use BigBlueButton\Enum\MeetingLayout;

$bbb = new BigBlueButton();

// Create parameters with session replacement
$getJoinUrlParams = new GetJoinUrlParameters('mobile-session-token-456');

// Replace the original session when the new one is used
$getJoinUrlParams->setReplaceSession(true);

// Set a descriptive session name
$getJoinUrlParams->setSessionName('Mobile Device Transfer');

// Enforce a specific layout for the new session
$getJoinUrlParams->setEnforceLayout(MeetingLayout::VIDEO_FOCUS);

// Add custom userdata parameters
$getJoinUrlParams->addUserData('device-type', 'mobile');
$getJoinUrlParams->addUserData('transfer-source', 'desktop');
$getJoinUrlParams->addUserData('screen-size', 'small');

$response = $bbb->getJoinUrl($getJoinUrlParams);

if ($response->success()) {
    echo "New join URL: " . $response->getUrl();
    echo "Session Token: " . $response->getSessionToken();
    echo "Session Name: " . $response->getSessionName();
    echo "Replace Session: " . ($response->isReplaceSession() ? 'Yes' : 'No');
} else {
    echo "Error: " . $response->getMessage();
}

QR Code Generation for Session Transfer

use BigBlueButton\BigBlueButton;
use BigBlueButton\Parameters\GetJoinUrlParameters;

$bbb = new BigBlueButton();

// Generate a join URL for mobile device transfer
$getJoinUrlParams = new GetJoinUrlParameters('desktop-session-token-789');
$getJoinUrlParams->setSessionName('Mobile Transfer from Desktop');
$getJoinUrlParams->addUserData('transfer-initiated', date('Y-m-d H:i:s'));
$getJoinUrlParams->addUserData('device-platform', 'mobile');

$response = $bbb->getJoinUrl($getJoinUrlParams);

if ($response->success()) {
    $joinUrl = $response->getUrl();
    
    // Generate QR code (you'll need a QR code library)
    // $qrCode = generateQRCode($joinUrl);
    
    echo "Scan this QR code to transfer your session to mobile device:";
    echo "Join URL: " . $joinUrl;
} else {
    echo "Failed to generate transfer URL: " . $response->getMessage();
}

Multi-Screen Setup

use BigBlueButton\BigBlueButton;
use BigBlueButton\Parameters\GetJoinUrlParameters;
use BigBlueButton\Enum\MeetingLayout;

$bbb = new BigBlueButton();

// Original session token
$originalToken = 'main-screen-session-001';

// Create second screen with presentation focus
$secondScreenParams = new GetJoinUrlParameters($originalToken);
$secondScreenParams->setSessionName('Second Screen - Presentation View');
$secondScreenParams->setEnforceLayout(MeetingLayout::PRESENTATION_FOCUS);
$secondScreenParams->addUserData('screen-role', 'presentation');

$secondScreenResponse = $bbb->getJoinUrl($secondScreenParams);

// Create third screen with participant focus
$thirdScreenParams = new GetJoinUrlParameters($originalToken);
$thirdScreenParams->setSessionName('Third Screen - Participants View');
$thirdScreenParams->setEnforceLayout(MeetingLayout::PARTICIPANTS_CHAT_ONLY);
$thirdScreenParams->addUserData('screen-role', 'participants');

$thirdScreenResponse = $bbb->getJoinUrl($thirdScreenParams);

if ($secondScreenResponse->success() && $thirdScreenResponse->success()) {
    echo "Second Screen URL: " . $secondScreenResponse->getUrl();
    echo "Third Screen URL: " . $thirdScreenResponse->getUrl();
}

Response Fields

The response is JSON and provides the following fields:

Example of a successful response:

{
    "response": {
        "returncode": "SUCCESS",
        "message": "Join URL provided successfully.",
        "url": "https://yourserver.com/bigbluebutton/api/join?&redirect=true&existingUserID=w_t18rn7uc1wjm&role=MODERATOR&checksum=..."
    }
}

Response Handling

$response = $bbb->getJoinUrl($getJoinUrlParams);

if ($response->success()) {
    echo "Join URL: " . $response->getUrl();
} else {
    echo "Error: " . $response->getMessage();
    echo "Rejected session token: " . $response->getSessionToken();
}

Layout Options

The enforceLayout parameter accepts the same values as the meeting creation:

use BigBlueButton\Enum\MeetingLayout;

// Available layout options
MeetingLayout::UNIFIED_LAYOUT              // BBB 3.0+ (default in 4.0)
MeetingLayout::CAMERAS_ONLY
MeetingLayout::PARTICIPANTS_AND_CHAT_ONLY  // BBB 3.0+ (replaces PARTICIPANTS_CHAT_ONLY)
MeetingLayout::PRESENTATION_ONLY
MeetingLayout::PLUGINS_ONLY                // BBB 3.0+
MeetingLayout::MEDIA_ONLY

Warning

BBB 4.0 no longer accepts CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS and VIDEO_FOCUS. The cases remain available in this library for BBB 2.x/3.x servers, but using them against a 4.0 server has no effect.

Userdata Parameters

Userdata parameters allow you to pass additional information about the session:

Common Userdata Parameters

Adding Userdata Parameters

// Single parameter
$getJoinUrlParams->addUserData('device-type', 'mobile');

// Multiple parameters
$getJoinUrlParams->addUserData('device-type', 'mobile');
$getJoinUrlParams->addUserData('platform', 'iOS');
$getJoinUrlParams->addUserData('app-version', '2.1.0');

// Complex data (JSON encoded)
$deviceInfo = [
    'type' => 'mobile',
    'os' => 'iOS',
    'version' => '15.0',
    'screen' => [
        'width' => 375,
        'height' => 667
    ]
];
$getJoinUrlParams->addUserData('device-info', json_encode($deviceInfo));

Security Considerations

Session Token Security

• Session tokens are sensitive and should be handled securely
• Only share session tokens with authorized users
• Implement proper validation before generating new join URLs

Userdata Validation

• Validate userdata parameters on both client and server side
• Sanitize user input to prevent injection attacks
• Consider implementing a blocklist for sensitive userdata parameters

Session Replacement

• Use replaceSession=true carefully as it immediately invalidates the original session
• Inform users when their original session will be replaced
• Implement proper error handling for session replacement scenarios

Error Handling

Common error scenarios and their handling:

$response = $bbb->getJoinUrl($getJoinUrlParams);

if (!$response->success()) {
    $message = $response->getMessage();
    $statusCode = $response->getStatusCode();
    
    switch ($statusCode) {
        case '404':
            // Session token not found
            echo "Invalid or expired session token";
            break;
            
        case '403':
            // Access denied
            echo "Permission denied for session transfer";
            break;
            
        case '400':
            // Bad request
            echo "Invalid parameters provided";
            break;
            
        default:
            echo "Unknown error: " . $message;
    }
}

Best Practices

1. Session Naming: Use descriptive session names to help users identify different sessions
2. Layout Selection: Choose appropriate layouts for different device types and use cases
3. Userdata Organization: Use consistent naming conventions for userdata parameters
4. Error Handling: Implement comprehensive error handling for all scenarios
5. Security: Validate and sanitize all input parameters
6. User Experience: Provide clear feedback about session transfers and multi-screen setups

Use Case Examples

Education Scenario

A professor wants to display the main presentation on a projector while managing participants on a tablet:

// Main screen (projector) - presentation focus
$projectorParams = new GetJoinUrlParameters($professorSessionToken);
$projectorParams->setSessionName('Projector - Presentation View');
$projectorParams->setEnforceLayout(MeetingLayout::PRESENTATION_FOCUS);

// Tablet screen - participants management
$tabletParams = new GetJoinUrlParameters($professorSessionToken);
$tabletParams->setSessionName('Tablet - Participants Management');
$tabletParams->setEnforceLayout(MeetingLayout::PARTICIPANTS_CHAT_ONLY);

Corporate Scenario

An executive wants to transfer a meeting from desktop to mobile for commuting:

$transferParams = new GetJoinUrlParameters($desktopSessionToken);
$transferParams->setReplaceSession(true);
$transferParams->setSessionName('Mobile Transfer - ' . date('H:i'));
$transferParams->addUserData('transfer-reason', 'commute');
$transferParams->addUserData('connection-type', 'mobile');

Support Scenario

A support agent needs to join a customer meeting with elevated permissions:

$supportParams = new GetJoinUrlParameters($customerSessionToken);
$supportParams->setSessionName('Support Agent Session');
$supportParams->addUserData('role', 'support');
$supportParams->addUserData('support-id', $supportAgentId);
$supportParams->addUserData('elevated-permissions', 'true');

This API provides powerful flexibility for managing user sessions across different devices and scenarios while maintaining user identity and meeting continuity.