Meeting Room

Meeting rooms are the core component for organizing video calls in the Eyeson platform. They serve as virtual spaces where participants can join and collaborate through video communication.

info

Throughout this documentation, the terms "meeting room," "meeting," and "room" are used interchangeably with the same meaning. It's important to note that a single room can host multiple consecutive meetings over time.

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 meeting and user
The access key grants entry to the meeting

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 meeting, the user provided will join this existing meeting.

POST /rooms
HEADERS Authorization
RESPONSES 201 CREATED, 400 BAD REQUEST, 403 FORBIDDEN
REQUIRED user[name]
RECOMMENDED options[sfu_mode]=disabled, options[widescreen]=true, user[id]

Example Req/Res: Start Meeting

Request
curl -X POST \
     -H "Authorization: $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"user": {"name": "John Doe", "id": "johndoe"}, "options": {"sfu_mode": "disabled", "widescreen": true}}' \
     "https://api.eyeson.team/rooms"

Response
Response Status: 201

{
  "access_key": "VgoCcMUSQQ6h4zwpEfBuo0rZ",
  "ready": false,
  "locked": false,
  "room": {
    "id": "67d2febd7a286f59a7643884",
    "name": "API magic",
    "ready": false,
    "started_at": "2025-03-13T15:50:21.347Z",
    "shutdown": false,
    "guest_token": "77Ua2Abc8ftGDNVzsixwvbcZ"
  },
  "team": {
    "name": "API magic"
  },
  "user": {
    "id": "johndoe",
    "room_id": "67d2febd7a286f59a7643884",
    "name": "John Doe",
    "avatar": null,
    "guest": false,
    "blocked": false,
    "ready": false
  },
  "links": {
    "self": "https://api.eyeson.team/rooms/VgoCcMUSQQ6h4zwpEfBuo0rZ",
    "gui": "https://app.eyeson.team/?VgoCcMUSQQ6h4zwpEfBuo0rZ",
    "guest_join": "https://app.eyeson.team/?guest=77Ua2Abc8ftGDNVzsixwvbcZ",
    "websocket": "https://api.eyeson.team/rt?access_key=VgoCcMUSQQ6h4zwpEfBuo0rZ"
  },
  "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": "67d2febd7a286f59a7643886",
      "conf_id": "67d2febd7a286f59a7643885",
      "auth_token": "eyJhbGciOiJFUzM4NCJ9.eyJpc3MiOiJleWVzb24tY29tYXBpIiwiY2xpZW50X2lkIjoiNjdkMmZlYmQ3YTI4NmY1OWE3NjQzODg2IiwiZXhwIjoxNzQxODg0NjIxLCJjb25mX2lkIjoiNjdkMmZlYmQ3YTI4NmY1OWE3NjQzODg1IiwiYXVkIjoiZXllc29uLXNlcHAifQ.fgRULd2AY85yNvFp3SDqo60ZLoYGn59gmOD3zw7ghzlMduq3C6SddgUq501TwulDWBt1Mubw53veH6tdF37b6snzpQGufQcmBrR2m6HNrGrTijL44NyRjcrbc7TjRKZo",
      "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": "1741967421:67d2febd7a286f59a7643886",
          "password": "jTF47lTP9hqOIWLRfeik2SSZjnY="
        }
      ]
    }
  }
}

danger

The links[gui] is the host link and should be kept a secret as it can be used to start the meeting.

id

Type: STRING (optional)
Default: RANDOM

Arbitrary and unique room 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, unique 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. This value gets used as the display value in the names overlay.

user[avatar]

Type: URL (optional)
Default: NULL

Link to the public avatar image. Avatars will be displayed in the sidebar of our prebuilt user interface.

options[show_names]

Type: BOOLEAN (optional)
Default: TRUE

Show display names in video. This uses the values from user[name]

options[show_label]

Type: BOOLEAN (optional)
Default: TRUE

Show Eyeson logo in Prebuilt-UI. This option can be customized with your own logo

options[exit_url]

Type: URL (optional)
Default: NULL

Prebuilt UI only: After the meeting is exited, the URL given will be displayed.

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[suggest_guest_names]

Type: BOOLEAN (optional)
Default: TRUE

For prebuilt UI, allows generating a random name when joining as a guest.

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

Provides guest token. In case you set this option to FALSE you can give access to the room using the standard user request.

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. To lock the meeting follow the instruction in Lock Meeting

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. To remove a user from the meeting follow the instruction in Kick User

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

options[sfu_mode]

Type: STRING (optional)
Default: ptp

Enables efficient routing of audio and video streams between 2 participants.

Value	Description
`disabled`	The meeting runs in MCU+ mode
`screencast`	Limits the meeting layout to a screencast configuration
`ptp`	For meetings with 2 participants

tip

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

If TRUE the meeting runs in widescreen mode (16:9 aspect ratio), for FALSE the meeting is in standard (4:3 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

Displays the audio activity of participants.

Value	Description
`enabled`	Shows audio activity inserts of all participants
`disabled`	Completely disables audio activity inserts
`audio_only`	Only shows audio activity inserts for participants who are not in the video stream.

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

Sets the preferred language for the Prebuilt-UI interface. English and German translations are officially maintained, while other language translations are community-contributed. For details on available translations and contribution guidelines, see the Web GUI Locale repository on GitHub
Valid values: en, de, fr

options[custom_fields][logo]

Type: URL (optional)
Default: NULL

URL to the public file for a custom logo in Prebuilt-UI. If the URL is not set the Eyeson logo gets shown.
The logo only gets shown when options[show_label] is TRUE.

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.

tip

Use these virtual background control fields to disable background effects when participants need to demonstrate physical objects on camera. This helps prevent common issues where virtual backgrounds interfere with showing physical items like documents.

options[custom_fields][virtual_background_image]

Type: URL (optional)
Default: NULL

Provide a custom Virtual Background image URL for selection in Prebuilt-UI.
Virtual backgrounds support custom static images. For optimal results, use images with a 4:3 aspect ratio. The selected image will automatically scale to cover the entire background area.

warning

Be aware of CORS requirements. The image is loaded in the browser and processed as a virtual background. For the browser to allow access to the image, the URL must deliver it with valid CORS headers, specifically either Access-Control-Allow-Origin: https://app.eyeson.team or Access-Control-Allow-Origin: *.

Parameter Behavior

Parameters That Only Apply at Meeting Room Startup

When creating or joining a meeting, certain parameters can only be effectively set during room initialization and cannot be modified for a running instance:

room[id] - Cannot be changed for a running room (changing it creates/joins a different meeting)
room[name] - Only applies at meeting room creation, changes are silently ignored for existing instances
options[widescreen] - Only effective at meeting startup, subsequent changes are silently ignored

Required vs. Optional Parameters

user[name] is the only required parameter (needed for UI elements, chat labels, voice recognition)
All other parameters are optional with server-generated defaults when omitted

Entity ID Mapping

Specifying your own IDs (user[id], room[id]) allows for easier mapping to your internal systems
These are convenience features that simplify integration but aren't mandatory

Parameter Behavior by Category

User Object Parameters:

All parameters inside the user object relate to specific participants
The user object can include a custom_fields object
User parameters can be set for each joining user

Room Instance Parameters:

Parameters outside the user object apply to the entire room instance
Room options can technically be modified in subsequent join requests, but:
- Some options only take effect at room creation
- Changing options like widescreen after room startup

Get details of current meeting

GET /rooms/`ACCESS_KEY`
RESPONSES 200 OK, 404 NOT FOUND, 410 GONE
REQUIRED user in running meeting

Example Req/Res: Details of current Meeting

Request
curl "https://api.eyeson.team/rooms/$ACCESS_KEY"

Response
{
  "access_key": "VgoCcMUSQQ6h4zwpEfBuo0rZ",
  "ready": true,
  "locked": false,
  "room": {
    "id": "67d2febd7a286f59a7643884",
    "name": "API magic",
    "ready": true,
    "started_at": "2025-03-13T15:50:21.347Z",
    "shutdown": false,
    "guest_token": "77Ua2Abc8ftGDNVzsixwvbcZ"
  },
  "team": {
    "name": "API magic"
  },
  "user": {
    "id": "johndoe",
    "room_id": "67d2febd7a286f59a7643884",
    "name": "John Doe",
    "avatar": null,
    "guest": false,
    "blocked": false,
    "ready": true
  },
  "links": {
    "self": "https://api.eyeson.team/rooms/VgoCcMUSQQ6h4zwpEfBuo0rZ",
    "gui": "https://app.eyeson.team/?VgoCcMUSQQ6h4zwpEfBuo0rZ",
    "guest_join": "https://app.eyeson.team/?guest=77Ua2Abc8ftGDNVzsixwvbcZ",
    "websocket": "https://api.eyeson.team/rt?access_key=VgoCcMUSQQ6h4zwpEfBuo0rZ"
  },
  "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": "67d2febd7a286f59a7643886",
      "conf_id": "67d2febd7a286f59a7643885",
      "auth_token": "eyJhbGciOiJFUzM4NCJ9.eyJpc3MiOiJleWVzb24tY29tYXBpIiwiY2xpZW50X2lkIjoiNjdkMmZlYmQ3YTI4NmY1OWE3NjQzODg2IiwiZXhwIjoxNzQxODg0NjQzLCJjb25mX2lkIjoiNjdkMmZlYmQ3YTI4NmY1OWE3NjQzODg1IiwiYXVkIjoiZXllc29uLXNlcHAifQ.FJ65OTcF3bUgw0taUdCkklz0drf053IHjQwmu72p45iFgstzAnnMNQQ5KbQuWwg3PtTkw8L0LaXnO3f2V77FrhEnuHRSCEQpedg2rj1pvW9Vra6mchvZC5aFHIy-8Jfu",
      "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": "1741967443:67d2febd7a286f59a7643886",
          "password": "R3EckhA8JEKeDlg5hmKPNPY2a38="
        }
      ]
    }
  }
}

End Meeting

DELETE /rooms/`ACCESS_KEY`
RESPONSES 204 NO CONTENT, 404 NOT FOUND, 410 GONE

This is something the user can do with the ACCESS_KEY. If you build a custom UI, you would use this method to end a meeting.

Example Req/Res: End Meeting

Request
curl -X DELETE "https://api.eyeson.team/rooms/$ACCESS_KEY"

No Response

Force Stop Meeting

DELETE /rooms/`ROOM_ID`
HEADERS Authorization
RESPONSES 204 NO CONTENT, 400 BAD REQUEST, 403 FORBIDDEN, 404 NOT FOUND

If you have the API_KEY you can force stop a running meeting.

Example Req/Res: Force Stop Meeting

Request
curl -X DELETE -H "Authorization: $API_KEY" "https://api.eyeson.team/rooms/$ROOM_ID"

Response
Response Status: 204

Get list of current running meetings

GET /rooms
HEADERS Authorization
RESPONSES 200 OK, 403 UNAUTHORIZED

Example Req/Res: Get list of current running meetings

Request
curl -H "Authorization: $API_KEY" "https://api.eyeson.team/rooms"

Response
[
  {
    "id": "67d44a8a7a286f59a76438d7",
    "name": "API magic",
    "ready": true,
    "started_at": "2025-03-14T15:26:02.538Z",
    "shutdown": false,
    "guest_token": "UCUKBgO7sWLOlV8AERC1BZUG"
  }
]

page

Type: Integer (optional)
Default: NULL

Fetch next set of rooms (limit is 25).
This parameter uses 0-based indexing, meaning the first page is 0, second page is 1, etc.

Lock Meeting

Meeting rooms can be locked to prevent new participants from joining. When a room is locked:

Only current participants remain in the meeting
No additional users can join
The lock cannot be reversed during the meeting session

tip

Users with an ACCESS_KEY have privileged access and can exit and rejoin the locked room. Users with a GUEST_TOKEN can only exit the room and cannot rejoin once it is locked. Before locking a room, ensure that all desired participants are present, as only the current participants will retain access.

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 options[lock_available] is set to FALSE, related API requests will respond with status 403 FORBIDDEN.

Example Req/Res: Lock Meeting

Request
curl -X POST -H "Content-Type: application/json" "https://api.eyeson.team/rooms/$ACCESS_KEY/lock"

Response
Response Status: 201

Room Creation and Access​

Room Status​

Start Meeting​

id​

name​

user[id]​

user[name]​

user[avatar]​

options[show_names]​

options[show_label]​

options[exit_url]​

options[recording_available]​

options[broadcast_available]​

options[reaction_available]​

options[suggest_guest_names]​

options[layout_available]​

options[guest_token_available]​

options[lock_available]​

options[kick_available]​

options[sfu_mode]​

options[widescreen]​

options[background_color]​

options[audio_insert]​

options[audio_insert_position][x]​

options[audio_insert_position][y]​

options[custom_fields][locale]​

options[custom_fields][logo]​

options[custom_fields][hide_chat]​

options[custom_fields][virtual_background]​

options[custom_fields][virtual_background_allow_guest]​

options[custom_fields][virtual_background_image]​

Parameter Behavior​

Parameters That Only Apply at Meeting Room Startup​

Required vs. Optional Parameters​

Entity ID Mapping​

Parameter Behavior by Category​

Get details of current meeting​

End Meeting​

Force Stop Meeting​

Get list of current running meetings​

page​

Lock Meeting​

Room Creation and Access

Room Status

Start Meeting

id

name

user[id]

user[name]

user[avatar]

options[show_names]

options[show_label]

options[exit_url]

options[recording_available]

options[broadcast_available]

options[reaction_available]

options[suggest_guest_names]

options[layout_available]

options[guest_token_available]

options[lock_available]

options[kick_available]

options[sfu_mode]

options[widescreen]

options[background_color]

options[audio_insert]

options[audio_insert_position][x]

options[audio_insert_position][y]

options[custom_fields][locale]

options[custom_fields][logo]

options[custom_fields][hide_chat]

options[custom_fields][virtual_background]

options[custom_fields][virtual_background_allow_guest]

options[custom_fields][virtual_background_image]

Parameter Behavior

Parameters That Only Apply at Meeting Room Startup

Required vs. Optional Parameters

Entity ID Mapping

Parameter Behavior by Category

Get details of current meeting

End Meeting

Force Stop Meeting

Get list of current running meetings

page

Lock Meeting