Version: /v2

Create a Room - API

This API lets you create unique meetingId.

HTTP method and endpoint

POST

https://api.videosdk.live/v2/rooms

Headers Parameters

Authorization

REQUIRED

values : YOUR_TOKEN_WITHOUT_ANY_PREFIX

This will be a JWT token generate using VideoSDK ApiKey and Secret.

Note that the token will not include any prefix such as "Basic " or "Bearer ". Just pass a token as value.

You can generate a new token by refering this Guide: Generate Auth token

Content-Type

REQUIRED

values : application/json

This is usefull for json body parameters, so that VideoSDK servers can understand that the incoming body parameter will be a JSON string.

Body Parameters

customRoomId

OPTIONAL

Customize Room id for better understanding.

webhook

OPTIONAL

values :

{
  "webhook": {
    "endPoint": "webhook url",
    "events": ["recording-*", "participant-joined"]
  }
}

Subscribe to webhook events using exact event names or regex patterns.

Webhook Configuration:

endPoint: Your webhook URL endpoint (must be a POST method)
events: Array of event names or regex patterns

Regex Pattern Matching

You can now use regex patterns to subscribe to multiple related events efficiently:

Usage Examples:

Subscribe to all events json { "webhook": { "endPoint": "webhook url", "events": ["*"] } }

Subscribe to all recording events json title="Subscribe to all recording events" { "webhook": { "endPoint": "webhook url", "events": ["recording-*"] } }

Mix patterns and specific events json { "webhook": { "endPoint": "webhook url", "events": ["recording-*", "hls-*", "participant-joined", "session-ended"] } }

Available Webhook Events

Session Events:

session-started
session-ended

Participant Events:

participant-joined
participant-left

Recording Events:

recording-starting
recording-started
recording-stopping
recording-stopped
recording-failed
participant-recording-starting
participant-recording-started
participant-recording-stopping
participant-recording-stopped
participant-recording-failed
participant-track-recording-starting
participant-track-recording-started
participant-track-recording-stopping
participant-track-recording-stopped
participant-track-recording-failed
merge-recording-completed
merge-recording-failed

Transcription Events:

transcription-started
transcription-stopped

Livestream Events:

livestream-starting
livestream-started
livestream-stopping
livestream-stopped
livestream-failed

HLS Events:

hls-starting
hls-started
hls-playable
hls-stopping
hls-stopped
hls-failed

Learn More: User Webhooks Documentation

:::tip Use regex patterns like recording-* to subscribe to all related events instead of listing them individually! :::

autoCloseConfig

OPTIONAL

values :

{
  'autoCloseConfig': {
    'type': 'session-end-and-deactivate',
    'duration': 60
   }
}

This configuration will be used to automatically close the running session and also deactivate it, if configured.

type
- session-ends: This will close the running session after provided duration.
- session-end-and-deactivate: This will not only close the running session after provided duration but also deactivate the roomId. i.e. Only one session could be taken using this roomId, after that session ends no other session could be taken for the same roomId.
duration
- This duration will be in minutes, and after that duration, your room will be closed. Default value is 480 minutes.

autoStartConfig

OPTIONAL

values :

{
  'autoStartConfig': {
    'recording': {
      'transcription': {
         'enabled' : true
         'summary': {
           'enabled' : true,
           'prompt' : 'Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary'
          } 
       }
       'config': {
        'layout': { 
          'type': 'GRID',
          'priority': 'SPEAKER',
          'gridSize': 4
        }
      }
    },
    'hls': {
      'transcription': {
         'enabled' : true
         'summary': {
          'enabled' : true,
          'prompt' : 'Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary'
         }
     },
     'config': {
        'layout': { 
          'type': 'GRID',
          'priority': 'SPEAKER',
          'gridSize': 4
        }
        'recording': { 
          'enabled': 'true'
        }
      }
    },
}

This configuration enables automatic initiation of recording, HLS streaming, or both, providing a convenient way to capture and serve content in real-time. It streamlines the process of content management and delivery for enhanced user experience.

recording :
- templateUrl : Customize Layout of Meeting Recording
- transcription :
  - enabled: true | false
  - summary :
    - enabled: true | false
    - prompt: “Your customized summary prompt”
- config :
  - layout:
    - type: "GRID" | "SPOTLIGHT" | "SIDEBAR"
    - priority: "SPEAKER" | "PIN"
    - gridSize: Number max 4
  - theme: "DARK" | "LIGHT" | "DEFAULT"
  - mode: "video-and-audio" | "audio"
  - quality: "low" | "med" | "high"
  - orientation: "portrait" | "landscape"
- awsDirPath: "Your AWS S3 Bucket Path."

hls :
- templateUrl : Customize Layout of Meeting HLS
- transcription :
  - enabled: true | false
  - summary :
    - enabled: true | false
    - prompt: “Your customized summary prompt”
- config :
  - layout:
    - type: "GRID" | "SPOTLIGHT" | "SIDEBAR"
    - priority: "SPEAKER" | "PIN"
    - gridSize: Number max 4
  - theme: "DARK" | "LIGHT" | "DEFAULT"
  - mode: "video-and-audio" | "audio"
  - quality: "low" | "med" | "high"
  - orientation: "portrait" | "landscape"
  - recording :
    - enabled: true | false
composite :
- participants : [{ participantId: "Id of participant", kind: "video"}]

POST

https://api.videosdk.live/v2/rooms

import fetch from 'node-fetch';
const options = {
	method: "POST",
	headers: {
		"Authorization": "$YOUR_TOKEN",
		"Content-Type": "application/json",
	},
	body: JSON.stringify({
		"customRoomId" : "aaa-bbb-ccc",
		"webhook" : "see example",
		"autoCloseConfig" : "see example",
		"autoStartConfig" : "see example"
	}),
};
const url= `https://api.videosdk.live/v2/rooms`;
const response = await fetch(url, options);
const data = await response.json();
console.log(data);

RESPONSE

{
  "roomId": "abc-xyzw-lmno",
  "customRoomId": "final-testing",
  "userId": "5f7edbb14c938bcd42944527",
  "disabled": false,
  "createdAt": "2022-03-25T04:49:11.024Z",
  "updatedAt": "2022-03-25T04:49:11.024Z",
  "id": "623d49c760a18e699abcc8a4",
  "links": {
    "get_room": "https://api.videosdk.live/v2/rooms/abc-xyzw-lmno",
    "get_session": "https://api.videosdk.live/v2/sessions/"
  }
}

Got a Question? Ask us on discord