VCS Realtime SDK

# REST API

All endpoints require an API key to be used in a x-vcs-token header. This api-key and the vcs-domain can be obtained by the system administrator.

# Realtime API

# Create a room

Creates a room and returns that room.

There are two conference types available (MESH/SFU). MESH is a peer-to-peer, end-to-end encrypted conference. This is the default conference type. SFU is a server-based conference suited for larger conferences.

The returned room object contains the token to be used by the client SDKs to join a room. The maxParticipants, roomTokenTTLSeconds and endpointTTLSeconds values are configurable by the system administrator.

POST /api/realtime/room

Parameters

Name Type In Required Description
name string body false The name of the room. Room names do not have to be unique.
description string body false The description of the room.
conferenceType string body false The conference type of the room (MESH or SFU). Default is MESH.
autoUpgradeParticipantCount number body false The paticipant count at which a MESH conference is autoupgraded to a SFU conference. Default is undefined (no upgrade).

Examples

Shell

$ curl -X POST https://<vcs-domain>/api/realtime/room \
-H "x-vcs-token: <api-key>" \
-H "Content-Type: application/json"

$ curl -X POST https://<vcs-domain>/api/realtime/room \
-H "x-vcs-token: <api-key>" \
-H "Content-Type: application/json" \
-d "{\"name\":\"Room A\",\"description\":\"My room description\",\"conferenceType\":\"MESH\",\"autoUpgradeParticipantCount\":\"4\"}"

Successful response

Status: 200 Ok

{
  "room": {
    "id": "RO-7403cb88-8e88-452a-8bb7-0923923348f7",
    "name": "Room A",
    "description": "My room description",
    "creationTime": 1649425468429,
    "conferenceType": "MESH",
    "autoUpgradeParticipantCount": 4,
    "modificationTime": 1649425468429,
    "maxParticipants": 3,
    "roomTokenTTLSeconds": 86400,
    "roomTTLSeconds": 86400,
    "endpointTTLSeconds": 86400,
    "token": "49bd3a2..."
  }
}

# Fetch a room

Gets a single room by its id.

GET /api/realtime/room/{id}

Parameters

Name Type In Required Description
id string path false Room ID

Examples

Shell

$ curl https://<vcs-domain>/api/realtime/room/b4a8b6e0-c3b6-4d70-9414-7b02adc50f71 \
-H "x-vcs-token: <api-key>"

Successful response

Status: 200 Ok

{
  "id": "RO-7403cb88-8e88-452a-8bb7-0923923348f7",
  "name": "Room A",
  "description": "My room description",
  "creationTime": 1649425468429,
  "conferenceType": "MESH",
  "modificationTime": 1649425468429,
  "maxParticipants": 3,
  "roomTokenTTLSeconds": 86400,
  "roomTTLSeconds": 86400,
  "endpointTTLSeconds": 86400,
  "token": "49bd3a2..."
}

# Fetch rooms

Gets rooms with paging capabilities. Maximum of 100 rooms per request. Default is 25.

Returns a 400 Bad Request for invalid numberOfRecords range or invalid token.

GET /api/realtime/room

Parameters

Name Type In Required Description
numberOfRecords number query true Number of rooms to return. Valid range is 1-100. If not passed a maximum of 100 rooms are returned.
token string query false Token used for paging.

Examples

Shell

# Get all rooms (up to 25)
$ curl https://<vcs-domain>/api/realtime/room \
-H "x-vcs-token: <api-key>"

# Get subsequent 10 rooms by passing token returned in prior page.
$ curl https://<vcs-domain>/api/realtime/room?numberOfRecords=10&token=<token returned from previous request> \
-H "x-vcs-token: <api-key>"

Successful response

Status: 200 Ok

{
  "data": [
    {
      "id": "RO-7403cb88-8e88-452a-8bb7-0923923348f7",
      "name": "Room A",
      "description": "My room description",
      "creationTime": 1649425468429,
      "conferenceType": "MESH",
      "modificationTime": 1649425468429,
      "maxParticipants": 3,
      "roomTokenTTLSeconds": 86400,
      "roomTTLSeconds": 86400,
      "endpointTTLSeconds": 86400,
      "token": "49bd3a2..."
    },
    {
      "id": "RO-fdd5c32f-b3ce-4257-b03b-fceb13b95107",
      "name": "Room B",
      "creationTime": "2021-02-27T19:11:21.233Z",
      "conferenceType": "MESH",
      "modificationTime": "2021-02-27T19:11:21.233Z",
      "maxParticipants": 4,
      "roomTokenTTLSeconds": 3600,
      "roomTTLSeconds": 86400,
      "endpointTTLSeconds": 3600,
      "token": "b9532a2..."
    }
  ],
  "token": "B53AF55E"
}

# Delete a room

Delete a room.

DELETE /api/realtime/room?id=<id>

Parameters

Name Type In Required Description
id string query true Room ID.

Examples

Shell

$ curl -X DELETE https://<vcs-domain>/api/realtime/room?id=<id> \
-H "x-vcs-token: <api-key>"

Successful response

Status: 200 Ok

{
  "room": {
    "id": "RO-7403cb88-8e88-452a-8bb7-0923923348f7",
    "name": "Room A",
    "description": "My room description",
    "creationTime": 1649425468429,
    "conferenceType": "MESH",
    "modificationTime": 1649425468429,
    "maxParticipants": 3,
    "roomTokenTTLSeconds": 86400,
    "roomTTLSeconds": 86400,
    "endpointTTLSeconds": 86400,
    "token": "49bd3a2..."
  }
}

# Error codes

Error codes are returned with a standard HTTP error code and a JSON body containing more details on the error.

For example if the vcs-token is missing or invalid, then the HTTP error 401 Unauthorized with following body will be returned.

{
  "httpCode": 401,
  "code": "BASE-00001",
  "id": null,
  "description": ["Authorization missing."]
}

Or a 400 Bad Request for an invalid/missing parameter:

{
  "httpCode": 400,
  "code": "BASE-00015",
  "id": "NUMBER_SIZE",
  "description": ["The parameter with name ::= [numberOfRecords] is is not within the range from ::= [1] to [100]"]
}

# Generic errors (e.g. authentication)

# Authorization (x-vcs-token) missing

{
  "httpCode": 401,
  "code": "BASE-00001",
  "id": null,
  "description": ["Authorization missing."]
}

# Authorization (x-vcs-token) invalid

{
    "httpCode": 400,
    "code": "REALTIME-00009",
    "id": "INVALID_TOKEN",
    "description": [
        "The token ::=
         [ce0ef13256b4eff41bef65af69f53ae750a81c15fd124c235a59eecaa766105bc] is invalid."
    ]
}

# Errors for POST /api/realtime/room

# Passed content is no a JSON body

{
  "httpCode": 400,
  "code": "BASE-00014",
  "id": null,
  "description": ["The passed JSON body is invalid."]
}

# Incorrect content type

{
  "httpCode": 415,
  "code": "BASE-00017",
  "id": null,
  "description": ["Passed media type is not supported."]
}

# Room name is too long

{
  "httpCode": 400,
  "code": "BASE-00013",
  "id": "STRING_SIZE",
  "description": ["The parameter with name ::= [name] is larger than ::= [512] characters"]
}

# Errors for GET /api/realtime/room

# Invalid parameter numberOfRecords

{
    "httpCode": 400,
    "code": "BASE-00015",
    "id": "NUMBER_SIZE",
    "description": [
        "The parameter with name ::= [numberOfRecords] is is not
          within the range from ::= [1] to [100]"
    ]
}

# Errors for DELETE /api/realtime/room

# Room does not exist

{
    "httpCode": 400,
    "code": "REALTIME-00004",
    "id": "CONFERENCE_ROOM_DOES_NOT_EXIST",
    "description": [
        "A conference room with id ::= [RO-fafd9427-fedf-4e58-9150-97d86a25fe58]
         does not exist."
    ]
}

← Javascript SDK →