Peer Connection Events

Web only

This feature is only available in the JavaScript/TypeScript SDK.

When a call is initiated or received, the Client SDK creates an RTCPeerConnection internally. The peerConnectionCreated event gives you access to this object the moment it is instantiated — before ICE gathering begins — so you can subscribe to any WebRTC lifecycle events you need.

This is useful for observing low-level connection diagnostics such as ICE gathering progress, connection state transitions, and failure detection.

client.on('peerConnectionCreated', (callId, pc) => {
  console.log(`Peer connection created for call ${callId}`);

  pc.addEventListener('connectionstatechange', () => {
    console.log(`[PC ${callId}] connectionState: ${pc.connectionState}`);
  });

  pc.addEventListener('iceconnectionstatechange', () => {
    console.log(
      `[PC ${callId}] iceConnectionState: ${pc.iceConnectionState}`
    );
  });

  pc.addEventListener('icegatheringstatechange', () => {
    console.log(`[PC ${callId}] iceGatheringState: ${pc.iceGatheringState}`);
  });
});

Call ID availability

Call direction	callId
Inbound	Available — the call ID is known before media setup begins
Outbound	null — the server has not yet assigned an ID at the point the peer connection is created

Subscribing to WebRTC events

The snippet above demonstrates subscribing to connectionstatechange, iceconnectionstatechange, and icegatheringstatechange. These are the most useful events for diagnosing call connectivity issues. The full list of RTCPeerConnection events is available in the MDN documentation.

Collecting call quality stats

To collect real-time quality metrics during a call, use pc.getStats() on the peer connection. This returns WebRTC statistics (jitter, packet loss, round-trip time) that can help diagnose audio quality issues. See MDN RTCPeerConnection.getStats() for details.