Skip to main content

Meeting Room

Meeting rooms are the core component for organizing video calls in Eyeson.

Room Creation and Access​

  • Rooms are created using an API-Key request
  • Each room has a unique identifier to control access
  • Users receive a unique access key specific to both the room and user
  • The access key grants entry to the Eyeson room

Room Status​

The API response provides room status information through ready states:

  • User ready state
  • Room ready state
  • Global ready state (combines user and room states)

Start Meeting​

If someone already created and joined the room session, the user provided will join this existing room session.

POST /rooms # create a new room or join an existing by id
HEADERS Authorization
RESPONSES 201 CREATED, 400 BAD REQUEST, 403 FORBIDDEN
REQUIRED user[name]
RECOMMENDED options[sfu_mode] = screencast
Response to the cURL request
Response Status: 201

{
  "access_key": "YOUR_ACCESS_KEY",
  "ready": false,
  "locked": false,
  "room": {
    "id": "standup",
    "name": "Scrum",
    "ready": true,
    "started_at": "2024-12-09T14:25:02.254Z",
    "shutdown": false,
    "guest_token": "YOUR_GUEST_TOKEN"
  },
  "team": {
    "name": "Scrum"
  },
  "user": {
    "id": "6756fdc1755694e70cb72c80",
    "room_id": "tryout",
    "name": "Bob",
    "avatar": null,
    "guest": false,
    "blocked": false,
    "ready": false
  },
  "links": {
    "self": "https://api.eyeson.team/rooms/YOUR_ACCESS_KEY",
    "gui": "https://app.eyeson.team/?YOUR_ACCESS_KEY",
    "guest_join": "https://app.eyeson.team/?guest=YOUR_GUEST_TOKEN",
    "websocket": "https://api.eyeson.team/rt?access_key=YOUR_ACCESS_KEY"
  },
  "options": {
    "show_names": true,
    "show_label": true,
    "exit_url": null,
    "recording_available": true,
    "broadcast_available": true,
    "layout_available": true,
    "layout": "auto",
    "reaction_available": true,
    "suggest_guest_names": true,
    "lock_available": false,
    "kick_available": true,
    "sfu_mode": "disabled",
    "layout_users": null,
    "layout_name": null,
    "layout_map": null,
    "voice_activation": false,
    "custom_fields": {},
    "widescreen": true,
    "background_color": "#121212"
  },
  "playbacks": [],
  "presentation": null,
  "broadcasts": [],
  "recording": null,
  "snapshots": [],
  "waiting_list": [],
  "signaling": {
    "type": "sepp",
    "options": {
      "client_id": "6756fdc1755694e70cb72c80",
      "conf_id": "6756fdbe755694e70cb72c7f",
      "auth_token": "eyJhbGciOiJFUzM4NCJ9.eyJpc3MiOiJleWVzb24tY29tYXBpIiwiY2xpZW50X2lkIjoiNjc1NmZkYzE3NTU2OTRlNzBjYjcyYzgwIiwiZXhwIjoxNzMzNzU3OTA3LCJjb25mX2lkIjoiNjc1NmZkYmU3NTU2OTRlNzBjYjcyYzdmIn0.iGaL9KfAQF2D0p9SxdRodfo5vYfE37S2AV8Kyoz5xgnx7y3T8ToZTE-cct0Cg6YSdQNAjA9PyTE3PGxwcOKqEywkIAp2aEyqgP7Ajbeu-nAUwYcPUrCJjeZ4WxLfno0e",
      "endpoint": "wss://sig.eyeson.com/call",
      "stun_servers": [
        "stun:nuts.eyeson.com:3478"
      ],
      "turn_servers": [
        {
          "urls": [
            "turn:nuts.eyeson.com:3478",
            "turn:nuts.eyeson.com:3478?transport=tcp",
            "turns:nuts.eyeson.com:443?transport=tcp"
          ],
          "username": "1733840707:6756fdc1755694e70cb72c80",
          "password": "r66KgWNa9PQY0ObQDBsHuYRUS4Q="
        }
      ]
    }
  }
}

id​

Type: STRING (optional)
Default: RANDOM

Arbitrary id to get users into a specific meeting room. If empty, a random id will be returned.

name​

Type: STRING (optional)
Default: NULL

The readable name of a meeting room.

user[id]​

Type: STRING (optional)
Default: RANDOM

Custom user ID to identify the user in further REST requests without the need to remember or save the Eyeson user ID, e.g., an internal user ID, an e-mail address, phone number, etc. If empty, a random id will be assigned.

user[name]​

Type: STRING (required)
Default:NULL

Display name of the user.

user[avatar]​

Type: URL (optional)
Default: NULL

Link to the avatar image. Avatars will be displayed in the sidebar of our pre-defined user interface.

options[show_names]​

Type: BOOLEAN (optional)
Default: TRUE

Show display names in video.

options[show_label]​

Type: BOOLEAN (optional)
Default: TRUE

Show Eyeson logos in Prebuilt-UI.

options[exit_url]​

Type: URL (optional)
Default: NULL

Exit destination, URL for exit button in Prebuilt-UI.

options[recording_available]​

Type: BOOLEAN (optional)
Default: TRUE

Allow recordings.

If set to FALSE, related API requests will respond with status 405 METHOD NOT ALLOWED.

options[broadcast_available]​

Type: BOOLEAN (optional)
Default: TRUE

Allow broadcasting.

If set to FALSE, related API requests will respond with status 405 METHOD NOT ALLOWED.

options[reaction_available]​

Type: BOOLEAN (optional)
Default: TRUE

Show gif media inserts in Prebuilt-UI.

If set to FALSE, related API requests will respond with status 405 METHOD NOT ALLOWED.

options[layout_available]​

Type: BOOLEAN (optional)
Default: TRUE

Allow layout updates.

If set to FALSE, related API requests will respond with status 405 METHOD NOT ALLOWED.

options[guest_token_available]​

Type: BOOLEAN (optional)
Default: TRUE

Provide guest token.

If set to FALSE, related API requests will respond with status 405 METHOD NOT ALLOWED.

options[lock_available]​

Type: BOOLEAN (optional)
Default: FALSE

Enable meeting lock.

If set to FALSE, related API requests will respond with status 405 METHOD NOT ALLOWED.

options[kick_available]​

Type: BOOLEAN (optional)
Default: TRUE

Allow participant kick.

If set to FALSE, related API requests will respond with status 405 METHOD NOT ALLOWED.

options[sfu_mode]​

Type: STRING (optional)
Default: ptp

Set a desired SFU mode. Possible values are: disabled, screencast or ptp. To either disable the feature, limit it to screencast or enable it for meetings with only 2 participants.

warning

In order to make use of all advanced features of Eyeson API you must disable the SFU (Selective Forwarding Unit) mode. Eyeson API is based on MCU+ (Multipoint Control Unit), which extends basic MCU functions with advanced source and data handling. For more information visit the product website.

options[widescreen]​

Type: BOOLEAN (optional)
Default: FALSE

Run meeting in widescreen mode (16:9 aspect ratio).

options[background_color]​

Type: STRING (optional)
Default: #121212

Set meeting background color as hex RGB. Read more

options[audio_insert]​

Type: STRING (optional)
Default: audio_only

Show audio insert.
Valid values:enabled, disabled, audio_only

options[audio_insert_position][x]​

Type: NUMBER (optional)
Default: NULL

X position value of the audio insert.

options[audio_insert_position][y]​

Type: NUMBER (optional)
Default: NULL

Y position value of the audio insert.

options[custom_fields][locale]​

Type: LOCALE (optional)
Default: en

User preferred language code in Prebuilt-UI.
Valid values: en, de, fr

Type: URL (optional)
Default: NULL

URL to custom logo in Prebuilt-UI.

options[custom_fields][hide_chat]​

Type: BOOLEAN (optional)
Default: FALSE

Hide chat in Prebuilt-UI.

options[custom_fields][virtual_background]​

Type: BOOLEAN (optional)
Default: FALSE

Enable Virtual Background selection in Prebuilt-UI.

options[custom_fields][virtual_background_allow_guest]​

Type: BOOLEAN (optional)
Default: FALSE

Enable Virtual Background selection for Guest users in Prebuilt-UI.

options[custom_fields][virtual_background_image]​

Type: URL (optional)
Default: NULL

Provide a custom Virtual Background image URL for selection in Prebuilt-UI.
Heads-Up: Take care about CORS.

Get details of current meeting​

GET /rooms/<access_key>
RESPONSES 200 OK, 404 NOT FOUND, 410 GONE
REQUIRED user in running meeting

End Meeting​

DELETE /rooms/<access_key> # end meeting for all
RESPONSES 204 NO CONTENT, 404 NOT FOUND, 410 GONE

Force Stop Meeting​

DELETE /rooms/<room_id> # force to stop a running meeting
HEADERS Authorization
RESPONSES 204 NO CONTENT, 400 BAD REQUEST, 403 FORBIDDEN, 404 NOT FOUND

Get list of current running rooms​

GET /rooms
HEADERS Authorization
RESPONSES 200 OK, 403 UNAUTHORIZED

page​

Type: Integer (optional)
Default: NULL

Fetch next set of rooms (limit is 25)

Lock Meeting Room​

A meeting room can be locked, so that only participants who are actively in the meeting at the moment of locking are allowed to stay. No more users can join afterwards.

danger

There is no unlock. Once locked, there's no way to let new users join the running meeting.

POST /rooms/<access_key>/lock
RESPONSES 201 CREATED, 403 FORBIDDEN, 404 NOT FOUND, 410 GONE

If option[lock_available] is set to FALSE, related API requests will respond with status 403 FORBIDDEN.