Video API – Manage Rooms – VIdeo API Dev Doc

Rooms are virtual meeting spaces within the Video platform to host RTC sessions. Rooms can behave as video-conferencing chats spaces, instant messaging rooms or video streaming sessions for real-time collaboration. Rooms can be Created, Removed, Updated or Deleted (CRUD) using the Room Route operation.

Create Room
Get list of Rooms
Get Room Information
Update Room Information
Delete a Room
Get list of users in a Room
Create Token

Create Room

When a Room is created, it merely creates a database entry with a room-id for the Video platform. The room-id is required to carry out CRUD operations for the Room.

API Route: https://api.yourcpass.com/video/v2/rooms
HTTP Request: POST

Request Example

{
  "name": "Topic or Room Title",
  "owner_ref": "xyz",
  "settings": {
    "description": "Descriptive text",
    "mode": "group",
    "scheduled": false,
    "adhoc": false,
    "duration": 30,
    "moderators": "1",
    "participants": "5",
    "billing_code": "",
    "auto_recording": false,
    "quality": "SD",
    "canvas": false,
    "screen_share": false,
    "abwd": true,
    "max_active_talkers": 4,
    "knock": false,
    "wait_for_moderator": false,
    "media_zone": "US",
    "single_file_recording": false,
    "role_based_recording": {
      "moderator": "audiovideo",
      "participant": "audio"
    },
    "live_recording": {
      "auto_recording": true,
      "url": "https://your-custom-view-url"
    }
  },
  "sip": {
    "enabled": false
  },
  "data": {
    "custom_key": ""
  }
}

JSON Raw Body Payload on Request

Key : Description

name – Name of Room or Topic of Meeting.
– Required: Yes
– Values: Alpha Numeric

owner_ref – Room Owner ID of Reference. You may use it from your Information System. Post Call Reports include this data for your reference/reporting.
– Required: Yes
– Values: Alpha Numeric

settings – JSON Object with room Configuration Keys. Value of each Key within settings will be validated to have legit value.

settings.mode – Type of Room. Not editable. Lecture mode auto-implements restriction on stream publishing by Participants and Moderator gets exclusive control of the floor.
– Required: Yes
– Enumerated Values: group (default), lecture

settings.scheduled – Whether the room is a permanent room or scheduled for a specific duration. Setting it false creates a permanent room. Not editable.
– Required: Yes
– Boolean Value: true, false (default)

settings.adhoc – Whether the room is a Adhoc room i.e. for one time use. To create a Adhoc room, you need to set it to true along with settings.scheduled as false. Not editable.
– Required: Yes
– Boolean value: true, false (default)

settings.scheduled_time – Only for scheduled room. This is scheduled start time of the Room. Token will be issues before 15 minutes of start time. Token will not be issued beyond scheduled duration if no participant is available in the room.
– Date Format: YYYY-MM-DD HH:II:SS
– Time Zone: UTC

settings.duration – Total Duration of Room. Its required only for Scheduled Room, for Adhoc and Permanent room its irrelevant.
– Required: Yes for Scheduled Room
– Values: Positive Number. No upper limit.

settings.moderators – Total Number of Moderator(s) allowed in the Room. If omitted, 1 moderator is set by default.
– Required: Yes
– Values: Numeric. 1-5, Default: 1

settings.participants – Total Number of Participants allowed in the Room. This value doesn’t count the Moderator.
– Required: Yes
– Values: Numeric.
* For Permanent & Adhoc Room: Max stream limit for permanent room is approximately 1600 streams. e.g conference with 100 participants and 6 max_active_talker = 600 streams. So, with 8 Active Talkers you can use 1-200 participants.
* For Scheduled Room: 1-300 participants.
* For Scheduled Rooms (in Lecture Mode): 1-1000 participants.

settings.audiences– Total Number of Audiences(s) allowed in the Room to view HLS Streaming This can be entered when HLS Service is subscribed.
– Required: No. However, mandatory if any of the hsl settings are being defined in the room.
– Values: Numeric. Default: 0. Range: Minimum 1. Maximum as allowed by subscription

settings.send_audiences_stats – Boolean, true or false. Default false. Set it to true, if end-point needs to receive user-connected and user-disconnected event on entry and exit of an audience.
– Required: No.
– Values: Boolean. Default: false.

settings.hls_view_url – If a custom view is required for HLS Streaming, develop one and host at application end. The URL of the Custom View may be passed here. If not passed, a pre-defined default HLS Streaming View will be used. However, you may explicitly pass “DEFAULT” as value to this key.
– Required: No.
– Values: String. URL.

settings.auto_recording – If auto-recording is enabled, recordings gets started as soon as any participant publishes into the room. In Auto-Recording enabled sessions, Recording can be stopped and restarted manually using function calls.
– Required: No
– Boolean Value: true, false (Default)

settings.screen_share – If you need Screen Share in a room, you may enable it.
– Required: No
– Boolean Value: true (Default), false

settings.canvas – If you need Canvas streaming (Streaming with contents of HTML5 Canvas Object) in a room, you may enable it.
– Required: No
– Boolean Value: true, false (Default)

settings.knock – If you need participant to wait before he is allowed by moderator to join a session, then enable knock feature.
– Required: No
– Boolean value: true, false (Default)

settings.wait_for_moderator – If you need participants to wait until a moderator joins the session. Once Moderator joins once, all waiting participants and new participants will be allowed to get into the session.
– Required: No
– Boolean value: true, false (Default)

settings.quality – If your application setting and subscription allows HD streaming, you may opt to use either HD, SD or LD for a room. If not used, The platform allows subscription based stream quality by default.
– Required: No
– Enumerated Values: HD, SD, LD

Note: Quality LD has been introduced with Release 1.5.3.

Video Resolutions:
* HD: Min 320X180@30fps. Max 1280X720@30fps
* SD: Min 320X180@30fps. Max 640X480@30fps
* LD: Min 80X45@30fps. Max 640X360@30fps

settings.billing_code – This is for Applications own reference.
– Required: No
– Values: Alpha Numeric

settings.abwd – If you need disable ABWD (Auto-Bandwidth Detection) in a Room.
– Required: No
– Boolean Value: true (default), false

settings.facex – If you need carry out Face Recognition Analysis in this Room.
– Required: No
– Boolean Value: true (default), false

settings.max_active_talkers – You may define how many maximum streams you need in Active Talkers. Optional. Maximum 16 Active Talkers may be define.
– Required: No
– Number Range: 1-16, Default 6

settings.single_file_recording – You may enable this feature to get live-transcoding done in a room defined with 2 users only where a user comes with audio/video and other user comes with audio only. Platform provides .webm file just after session ends. This is typically used by KYC Applications.
– Required: No
– Boolean value: true, false (Default)

settings.role_based_recording– JSON Object to define if recording file needs to exclude Video Track from user’s stream in the Rool. By default, audio and video track for all users are recorded as received at Media Server. If required, audio only recording may be enabled for users joined with “participant” and/or “moderator” role.
– Required: No

This Object may have one or both of the following keys { "moderator": "audiovideo", "participant": "audio" }. Here:
– moderator: Optional. String. Enumerated values: audio, audiovideo. Default. audiovideo.
– participant: Optional. String. Enumerated values: audio, audiovideo. Default. audiovideo.

Value: audiovideo – It will record both Video with Audio Track.
Value: audio – It will record only Audio Track. Video Track will be skipped.

settings.live_recording – JSON Object to create a transcoded file in a live session without recording individual streams. You can enable live recording and define the url.
– Required: No
– Boolean value: true, false (Default)

settings.media_zone – You may decide a Media Zone for the Room among available Zones. Note that its subscription controlled feature. By default, Platform decides Media Zone at run time.
– Required: No
– Enumerated Values: IN (for India), SG (For Singapore), US (For United States). XX (Default – Platform assigns Media Zone)

settings.watermark – This enables Watermarking of recorded files for the Room.
– Required: No
– Boolean Value: true, false (Default)

sip – JSON Object with SIP Configuration Keys. Value of each Key within sip will be validated to have legit value.

enabled – This is to enable SIP Connection to the Room.
– Required: No
– Boolean Value: true, false (Default)

data – JSON Object to carry custom data. You can define your own Keys in this object. None of the Keys and their values are validated by the Platform.

Response JSON

{
  "result": 0,
  "room": {
    "name": "Topic or Room Title",
    "owner_ref": "xyz",
    "settings": {
      "description": "Descriptive text",
      "mode": "group",
      "scheduled": false,
      "adhoc": false,
      "duration": 50,
      "moderators": "2",
      "participants": "10",
      "billing_code": "",
      "auto_recording": false,
      "quality": "HD",
      "canvas": true,
      "screen_share": true,
      "max_active_talkers": true,
      "role_based_recording": {
        "moderator": "audiovideo",
        "participant": "audio"
      },
      "live_recording": {
        "auto_recording": true,
        "url": "rtmp-client.enablex.io/?token="
      }
    },
    "sip": {
      "enabled": true,
      "pin": 99999,
      "meeting_id": 99999
    },
    "data": {
      "custom_key": ""
    },
    "created": "2018-07-12T11:30:24.851Z",
    "room_id": "xxxxxxxxxxxxxxx"
  }
}

Get a list of Rooms

To get a complete list of Rooms created within an Application you may use this Route

API Route: https://api.yourcpass.com/video/v2/rooms
HTTP Request: GET

Request Example

GET https://api.yurcpass.com/video/v2/rooms
Authorization: Basic XXXXXXX

Response JSON

{
     "result": 0,
     "rooms": [{
         "name": "Topic or Room Title",
         "owner_ref": "xyz",
         "settings": {
             "description": "Descriptive text",
             "mode": "group",
             "scheduled": false,
             "adhoc": false,
             "duration": 50,
	     "moderators": "2",
             "participants": "10",
             "billing_code": "",
             "auto_recording": false,
             "quality": "HD",
             "canvas": true,
	     "screen_share": true,
	     "max_active_talkers": 6
         },
         "sip" : {
             "enabled": false
         },
         "data": {
             "custom_key": ""
         },
         "created": "2018-07-12T11:30:24.851Z",
         "room_id": "xxxxxxxxxxxxxxx"
     }]
 }

Get Room Information

To get a complete room definition of a given Room, you may use this Route. Note the API Route has the room-id appended

API Route: https://api.yourcpass.com/video/v2/rooms/{room_id}
HTTP Request: GET

Request Example

GET https://api.yourcpass.com/video/v2/rooms/{room_id}
Authorization: Basic XXXXXXX

Response JSON

Response is similar to the response of Create Room API Call.

Update Room Information

If you need to update Room information you may do so with this API Route. The JSON Payload contains only those keys that are permissible to update. Note that any update on the Room definition will take effect only on subsequent sessions of the Room. To update schedule room, you should do so 15 minutes prior to the scheduled start time.

API Route: https://api.yourcpass.com/video/v2/rooms/{room_id}
HTTP Request: PATCH

Request Example

PATCH https://api.yourcapss.com/video/v2/rooms/{room_id}
Authorization: Basic XXXXXXX
Content-Type: application/json

{
      "name": "Topic or Room Title",
      "settings": {
          "participants": "15",
          "auto_recording": true 
      }            
 }

Response JSON

{
     "result": 0    
}

Delete a Room

You can delete a Room using this API call only if the Room is not an active Room i.e. without any ongoing session in it.

API Route: https://api.yourcpass.com/video/v2/rooms/{room_id}
HTTP Request: DELETE

Request Example

DELETE https://api.yourcpass.com/video/v2/rooms/{room_id} 
Authorization: Basic XXXXXXX

Response JSON

{
     "result": 0    
}

Get list of Users in a Room

If a Room is active i.e. room with ongoing session; you may get a list of all users (participants + moderator) connected to the Room using this API call. Note that if room is not active, the API call returns a null list.

API Route: https://api.yourcpass.com/video/v2/rooms/{room_id}/users
HTTP Request: GET

Request Example

GET https://api.yourcpass.com/video/v2/rooms/{room_id}/users 
Authorization: Basic XXXXXXX

Response JSON

{
     "result": 0,
     "total": 1,
     "users": [
         {
         "name": "User Name",
         "user_ref": "xxx",
         "role": "participant",
         "permissions": {
             "publish": true,
             "subscribe": true,
             "record": false,
             "stats": true,
             "controlhandlers": true
             }
         } 
     ]
 }

Create Token

A Token is required for any Client End Point to join a RTC session on the Video Platform.. A Token created for a Room has an assigned role for the user. Note the following:

Characteristics of Token

A Token is created only for a given Room-ID.
A Token decides your role within a session, i.e. Moderator or a Participant or a Viewer. A Moderator is the Organiser who will have additional control over the session like start/stop recording, hard mute/unmute room, drop/eject participant from the room or end the session. The viewers can access all media streams and chat, but they cannot interact.
Tokens are transactional. Every time you want to connect to the same room you would require a new Token.
A Token can be used only once.
Tokens have a 15 minutes lifetime within which it must be used to connect to a Room.
For a Permanent Meeting Room, Token may be created any time.
For a Scheduled Meeting Room, Token may be created 15 minutes prior to scheduled start time.

API Route: https://api.yourcpass.com/v2/rooms/{room-id}/tokens
HTTP Request: POST

Request Example

POST https://api.yourcpass.com/video/v2/rooms/{room_id}/tokens
Authorization: Basic XXXXXXX
Content-Type: application/json

{
     "name": "User Name",
     "role": "participant",
     "user_ref": "XXX",
     "data": {
     	"custom_key": "String",
	"any_key": "String"
     }
}

JSON Raw Body Payload on Request

Key : Description

name Name of the user who is creating token to join session
– Required: Yes
– Format: Alpha Numeric

role Role of User
– Required: Yes
– Enumerated Values: moderator, participant, viewer, audience (All in lowercase)
Note: moderator role user has access to session management controls, viewer role user doesn’t have stream publishing rights. audience is only HLS Stream Viewer.

user_ref User ID or Reference. You may use it from your Information System. Post Call Reports include this data for your reference/reporting
– Required: Yes
– Values: Alpha Numeric

data its a custom data object that you can pass. You can define your own keys, max 5 keys to pass data about the user. The data will be available to others in-session.

Response JSON

{
     "result": 0, 
     "token": "JWT_WEB_TOKEN"
 }

Table of Contents

Create Room

Request Example

JSON Raw Body Payload on Request

Response JSON

Get a list of Rooms

Request Example

Response JSON

Get Room Information

Request Example

Response JSON

Update Room Information

Request Example

Response JSON

Delete a Room

Request Example

Response JSON

Get list of Users in a Room

Request Example

Response JSON

Create Token

Characteristics of Token

Request Example

JSON Raw Body Payload on Request

Response JSON