JitsiConnection

XMPP connection management, authentication, and lifecycle

The JitsiConnection class manages the XMPP connection to Jitsi Meet servers and provides the foundation for creating conferences.

Overview

JitsiConnection handles:

• XMPP connection establishment and lifecycle
• Authentication with JWT tokens or passwords
• Connection state management
• Conference creation
• Feature advertising

Creating a Connection

Connections are created using the main library API:

const connection = new JitsiConnection(appID, token, options);

Constructor Parameters

interface IConnectionOptions {
    serviceUrl: string;                    // WebSocket/BOSH service URL
    hosts: {
        domain: string;                    // XMPP domain
    };
    enableWebsocketResume: boolean;        // Enable connection resume
    p2pStunServers: any[];                // STUN servers for P2P
    websocketKeepAlive?: number;          // Keep-alive interval
    websocketKeepAliveUrl?: string;       // Keep-alive endpoint
    flags?: Record<string, any>;          // Feature flags
    // ... additional options
}

From JitsiConnection.ts:16-34:

Constructor Implementation

export default class JitsiConnection {
    constructor(appID: string, token: Nullable<string>, options: IConnectionOptions) {
        this.appID = appID;
        this.token = token;
        this.options = options;

        // Initialize the feature flags so that they are advertised through the disco-info.
        FeatureFlags.init(options.flags || {});

        this._xmpp = new XMPP(options, token);

        this.addEventListener(JitsiConnectionEvents.CONNECTION_FAILED,
            (errType: string, msg: string, credentials: any, details: any) => {
                Statistics.sendAnalyticsAndLog(
                    createConnectionFailedEvent(errType, msg, details));
            });
    }
}

Connection Lifecycle

Connecting

The connect() method establishes the XMPP connection:

connection.connect({
    id: 'user@domain',           // Optional: username
    password: 'password',        // Optional: password  
    name: 'room-name'           // Optional: room name for conference request
});

From JitsiConnection.ts:105-120:

Connect Method

connect(options: IConnectOptions = {}): void {
    RTCStats.startWithConnection(this);

    // if we get redirected, we set disableFocus to skip sending the conference request twice
    if (this.xmpp.moderator.targetUrl && !this.options.disableFocus && options.name) {
        // The domain (optional) will uses this.options.hosts.muc.toLowerCase() if not provided
        this.xmpp.moderator.sendConferenceRequest(this.xmpp.getRoomJid(options.name, undefined))
            .then(() => {
                this.xmpp.connect(options.id, options.password);
            })
            .catch(e => logger.trace('sendConferenceRequest rejected', e));
    } else {
        this.xmpp.connect(options.id, options.password);
    }
}

The connection can send an HTTP conference request to Jicofo before establishing the XMPP connection when both options.name is provided and the redirect URL is configured.

Attaching to Existing Connection

For optimization, you can attach to an existing connection:

connection.attach({
    jid: 'user@domain/resource',
    rid: '1234567',  // Request ID
    sid: 'session-id' // Session ID
});

Disconnecting

Clean up the connection:

await connection.disconnect();

From JitsiConnection.ts:138-144:

disconnect(...args: any): boolean | Promise<void> {
    // Forward any arguments to XMPP.disconnect for finer-grained context
    return this.xmpp.disconnect(...args);
}

Connection Events

All connection events are defined in JitsiConnectionEvents.ts:5-60:

CONNECTION_ESTABLISHED

Fired when the connection is successfully established:

connection.addEventListener(
    JitsiConnectionEvents.CONNECTION_ESTABLISHED,
    (id: string) => {
        console.log('Connected with ID:', id);
    }
);

Parameters:

• id (string) - The ID of the local endpoint/participant/peer

CONNECTION_FAILED

Fired when connection fails:

connection.addEventListener(
    JitsiConnectionEvents.CONNECTION_FAILED,
    (errType, errReason, credentials, errReasonDetails) => {
        console.error('Connection failed:', errType, errReason);
    }
);

Parameters:

• errType (JitsiConnectionErrors) - The type of error
• errReason (string) - Error message
• credentials (object) - Credentials used to connect
• errReasonDetails (object) - Additional error details for analytics

CONNECTION_DISCONNECTED

Fired when connection is closed:

connection.addEventListener(
    JitsiConnectionEvents.CONNECTION_DISCONNECTED,
    (msg: string) => {
        console.log('Disconnected:', msg);
    }
);

Parameters:

• msg (string) - Message associated with disconnect (e.g., last error)

Other Connection Events

Event	Description
CONNECTION_REDIRECTED	Connection is redirected to a visitor node
CONNECTION_TOKEN_EXPIRED	Token expired during connection resume
DISPLAY_NAME_REQUIRED	Display name is required (e.g., for lobby)
PROPERTIES_UPDATED	Connection properties updated (shard, region)

Authentication

JWT Token Authentication

Provide a JWT token during construction:

const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';
const connection = new JitsiConnection('myapp', token, options);
connection.connect();

Token Refresh

Renew tokens before expiration:

await connection.refreshToken(newToken);

From JitsiConnection.ts:159-163:

refreshToken(token: string): Promise<void> {
    this.token = token;
    return this._xmpp.refreshToken(this.token);
}

Token refresh is critical for long-running conferences. Implement token renewal before expiration to avoid disconnection.

Password Authentication

Provide credentials in the connect options:

connection.connect({
    id: '[e-mail]',
    password: 'secret'
});

Creating Conferences

Once connected, create a conference:

const conference = connection.initJitsiConference('room-name', {
    openBridgeChannel: 'websocket',
    p2p: { enabled: true },
    // ... other options
});

From JitsiConnection.ts:173-179:

initJitsiConference(name: Nullable<string>, options: Record<string, any>): JitsiConference {
    return new JitsiConference({
        config: options,
        connection: this,
        name
    });
}

Room names must be lowercase. The constructor will throw an error if the name contains uppercase characters.

Feature Management

Advertise client capabilities:

// Add a feature
connection.addFeature('urn:xmpp:jingle:apps:rtp:audio', true);

// Remove a feature  
connection.removeFeature('urn:xmpp:jingle:apps:rtp:audio', true);

From JitsiConnection.ts:214-227:

addFeature(feature: string, submit: boolean = false): void {
    this.xmpp.caps.addFeature(feature, submit, true);
}

removeFeature(feature: string, submit: boolean = false): void {
    this.xmpp.caps.removeFeature(feature, submit, true);
}

Parameters:

• feature - Feature name (usually URN format)
• submit - If true, immediately submit the new feature list to peers

Utilities

Get Connection JID

Retrieve the participant’s JID:

const jid = connection.getJid();
console.log('My JID:', jid); // '[e-mail]/abc12345'

Connection Times

Get connection timing information for analytics:

const times = connection.getConnectionTimes();
console.log('Connection times:', times);

Connection Logs

Retrieve internal logs for debugging:

const logs = connection.getLogs();
console.log('XMPP log:', logs.metadata.xmpp);
console.log('Jingle log:', logs);

From JitsiConnection.ts:233-251:

getLogs(): Record<string, any> {
    const data = this.xmpp.getJingleLog();
    const metadata: Record<string, any> = {};

    metadata.time = new Date();
    metadata.url = window.location.href;
    metadata.ua = navigator.userAgent;

    const log = this.xmpp.getXmppLog();
    if (log) {
        metadata.xmpp = log;
    }

    data.metadata = metadata;
    return data;
}

Best Practices

Handle Connection Events

Always listen for connection events to handle failures gracefully:

connection.addEventListener(JitsiConnectionEvents.CONNECTION_FAILED, (error) => {
    // Show user-friendly error message
    // Implement retry logic
    // Log error for debugging
});

Manage Token Lifecycle

Implement token refresh before expiration:

// Refresh token 5 minutes before expiration
const refreshTime = tokenExpiration - Date.now() - (5 * 60 * 1000);
setTimeout(async () => {
    const newToken = await fetchNewToken();
    await connection.refreshToken(newToken);
}, refreshTime);

Clean Up Resources

Always disconnect properly to free resources:

window.addEventListener('beforeunload', async () => {
    await connection.disconnect();
});

Related Concepts

JitsiConference

Learn about conference lifecycle and room management

Architecture

Understand the overall library architecture