Route: Rooms

Rooms are virtual meeeting space within which hosts the RTC session. They can act like videoconferencing chats, instant messaging rooms, video streaming sessions, and any other kind of virtual space for real-time collaboration. Rooms route has the CRUD operations used for managing rooms.

List of Actions available are as below:
  1. Create Room
  2. Get list of Rooms
  3. Get Room Information
  4. Update a Room
  5. Delete a non-active Room
  6. Get list of users in an active Room
  7. Create Token



Create Room

This API Call is to create a new Room to carry out RTC Sessions.

URL: https://api.enablex.io/%version-slug%/rooms
Method: POST

JSON Body Definition
Parameters Description
name Name of the Room
Required: Yes
owner_ref The Room Owner’s ID or Reference to be used from your own Information System.
Required: Yes
Values: Only Alphanumeric values
settings JSON structure to send room configuration parameters. Each field will be evaluated / validated.
mode This setting is not editable.
Values: Lecture / Group
Default: Group
adhoc The room will be used only once.
Required: Yes
Values: true/false
scheduled The room can be used anytime if the value is set as false. If it is set to true, you can use the room only at pre-defined time.
Required: Yes
Values: true/false
scheduled_time For scheduled room, a date/time can be specified in UTC when the room is scheduled to be available. The room will be made available for users to get connected 15 minutes before the specified time. Data Format: YYYY-MM-DD HH:II:SS. Required for scheduled rooms. Only future date/time allowed here.
duration Total Duration in number of minutes. Set it to 0 (Zero) for unlimited duration. Positive whole numbers are acceptable values. No upper limit. You must specify a duration for scheduled rooms.
Required: Yes
participants Total number of participants allowed in the room. Default 0 for unlimited participants. Positive whole numbers are acceptable values.
Default: 0
billing_code This is for developer's own reference. You may enter any alphanumeric values.
Required: Yes
auto_recording When it is set to true, recording starts automatically as soon as any participant starts publishing stream in the room.
Required: Yes
Values: true/false
canvas When it is set to true, it adds canvas streaming capability to the room.
Required: No
Values: true/false
Default: false
knock When it is set to true, it forces a participant to wait to be accepted by moderator to join the room.
Required: No
Values: true/false
Default: false
quality If not passed, it defaults to quality setting of your Application. You are not allowed to set HD Quality Rooms in any Application not opted for HD quality.
Required: No
Values: HD/SD
sip JSON structure to send sip configuration parameters. Each field will be evaluated/validated.
enabled This is enable SIP connection to the Room.
Required: No
Values: true/false
Default: false
data JSON structure to send optional data. You can send any key with a value for your application requirement.

Request JSON: { "name": "Permanent Room", "settings": { "description": "Permanent Room", "scheduled": false, "duration": 50, "participants": "10", "billing_code": "1234", "auto_recording": false, "quality": "HD", "adhoc": false, "mode": "group", "canvas": true }, "sip" : { "enabled": true }, "data": { "name": "Permanent Room" }, "owner_ref": "xyz" }

Response JSON: { "result": 0, "room": { "name": "Permanent Room", "owner_ref": "xyz", "settings": { "description": "Permanent Room", "scheduled": false, "adhoc": false, "participants": "10", "billing_code": "1234", "auto_recording": false, "quality": "HD", "mode": "group", "canvas": true }, "sip": { "enabled": true, "pin": 999999 }, "data": { "name": "Permanent Room" }, "created": "2018-07-12T11:30:24.851Z", "room_id": "xyzxyz" } }



Get List of Rooms

This API Call allows to fetch list of all rooms created in the Application.

URL: https://api.enablex.io/%version-slug%/rooms
Method: GET

Response JSON: { "result": 0, "rooms": [ { "name": "Scheduled Room", "owner_ref": "xyz", "settings": { "description": "Scheduled Room", "scheduled": true, "scheduled_time": "2018-07-20T08:10:45.000Z", "duration": "15", "adhoc": false, "participants": "10", "billing_code": "Test123", "auto_recording": false, "quality": "HD", "mode": "group", "canvas": false }, "sip": { "enabled": false }, "data": { "name": "Scheduled Room" }, "created": "2018-07-12T10:16:07.119Z", "updated": "2018-07-12T10:53:03.674Z", "room_id": "xyzxyz" } ] }



Get Room Information

This API is called to get information of a given room-id

URL: https://api.enablex.io/%version-slug%/rooms/{room_id}
Method: GET
Parameter: room-id

Response JSON: { "result": 0, "room": { "name": "Scheduled Room", "owner_ref": "xyz", "settings": { "description": "Scheduled Room", "scheduled": true, "scheduled_time": "2018-07-20T08:10:45.000Z", "duration": "15", "adhoc": false, "participants": "05", "billing_code": "Test123", "auto_recording": false, "quality": "HD", "mode": "group", "canvas": false }, "sip": { "enabled": false }, "data": { "name": "Scheduled Room" }, "created": "2018-07-12T10:16:07.119Z", "room_id": "xyzxyz" } }



Update Room Information

This API Call is to update Room Information.

Note:
- All the information of a Room may not be editable.
- While updating, you can pass the key only which you look to update.

URL: https://api.enablex.io/%version-slug%/rooms/{room_id}
Method: PATCH
Parameters: room_id
Warning : Any update on Room Parameter will not affect ongoing conference. The updated parameters will only come in effect in subsequent conferences.

JSON Body Definiton
Parameters Description
name Name of the Room
Required: Yes
settings JSON structure to update optional data. It doesn’t provision to change on-demand room to one-time or vice versa.
scheduled_time In case its scheduled room, a date/time can be specified in UTC when the room is scheduled to be available. The room will be made available for users to get connected 15 minutes before the specified time. Data Format: YYYY-MM-DD HH:II:SS. Required for scheduled rooms. Only future date/time is legible.
duration Total Duration in number of minutes. Set it to 0 (Zero) for unlimited duration. Positive whole numbers are acceptable values. No upper limit. You must specify a duration for scheduled rooms.
This field is Optional
participants Total number of participants allowed in the room. Default 0 for unlimited participants. Positive whole numbers are acceptable values.
Default : 0
billing_code This is for self-reference. You may enter any alphanumeric values.
This field is Optional
auto_recording If it is set to true, recording starts automatically as soon as any participant starts publishing stream.
This field is Optional
Values : true/false
knock If set to true, it forces a participant to wait to be accepted by moderator to join the room.
This field is Optional
Values : true/false
Default: false
quality If not passed, it defaults to quality setting of your Application. You are not allowed to set HD Quality Rooms in any Application not opted for HD quality.
Optional
Values : HD/SD
sip JSON structure to send sip configuration parameters. Each field will be evaluated / validated.
enabled This is enable SIP connection to the Room.
Optional
Values : true/false
Default: false
data JSON structure to send optional data. You can send any key with a value for your application requirement.

Request JSON: { "name": "Scheduled Room", "settings": { "description": "Scheduled Room", "scheduled": true, "scheduled_time": "2018-07-20 08:10:45", "duration": "15", "participants": "10", "billing_code": "Test123", "auto_recording": false, "quality": "HD", "adhoc": false, "mode": "group", "canvas": false }, "sip" : { "enabled":false }, "data": { "name": "Scheduled Room" }, "owner_ref": "xyz" }

Response JSON: { "result": 0 }



Delete a non-active Room

This API call is used to delete a room. If the room is currently busy with an RTC Session, you can't delete the room.

URL: https://api.enablex.io/%version-slug%/rooms/{room_id}
Method: DELETE
Paratmeters: room_id

Response JSON: { "result": 0 }



Get list of users in a Room

You get a list of all users currently connected to an ongoing RTC Session in in the Room. It doesn't return anything if the Room is not in an active RTC Session.

URL: https://api.enablex.io/%version-slug%/rooms/{room_id}/users
Method: GET
Paratmeters: room_id

Response JSON: { "result": 0, "total": 2, "users": [ { "name": "abc", "user_ref": "abc", "role": "participant", "permissions": { "publish": true, "subscribe": true, "record": false, "stats": true, "controlhandlers": true } }, { "name": "abx", "user_ref": "xyz", "role": "participant", "permissions": { "publish": true, "subscribe": true, "record": false, "stats": true, "controlhandlers": true } } ] }



Create Token

This is used to get a Token for a new user to allow him to enter RTC Session currently in progress in the room. Token is a string that allows you to add a new participant to a determined room. When you want to add a new participant to a room, you need to create a new token than you will consume in the client-side API. To create a token you need to specify a name, role, use_ref for the new participant.

URL: https://api.enablex.io/%version-slug%/rooms/{room_id}/tokens
Method: POST
Paratmeters: room_id

JSON Body
Parameters Description
user_ref This is to identify a user. The ID or Reference No. of a user to be taken from your own information system.
Required: Yes
name Required: Yes
role Allowed Values: moderator, participant


Request JSON: { "name": "John Doe", "role": "participant", "user_ref":"abc }

Response JSON: { "result": 0, "token": "JSON_WEB_TOKEN " }