Connecting to Rooms

The MaxConf API is consumed by the IDIM server infrastructure (Identity Information Management), not directly by the BCSC mobile app. IDIM coordinates room creation and returns connection details to the BCSC app, which then connects to the Pexip conference node via WebRTC.

Connection flow

sequenceDiagram
    participant BCSC as BCSC Mobile App
    participant IDIM as IDIM Server Infrastructure
    participant API as MaxConf API
    participant Pexip as Pexip Conference Node
    participant Genesys as Genesys Cloud Queue

    BCSC->>IDIM: Identity verification request
    IDIM->>API: POST /room/create (uuiData)
    API-->>IDIM: ConstrainedConference<br/>(name, guest_pin, aliases)
    IDIM-->>BCSC: Room connection details<br/>(conference node, alias, guest_pin)
    BCSC->>Pexip: WebRTC connect<br/>(conference node, alias, guest_pin)
    Pexip->>Pexip: Room auto-dials SIP endpoint
    Pexip->>Genesys: SIP INVITE → queue
    Genesys-->>Pexip: Agent answers
    Note over BCSC,Pexip: Citizen video active
    Note over Pexip,Genesys: Agent video active

Connection parameters

The following values are used by the client (BCSC app or Agent App widget) to initiate a WebRTC session with the Pexip conference node:

Parameter	Source	Description
Conference node	Environment config	The Pexip conference node hostname
Alias	Response aliases[0].alias or name	The room dial string
PIN	Response guest_pin	Guest PIN for citizen entry
Display name	Client-determined	Name shown in the conference participant list
Bandwidth	Client-determined	Max media bandwidth in kbps (default: 1264)

Conference node hosts

Environment	Conference Node
Test	conference.test.vc.maxconf.ca
Production	conference.vc.maxconf.ca

The conference node is not returned in the API response - it is configured in the client application’s environment settings. The API provides the room identity (alias + PIN); the client already knows which conference node to connect to.

Citizen connection (BCSC Mobile App)

The BCSC mobile app does not call the MaxConf API directly. The IDIM server infrastructure handles room creation and provides the BCSC app with connection details:

1. IDIM calls POST /room/create and receives the ConstrainedConference response
2. IDIM provides the BCSC app with the conference alias, guest PIN, and conference node
3. The BCSC app connects to the conference node via WebRTC using the Pexip client SDK
4. The citizen enters the room as a guest participant

Agent connection (Agent App Widget)

The Agent App widget uses a different path:

1. Receives the room name via Genesys Cloud interaction attributes
2. Calls GET /public/room/{room_name} (authenticated with Genesys token via x-auth-token)
3. Connects to the conference node using the host PIN (hardcoded in config as conferencePin)
4. The agent enters the room as the host participant

sequenceDiagram
    participant Agent as Agent Desktop
    participant Widget as Agent App Widget
    participant API as MaxConf API
    participant Pexip as Conference Node

    Agent->>Widget: Interaction received (room_name in attributes)
    Widget->>API: GET /public/room/{room_name}<br/>(x-auth-token: Genesys token)
    API-->>Widget: Room details
    Widget->>Pexip: WebRTC connect<br/>(conference node, alias, host PIN)
    Note over Widget,Pexip: Agent video session active

PexRTC client SDK

Both the Agent App and BCSC app use the PexRTC JavaScript SDK to establish the WebRTC connection. The SDK handles:

• ICE candidate negotiation
• Media stream setup (video + audio)
• PIN authentication with the conference node
• Connection lifecycle events (setup, connect, disconnect, error)

Key SDK parameters

// Initialize PexRTC
const pexrtc = new PexRTC();

// Start the call
pexrtc.makeCall(
  conferenceNode, // "conference.test.vc.maxconf.ca"
  conferenceAlias, // room name from API response
  displayName, // participant display name
  bandwidth, // max bandwidth in kbps
);

// After setup event fires, authenticate:
pexrtc.connect(pin); // guest_pin for citizens, host pin for agents

Automatic SIP dial-out

When the first participant joins a room, Pexip Infinity’s automatic participant feature triggers a SIP call to the configured Genesys Cloud queue:

• The SIP endpoint is defined in the VMR’s automatic_participants configuration on the Pexip management node
• The call routes to a Genesys Cloud SBC trunk → queue (e.g., SBC_VBV_TEST)
• An available agent’s desktop receives the interaction, which triggers the Agent App widget

This dial-out is configured on the Pexip management node and is not controlled by the MaxConf API.