Create Session

Overview

To create a session in Metered Global SFU, you should call this API. A session uniquely represents a peerConnection, so for each peerConnection you will create in your application you will have to call the Create Session API for that peerConnection and establish connection with the SFU.

The "Create Session API" accepts SDP from the peerConnection and return the remote sdp.

Authentication

You must provide bearer token in the Authorization header. The bearer token in the secret of the SFU App that you have created in the dashboard. When you create an SFU app, you will get the SFU App Id and the Secret.

• Header Authorization: Bearer {secret}

HTTP Request

POST

https://global.sfu.metered.ca/api/sfu/:sfu_app_id/session/new

URL Parameters

Parameter Name	Type	Description
sfu_app_id	string	The unique identifier of your SFU app. This parameter is required to specify which SFU app the session should be created for. You can find the SFU app ID in the dashboard after creating the SFU app.

Headers

Header	Value	Description
Authorization	Bearer {secret}	The bearer token which is the secret of the SFU App created in the dashboard.
Content-Type	application/json	Indicates that the request body format is JSON.

Request Body

{
    "sessionDescription": <sdp>,
    "metadata": "custom descriptive text"
}

Field	Type	Required	description
sessionDescription	string	Yes	The SDP (Session Description Protocol) information from the peerConnection.
metadata	string	No	Custom descriptive text that can be used to store additional information about the session.

Response

Success Response

The session response contains the unique sessionId representing the peerConnection, and the remote sdp from the SFU that you would have to add as remote session descriptor in the peerConnection.

{
    "sessionDescription": {
        "type": "answer",
        "sdp": "v=0\r\no=- 8184802762297966397 1723148053..."
    },
    "sessionId": "session-101-fc756623-3be4-4c40-b651-20e22095ee07"
}

Code Example

Here is a complete JavaScript Code example on how to establish a session with the SFU.

(async () => {
    const peerConnection = new RTCPeerConnection({
        iceServers: [{
            urls: "stun:stun.metered.ca:80"
        }]
    });

    let transceiverA = peerConnection.addTransceiver('video');

    const offerA = await peerConnection.createOffer();
    await peerConnection.setLocalDescription(offerA);

    // Saving the API Host in a variable
    const host = "https://global.sfu.metered.ca";
    // Our SFU App ID that we have obtained from the previous step
    const sfuAppId = "66ad57c7f9a530a04920b5cf";
    // Our SFU App Secret that we have obtained from the previous step
    const secret = "43wJtcPext1cmlfx";

    // Creating the session by sending the SDP to the SFU
    // In the response we will get the session_id which will be automatically generated
    // to represent this unique session, as well as the remote sdp from the SFU
    const responseSessionA = await fetch(host + `/api/sfu/${sfuAppId}/session/new`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${secret}`
        },
        body: JSON.stringify({
            sessionDescription: offerA,
            metadata: "userA session"
        })
    });



    const jsonSessionA = await responseSessionA.json();


    const sessionIdA = jsonSessionA.sessionId; 

    console.log("Session ID A:", sessionIdA);
    const remoteSDP = jsonSessionA.sessionDescription;
    await peerConnection.setRemoteDescription(new RTCSessionDescription(remoteSDP));
})()