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.

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,
    "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. 1-100 (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_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 [email protected] Max [email protected]
* SD: Min [email protected] Max [email protected]
* LD: Min [email protected] Max [email protected]
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

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…

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

Note: moderator role user has access to session management controls, viewer role user doesn’t have stream publishing rights.
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…