RTCPeerConnection: negotiationneeded event

A negotiationneeded event is sent to the RTCPeerConnection when negotiation of the connection through the signaling channel is required. This occurs both during the initial setup of the connection as well as any time a change to the communication environment requires reconfiguring the connection.

Bubbles No
Cancelable No
Interface Event
Event handler property RTCPeerConnection.onnegotiationneeded

The negotiationneeded event is first dispatched to the RTCPeerConnection when media is first added to the connection. This starts the process of ICE negotiation by instructing your code to begin exchanging ICE candidates through the signaling server. See Signaling transaction flow in Signaling and video calling for a description of the signaling process that begins with a negotiationneeded event.

Examples

In this example, we use addEventListener() to create an event handler for negotiationneeded. Its role is to create an SDP offer and send it through the signaling channel to the remote peer.

pc.addEventListener("negotiationneeded", ev => {
  pc.createOffer()
  .then(offer => return pc.setLocalDescription(offer))
  .then(() => sendSignalingMessage({
    type: "video-offer",
    sdp: pc.localDescription
  }))
  .catch(err => {
    /* handle error */
  );
}, false);

After creating the offer, the local end is configured by calling RTCPeerConnection.setLocalDescription(); then a signaling message is created and sent to the remote peer through the signaling server, to share that offer with the other peer. The other peer should recognize this message and follow up by creating its own RTCPeerConnection, setting the remote description with setRemoteDescription(), and then creating an answer to send back to the offering peer.

You can also set an event handler for the negotiationneeded event by assigning the event handler function to the RTCPeerConnection.onnegotiationneeded property:

pc.onnegotiationneeded = ev => {
  pc.createOffer()
  .then(offer => return pc.setLocalDescription(offer))
  .then(() => sendSignalingMessage({
    type: "video-offer",
    sdp: pc.localDescription
  }))
  .catch(err => {
    /* handle error */
  );
};

For a more detailed example, see Starting negotiation in Signaling and video calling.

Specifications

Specification Status Comment
WebRTC 1.0: Real-time Communication Between Browsers
The definition of 'negotiationneeded' in that specification.
Candidate Recommendation

Browser compatibility

DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
negotiationneeded eventChrome Full support 24Edge Full support 15Firefox Full support 22IE No support NoOpera Full support 43Safari Full support 11WebView Android Full support YesChrome Android Full support YesFirefox Android Full support 44Opera Android Full support 43Safari iOS ? Samsung Internet Android Full support 6.0

Legend

Full support
Full support
No support
No support
Compatibility unknown
Compatibility unknown

See also