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.

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
     },
     "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.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 9 Active Talkers may be define.
– Required: No
– Number Range: 1-9, 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.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)
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"
     }
 }

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

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

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/v1/rooms/{room_id}
  • HTTP Request: GET
  • Try Open API Tool

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.

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/v1/rooms/{room_id}
  • HTTP Request: PATCH
  • Try Open API Tool

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    
}

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/v1/rooms/{room_id}
  • HTTP Request: DELETE
  • Try Open API Tool

Request Example

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

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

Try Open API Tool…

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
  • Try Open API Tool

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

Try Open API Tool…