Video Server API – Manage Rooms – EnableX Developer Centre

Rooms are virtual meeting spaces within the EnableX 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
Get Concurrent Session Information
Create Token

Create Room

A Video Session is held in a Video Room. Therefore, you need a Video Room created first before anyone can join in it for a Video Session.

EnableX supports 3 different type of Rooms, to be used in different use-cases. They are:

Permanent Room: These are always available to do a Video Session. So, you can do multiple session in the room until you delete the Room.
Scheduled Room: These rooms are available only 15 minutes prior to its scheduled time and remains available for its defined duration. You can do multiple session in the room during its availability. If users are in session, ongoing session continues beyond defined duration.
Adhoc Room: By default these rooms are available to do a single session anytime. If its used once, its gets deleted. However, Adhoc Room can be extended to do multiple sessions by adding a duration. Doing so, the room is not deleted after its first use, but it remains available for multiple session until the defined duration gets past from its first session’s start time.

EnableX supports 2 different modes in which the rooms can be defined to have different experience for users:

Group Mode: This is most common mode of Session where all moderators and participants can see and talk with each other.
Lecture Mode: This is Lecture or Webinar Mode. This is mode to carry our Webinar or Presentation to larger audience. In this mode, only moderators can talk and they can be seen and heard by all others in the room. Moderator can however allow any participant to talk, be heard and seen.

Use given Rest API Route to create Video Rooms for your Application.

API Route: https://api.enablex.io/video/v2/rooms
HTTP Request: POST
Try Open API Tool

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

license_id– This is required only if you have subscribed for User License based Billing Model where you are given N number of License IDs to use. Each Room must be defined with one of the given License IDs. Note that 2 concurrent sessions for rooms created with license_id is not permitted.
– Required: No
– 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 an Adhoc room. An adhoc room by default can only be used only for one session. . To create an 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 single Video Session in the room. Its in minutes. Video Session can be extended using SDK Method call being within a session. If duration is defined with an Adhoc Room, the room is made available for multiple sessions until N minutes as defined in duration from its initial session. e.g. If an Adhoc room is defined for 60 minutes, and if its used at 1PM for first session, it will be made available until 2PM for any new session.
– Required: Yes for Scheduled Room
– Values: Positive Number. In no. of minutes. Upper limited restricted by your Subscription..

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.
Know how to create HLS View?

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, EnableX 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. EnableX 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, EnableX decides Media Zone at run time.
– Required: No
– Enumerated Values: IN (for India), SG (For Singapore), US (For United States). XX (Default – EnableX 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 EnableX.

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"
  }
}

Try Open API Tool…

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.enablex.io/video/v2/rooms
HTTP Request: GET
Try Open API Tool

Request Example

GET https://api.enablex.io/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"
     }]
 }

Try Open API Tool…

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.enablex.io/video/v2/rooms/{room_id}
HTTP Request: GET
Try Open API Tool

Request Example

GET https://api.enablex.io/video/v2/rooms/{room_id}
Authorization: Basic XXXXXXX

Response JSON

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

Try Open API Tool…

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.enablex.io/video/v2/rooms/{room_id}
HTTP Request: PATCH
Try Open API Tool

Request Example

PATCH https://api.enablex.io/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    
}

Try Open API Tool…

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.enablex.io/video/v2/rooms/{room_id}
HTTP Request: DELETE
Try Open API Tool

Request Example

DELETE https://api.enablex.io/video/v2/rooms/{room_id} 
Authorization: Basic XXXXXXX

Response JSON

{
     "result": 0    
}

Try Open API Tool…

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.enablex.io/video/v2/rooms/{room_id}/users
HTTP Request: GET
Try Open API Tool

Request Example

GET https://api.enablex.io/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
             }
         } 
     ]
 }

Try Open API Tool…

Get Concurrent Session Information

If you want to know many many rooms are currently engaged in video sessions, this API helps you get run-time information across rooms. In other words, it can show run-time information for your Video Application.

API Route: https://api.enablex.io/video/v2/data
HTTP Request: GET

Request Example

GET https://api.enablex.io/video/v2/rooms/data 
Authorization: Basic XXXXXXX

Response JSON

{
  "total_sessions": Number,	/* Number of ongoing sessions */
  "license_sessions": {		/* User License used in ongoing sessions */
    "$license_id": false,	/* This user license is not in use */
    "$license_id": true		/* This userlicense is used in active session */
  }
}

Note:

Concurrency related data is made available only if you have subscribed for Concurrency or User License based billing mode.
total_sessions denotes how many sessions are currently ongoing.
license_sessions object is included if you have subscribed for User License based Billing Mode. It contains information related to the User License IDs if they are currently in use in active sessions.

Create Token

A Token is required for any Client End Point to join a RTC session on EnableX 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.enablex.io/v2/rooms/{room-id}/tokens
HTTP Request: POST
Try Open API Tool

Request Example

POST https://api.enablex.io/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"
 }

Try Open API Tool…

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

Get Concurrent Session Information

Request Example

Response JSON

Create Token

Characteristics of Token

Request Example

JSON Raw Body Payload on Request

Response JSON