RTCPeerConnection: createOffer() method

BaselineWidely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2017.

ThecreateOffer() method of theRTCPeerConnection interface initiates the creation of anSDP offer for the purpose of starting a new WebRTC connection to a remote peer.

The SDP offer includes information about anyMediaStreamTrack objects already attached to the WebRTC session, codec, and options supported by the browser, and any candidates already gathered by theICE agent, for the purpose of being sent over the signaling channel to a potential peer to request a connection or to update the configuration of an existing connection.

Syntax

createOffer()createOffer(options)createOffer(successCallback, failureCallback) // deprecatedcreateOffer(successCallback, failureCallback, options) // deprecated

Parameters

optionsOptional

An object providing the following options requested for the offer:

iceRestartOptional: To restart ICE on an active connection, set this totrue.This will cause the returned offer to have different credentials than those already in place.If you then apply the returned offer, ICE will restart.Specifyfalse to keep the same credentials and therefore not restart ICE.The default isfalse. Instead of using this option, consider callingRTCPeerConnection.restartIce(), which will automatically set this flag the next timecreateOffer() is called.
offerToReceiveAudioOptional Deprecated: Provides additional control over the directionality of audio. For example, it can be used to ensure that audio can be received, regardless if audio is sent or not.
offerToReceiveVideoOptional Deprecated: Provides additional control over the directionality of video. For example, it can be used to ensure that video can be received, regardless if video is sent or not.

Deprecated parameters

In older code and documentation, you may see a callback-based version of this function.This has been deprecated and its use isstrongly discouraged.You should update any existing code to use thePromise-based version ofcreateOffer() instead.The parameters for the older form ofcreateOffer() are described below, to aid in updating existing code.

successCallbackDeprecated: Acallback function which will be passed a singleRTCSessionDescription object describing the newly-created offer.
errorCallbackDeprecated: Acallback function which will be passed a singleDOMException object explaining why the request to create an offer failed.
optionsOptional: An optional object providing options requested for the offer.

Return value

APromise that fulfills with an object containing the same properties as anRTCSessionDescription objects:

type: A string whose value is"offer".
sdp: A string containing the SDP describing the generated offer, to be delivered to the remote peer.

Exceptions

These exceptions are returned by rejecting the returned promise.Your rejection handler should examine the received exception to determine which occurred.

InvalidStateErrorDOMException: Returned if theRTCPeerConnection is closed.
NotReadableErrorDOMException: Returned if no certificate or set of certificates was provided for securing the connection, andcreateOffer() was unable to create a new one.Since all WebRTC connections are required to be secured, that results in an error.
OperationErrorDOMException: Returned if examining the state of the system to determine resource availability in order to generate the offer failed for some reason.

Examples

Here we see a handler for thenegotiationneeded event which creates the offer and sends it to the remote system over a signaling channel.

Note:Keep in mind that this is part of the signaling process, the transport layer for which is an implementation detail that's entirely up to you.In this case, aWebSocket connection is used to send aJSON message with atype field with the value "video-offer" to the other peer.The contents of the object being passed to thesendToServer() function, along with everything else in the promise fulfillment handler, depend entirely on your design.

myPeerConnection  .createOffer()  .then((offer) => myPeerConnection.setLocalDescription(offer))  .then(() => {    sendToServer({      name: myUsername,      target: targetUsername,      type: "video-offer",      sdp: myPeerConnection.localDescription,    });  })  .catch((reason) => {    // An error occurred, so handle the failure to connect  });

In this code, the offer is created, and once successful, the local end of theRTCPeerConnection is configured to match by passing the offer (which is represented using an object in the same shape asRTCSessionDescription) intosetLocalDescription().Once that's done, the offer is sent to the remote system over the signaling channel; in this case, by using a custom function calledsendToServer().The implementation of the signaling server is independent from the WebRTC specification, so it doesn't matter how the offer is sent as long as both the caller and potential receiver are using the same one.

UsePromise.catch() to trap and handle errors.

SeeSignaling and video calling for the complete example from which this snippet is derived; this will help you to understand how the signaling code here works.