Connection patterns

Prepare the media offer. In the browser, capture tracks with navigator.mediaDevices.getUserMedia(). Create an RTCPeerConnection, called pc here, and add each track with pc.addTransceiver(track, { direction: "sendonly" }). Create an offer with await pc.createOffer(), then apply it with await pc.setLocalDescription(offer).

Wait for candidate gathering, then read each transceiver's mid. This identifier associates a media section in this connection's SDP with the track you publish.

Create the SFU session. On your backend, call POST /sessions/new with no request body. Store the returned sessionId with this connection.

Publish the tracks. On the backend, call POST /sessions/{sessionId}/tracks/new with the browser's pc.localDescription as sessionDescription:

{
  "sessionDescription": { "type": "offer", "sdp": "<LOCAL_SDP>" },
  "tracks": [
    { "location": "local", "mid": "<TRANSCEIVER_MID>", "trackName": "camera" }
  ]
}

Replace the placeholders with the generated SDP and assigned mid. To publish camera and microphone together, include both tracks in this request. Each entry uses its own mid and trackName. Refer to batch resource operations.

Apply the answer. In the browser, await pc.setRemoteDescription(response.sessionDescription) with the returned SFU answer. This completes the offer/answer exchange. No /renegotiate call is needed for this answer.

Make the publication discoverable. Wait for the connection to become connected. Share successful publications' session ID and track names with authorized subscribers through your application.

Create the receiving connection. Create a new RTCPeerConnection, called pc, and install a track event handler. On the backend, call POST /sessions/new with no request body. Save its ID as subscriberSessionId.

Request the publication. On the backend, call POST /sessions/{subscriberSessionId}/tracks/new without a local offer:

{
  "tracks": [
    { "location": "remote", "sessionId": "<PUBLISHER_SESSION_ID>", "trackName": "camera" }
  ]
}

To receive several publications together, include one entry for each in tracks. They can come from different publishers. This request adds them all to the same receiving session.

Answer the SFU offer. Map each successful result's receiving mid to its publication before applying the returned offer. In the browser, await pc.setRemoteDescription(response.sessionDescription), then pc.createAnswer() and pc.setLocalDescription(answer).

In the track handler, use event.transceiver.mid to select the publication's playback element. For one received track, set element.srcObject = new MediaStream([event.track]).

Finish the exchange. After candidate gathering, return pc.localDescription to your backend. Send it as sessionDescription to PUT /sessions/{subscriberSessionId}/renegotiate:

{
  "sessionDescription": { "type": "answer", "sdp": "<LOCAL_ANSWER_SDP>" }
}

Continue only after the API accepts the answer.

Verify reception. Wait for the connection to become connected and confirm that the requested media plays. Use media troubleshooting when the connection succeeds but playback does not.

Create both connections. In each browser, create a new RTCPeerConnection. Install a datachannel event listener to retain channels opened by the SFU and close them during teardown. On the backend, call POST /sessions/new with no body for each connection. Save publisherSessionId and subscriberSessionId.

Connect DataChannel transport. For each session, call POST /sessions/{sessionId}/datachannels/establish once:

{
  "dataChannel": {
    "location": "remote",
    "dataChannelName": "server-events"
  }
}

Check the returned dataChannel allocation. The server-events channel is reserved for transport setup. The application channel is allocated separately.

Answer each SFU offer. In the corresponding browser, await pc.setRemoteDescription(response.sessionDescription), create an answer, and await pc.setLocalDescription(answer). After candidate gathering, return pc.localDescription to your backend and send PUT /sessions/{sessionId}/renegotiate:

{
  "sessionDescription": { "type": "answer", "sdp": "<THIS_ENDPOINT_ANSWER_SDP>" }
}

Wait for each answer to be accepted and both PeerConnections to become connected before allocating application channels.

Publish the application channel. On the backend, call POST /sessions/{publisherSessionId}/datachannels/new:

{
  "dataChannels": [{ "location": "local", "dataChannelName": "messages" }]
}

Retain the successful publisher allocation and its id.

Subscribe to the channel. Call POST /sessions/{subscriberSessionId}/datachannels/new:

{
  "dataChannels": [
    {
      "location": "remote",
      "sessionId": "<PUBLISHER_SESSION_ID>",
      "dataChannelName": "messages"
    }
  ]
}

Retain the successful subscriber allocation and its id.

Create the browser channels. Return each allocation's id to its own endpoint as channelId. On each PeerConnection, create the channel with that ID:

const channel = pc.createDataChannel("messages", {
  negotiated: true,
  id: channelId,
});

Publisher and subscriber IDs can differ. This browser configuration matches the reliable, ordered API defaults. Install a message handler on the subscriber and wait for both channels to open.

Send and verify. After the subscriber confirms it is ready through your application, call channel.send("hello") on the publisher. Confirm the subscriber's message event contains hello.

Create the receiving connection. Create a new RTCPeerConnection, called pc. Install track and datachannel listeners. On the backend, call POST /sessions/new with no body and save subscriberSessionId. Do not create browser DataChannels during this first media exchange.

Request media. Call POST /sessions/{subscriberSessionId}/tracks/new without a local offer:

{
  "tracks": [
    { "location": "remote", "sessionId": "<MEDIA_PUBLISHER_SESSION_ID>", "trackName": "camera" }
  ]
}

Map successful receiving mid values to their publications. Use event.transceiver.mid in the track handler to attach each received track to its playback element.

Finish media negotiation. Await pc.setRemoteDescription(response.sessionDescription), pc.createAnswer(), and pc.setLocalDescription(answer). After candidate gathering, send pc.localDescription through your backend to PUT /sessions/{subscriberSessionId}/renegotiate:

{
  "sessionDescription": { "type": "answer", "sdp": "<MEDIA_ANSWER_SDP>" }
}

Wait for the API to accept it and confirm media playback before continuing.

Add DataChannel transport. Keep this same PeerConnection and session. Call POST /sessions/{subscriberSessionId}/datachannels/establish once:

{
  "dataChannel": {
    "location": "remote",
    "dataChannelName": "server-events"
  }
}

Retain the successful allocation and reserved server-events channel for cleanup.

Finish the new negotiation. Apply this new SFU offer with pc.setRemoteDescription(). Create and set a new local answer. After candidate gathering, submit pc.localDescription through your backend to PUT /sessions/{subscriberSessionId}/renegotiate:

{
  "sessionDescription": { "type": "answer", "sdp": "<DATACHANNEL_ANSWER_SDP>" }
}

Await each browser operation and the API's acceptance of the answer. Wait for the PeerConnection to be connected before allocating the control subscription.

Subscribe with reply permission. Call POST /sessions/{subscriberSessionId}/datachannels/new:

{
  "dataChannels": [
    {
      "location": "remote",
      "sessionId": "<CONTROL_PUBLISHER_SESSION_ID>",
      "dataChannelName": "controls",
      "canReply": true
    }
  ]
}

Check the result. At most one subscriber can hold reply access for this publisher channel. Granting access to this subscriber replaces any previous holder. Your backend controls who receives that permission.

Open and verify controls. Return the subscription's id to the browser as channelId:

const controls = pc.createDataChannel("controls", {
  negotiated: true,
  id: channelId,
});

Wait for open. Send a command defined by your application and confirm that the publisher receives it while media continues playing.

Prepare the endpoint's offer. In the browser, save the mid of each transceiver to close, then call its stop() method. Create an offer with await pc.createOffer() and apply it with await pc.setLocalDescription(offer).

Close the tracks. After candidate gathering, send PUT /sessions/{sessionId}/tracks/close from your backend with those mids and the browser's pc.localDescription as sessionDescription:

{
  "tracks": [{ "mid": "<TRANSCEIVER_MID>" }],
  "sessionDescription": { "type": "offer", "sdp": "<LOCAL_SDP>" },
  "force": false
}

Apply the answer. Check request-level and per-track errors. In the browser, await pc.setRemoteDescription(response.sessionDescription) with the returned answer, even if individual tracks failed. Other tracks may have closed.

Handle unfinished work. Complete this exchange before another mutation. Retain failed closures for retry. If no usable answer arrives, follow recovery guidance.