Rooms are virtual meeting space 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.

Table of Contents

Create Room

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

  • API Route: https://api.enablex.io/video/v1/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": "2",
         "participants": "10",
         "billing_code": "",
         "auto_recording": false,
         "quality": "SD",
         "canvas": false,
	 "screen_share": false,
         "abwd": true,
	 "max_active_talkers": 1
     },
     "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.modeType 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.moderatorsTotal 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. 1-50 (For Permanent & Adhoc Room), 1-300 (For Scheduled Rooms). 1-1000 (For Scheduled Rooms in Lecture Mode)
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_shareIf 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.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.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 9 Active Talkers may be define.
– Required: No
– Number Range: 1-9, Default 6
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
         },
         "sip" : {
             "enabled": true,
	     "pin": 99999,	 /* When sip.enabled=true */
	     "meeting_id": 99999 /* When sip.enabled=true */
         },
         "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.enablex.io/video/v1/rooms
  • HTTP Request: GET

Request Example

GET https://api.enablex.io/video/v1/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.enablex.io/video/v1/rooms/{room_id}
  • HTTP Request: GET

Request Example

GET https://api.enablex.io/video/v1/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.enablex.io/video/v1/rooms/{room_id}
  • HTTP Request: PATCH

Request Example

PATCH https://api.enablex.io/video/v1/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.enablex.io/video/v1/rooms/{room_id}
  • HTTP Request: DELETE

Request Example

DELETE https://api.enablex.io/video/v1/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.enablex.io/video/v1/rooms/{room_id}/users
  • HTTP Request: GET

Request Example

GET https://api.enablex.io/video/v1/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 EnableX Platform.. A Token created for a Room has an assigned role for the user. Note the following:

  • A Token is only for one time use with a lifespan of 120 minutes.
  • Each Client End Point must connect to the Room using a Token within its lifespan.
  • A Client End Point can only connect to a Room if the Token is valid.
  • For a scheduled meeting Room, the Token may be created 15 minutes prior to scheduled start time.
  • API Route: https://api.enablex.io/v1/rooms/{room-id}/tokens
  • HTTP Request: POST

Request Example

POST https://api.enablex.io/video/v1/rooms/{room_id}/tokens
Authorization: Basic XXXXXXX
Content-Type: application/json

{
     "name": "User Name",
     "role": "participant",
     "user_ref": "XXX"
}

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 (All in lowercase)
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

Response JSON

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