Control

The control module contains the base functionality for the conference including information like the participant list, roles and hand raise.

Commands

Join

Must be the first message to be sent when the websocket connection is established.

Fields

Field	Type	Required	Description
action	enum	yes	Must be "join"
display_name	string	yes	String to be displayed as the user's display name in the room

Example

{
    "action": "join",
    "display_name": "Test"
}

---

EnterRoom

Can only be sent while in the waiting room and after being accepted by a moderator.

See InWaitingRoom

Fields

Field	Type	Required	Description
action	enum	yes	Must be "enter_room"

Example

{
    "action": "enter_room"
}

---

Raise Hand

Notify other participants that a participant's hand is raised.

Fields

Field	Type	Required	Description
action	enum	yes	Must be "raise_hand"

Example

{
    "action": "raise_hand"
}

---

Lower Hand

Notify other participants that a participant's hand is no longer raised.

Fields

Field	Type	Required	Description
action	enum	yes	Must be "raise_hand"

Example

{
    "action": "raise_hand"
}

---

Grant moderator role

Requires moderator role.

Grant a participant the moderator role.

Fields

Field	Type	Required	Description
action	enum	yes	Must be "grant_moderator_role"
target	string	yes	Id of the participant to grant the moderator role

Example

{
    "action": "grant_moderator_role",
    "target": "00000000-0000-0000-0000-000000000000"
}

---

Revoke moderator role

Requires moderator role.

Revoke the moderator role from a participant. Cannot revoke the moderator role from the creator of the room.

Fields

Field	Type	Required	Description
action	enum	yes	Must be "grant_moderator_role"
target	string	yes	Id of the participant to revoke the moderator role from

Example

{
    "action": "revoke_moderator_role",
    "target": "00000000-0000-0000-0000-000000000000"
}

---

Events

Data Types

Participant

Fields

Information about another participant

Field	Type	Always	Description
id	string	yes	ID of the participant
control	ControlData	yes	Information about the participant provided by the control module
some_other_module...	object	?	Not an actual field but every module can attach data about the participant under their name

ControlData

Information about another participant provided by the control module

Fields

Field	Type	Always	Description
display_name	string	yes	Display name of the participant
role	enum	yes	either "guest,, "user" or "moderator"
avatar_url	string	no	url to your avatar image if the participant is a logged in user
participation_kind	enum	yes	either "user", "guest" or "sip"
hand_is_up	bool	yes	true if the user is currently raising their hand
joined_at	string	yes	timestamp of when the participant joined
left_at	string	no	timestamp of when the participant left the room
hand_updated_at	string	yes	timestamp of when the hand-raise status last changed
is_room_owner	bool	yes	true if the user is the owner of the room

EventInfo

Fields

Information about the event associated with a room.

Field	Type	Always	Description
id	string	yes	Id of the event
room_id	string	yes	Id of the room belonging to the event. (deprecated! use the room_info field from the JoinSuccess message instead)
title	string	yes	Title of the event
is_adhoc	bool	yes	True if the event was created ad-hoc
meeting_details	MeetingDetails	no	Meeting for an event associated with a room. See: MeetingDetails

MeetingDetails

Fields

Meeting details for an event associated with a room.

Field	Type	Always	Description
invite_code_id	string	no	Invite code id of the event
call_in	CallIn	no	Dial-in information for the event. See: CallIn
streaming_links	StreamingLink[]	yes	Links for accessing the stream. See: StreamingLink

CallIn

Fields

Meeting details for an event associated with a room.

Field	Type	Always	Description
tel	string	yes	SIP call-in phone number which must be used to reach the room
id	string	yes	SIP ID which must transmitted via DTMF
password	string	yes	SIP password which must be transmitted via DTMF

StreamingLink

Fields

Meeting details for an event associated with a room.

Field	Type	Always	Description
name	string	yes	Name of the streaming link
url	string	yes	Url of the streaming link

RoomInfo

Fields

Information about the current room.

Field	Type	Always	Description
id	string	yes	Id of the room
password	string	no	The room password, if one is configured
created_by	UserInfo	yes	Information about the user that created the room. SeeUserInfo

UserInfo

Fields

Information about the creator of the current room.

Field	Type	Always	Description
title	string	yes	The users title
firstname	string	yes	The users first name
lastname	string	yes	The users last name
display_name	string	yes	The users configured display name
avatar_url	string	yes	The url to the users avatar

JoinSuccess

Received after joining the room. Can be triggered by either calling Join or EnterRoom.

Fields

Field	Type	Always	Description
message	enum	yes	Is "join_success"
id	string	yes	Your participant id in this session
display_name	string	yes	Your display name in this session
avatar_url	string	no	Url to your avatar image if logged
role	enum	yes	Either "guest", "user" or "moderator"
closes_at	string	no	The point in time the room closes
tariff	Tariff	yes	Tariff information, including quotas and modules
participants	Participant[]	yes	List of participants in the room
event_info	EventInfo	no	Information about the event associated with the meeting room. See: EventInfo
room_info	RoomInfo	yes	Information about the current room. See: RoomInfo

Example

{
  "message": "join_success",
  "id": "00000000-0000-0000-0000-000000000000",
  "display_name": "My Display Name",
  "avatar_url":"https://example.org/",
  "role": "moderator",
  "closes_at": "2023-03-10T16:52:54Z",
  "is_room_owner": true,
  "tariff": {
    "id": "53db7cb1-12af-4715-9b17-4a5a57876085",
    "name": "OpenTalkDefaultTariff",
    "quotas": {},
    "modules":{
      "core": {"features": ["feature2", "feature3"]},
      "chat": {}
    }
  },
  "participants": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "control": {
        "display_name": "Someone Else",
        "hand_is_up": false,
        "hand_updated_at": "2022-05-10T10:40:39Z",
        "joined_at": "2022-05-10T10:40:39Z",
        "left_at": "2022-05-10T10:40:42Z",
        "participation_kind": "user",
        "is_room_owner": false
      }
    }
  ],
  "event_info": {
    "id": "fa31b241-612d-4524-930e-b5b0af12acb1",
    "title": "Daily"
  },
  "room_info": {
    "id": "00000000-0000-0000-0000-000000000000",
    "password": "secret123",
    "created_by": {
      "title": "Dr.",
      "firstname": "Firstname",
      "lastname": "Lastname",
      "display_name": "The Creator",
      "avatar_url": "https://example.org/",
    }
  }
}

JoinBlocked

If a tariff is configured for a room, an issued Join action may result in this event.

Fields

Field	Type	Always	Description
message	enum	yes	Is "join_blocked"
reason	enum	yes	Is "participant_limit_reached"

Example

{
    "message": "join_blocked",
    "reason": "participant_limit_reached"
}

Update

Received when a participant changes their state. Wraps a Participant.

Fields

Field	Type	Always	Description
message	enum	yes	Is "update"

Example

{
    "message": "update",
    "id": "00000000-0000-0000-0000-000000000000",
    "control": {
      "display_name": "Someone Else",
      "hand_is_up": false,
      "hand_updated_at": "2022-05-10T10:40:39Z",
      "joined_at": "2022-05-10T10:40:39Z",
      "left_at": "2022-05-10T10:40:42Z",
      "participation_kind": "user"
    }
}

Joined

Received when a participant joined the room. Wraps a Participant.

Fields

Field	Type	Always	Description
message	enum	yes	Is "joined"

Example

{
    "message": "joined",
    "id": "00000000-0000-0000-0000-000000000000",
    "control": {
      "display_name": "Someone Else",
      "hand_is_up": false,
      "hand_updated_at": "2022-05-10T10:40:39Z",
      "joined_at": "2022-05-10T10:40:39Z",
      "left_at": "2022-05-10T10:40:42Z",
      "participation_kind": "user"
    }
}

Left

Received when a participant left the room.

Fields

Field	Type	Always	Description
message	enum	yes	Is "left"
id	string	yes	Id of the participant that has left
reason	enum	yes	The reason as to why the participant left either "quit", "timeout" or "sent_to_waiting_room"

Example

{
    "message": "left",
    "id": "00000000-0000-0000-0000-000000000000",
    "reason": "quit"
}

TimeLimitQuotaElapsed

Received when the quota's time limit has elapsed.

Fields

Field	Type	Always	Description
message	enum	yes	Is "time_limit_quota_elapsed"

RateLimitExceeded

The participant has exceeded the configured rate limit of the controller

This will be the last message received before the participant is removed from the conference

Fields

Field	Type	Always	Description
message	enum	yes	Is "rate_limit_exceeded"

HandRaised

Received by a participant after they have raised their hand.

Fields

Field	Type	Always	Description
message	enum	yes	Is "hand_raised"

HandLowered

Received by a participant after they have lowered their hand.

Fields

Field	Type	Always	Description
message	enum	yes	Is "hand_lowered"

RoleUpdated

Received when a moderator assigned a new role to a participant. This message is sent to the affected participants

Fields

Field	Type	Always	Description
message	enum	yes	Is "role_updated"
new_role	enum	yes	either "guest", "user", "moderator"

Example

{
    "message": "role_updated",
    "new_role": "moderator"
}

ModeratorRoleGranted

Moderator rights have been granted to the specified participant. This message is sent to the participant who has executed the grant_moderator_rolecommand

Fields

Field	Type	Always	Description
message	enum	yes	Is "moderator_role_granted"
target	string	yes	Participant id to grant the presenter role to

Example

{
    "message": "moderator_role_granted",
    "target": "84a2c872-94fb-4b41-aca7-13d784c92a72"
}

ModeratorRoleRevoked

Moderator rights have been revoked from the specified participant. This message is sent to the participant who has executed the revoke_moderator_rolecommand

Fields

Field	Type	Always	Description
message	enum	yes	Is "moderator_role_revoked"
target	string	yes	Participant id to revoke the presenter role from

Example

{
    "message": "moderator_role_revoked",
    "target": "84a2c872-94fb-4b41-aca7-13d784c92a72"
}

RoomDeleted

Received by a participant if removed from the room because the room has been deleted. Will be the last message before server-side websocket disconnection.

Fields

Field	Type	Always	Description
message	enum	yes	Is "room_deleted"

Error

Received when something went wrong.

Fields

Field	Type	Always	Description
message	enum	yes	Is "error"
text	enum	yes	arbitrary error text

Example

{
    "message": "error",
    "text": "something happened"
}