Subroom Audio

This module implements signaling that allows participants to manage a group of whisper participants. Participants in a whisper group gain access to an audio-only livekit room, where they can talk without being heard by other participants in the conference.

The implementing frontend, still has to do most of the livekit management associated with this feature. This module only creates the livekit room, the tokens to join that room and tracks the whisper group state to enforce some behavior.

The WhisperId that is returned in various events is also the name of the livekit room.

After a livekit access token has been provided through the WhisperGroupCreated or WhisperToken event, the frontend has to connect to the whisper room by itself. The tokens are restricted to audio only, and are revoked when the participant leaves the whisper group.

Commands

CreateWhisperGroup

Creates a new whisper group with the targeted participants. The group creator is implicitly contained in the group.

Fields

Field	Type	Required	Description
action	enum	yes	Must be "create_whisper_group"
participants_ids	Participant[]	yes	Ids of participants to invite

Example

{
    "action": "create_whisper_group",
    "participant_ids": ["00000000-0000-0000-0000-000000000000", "00000000-0000-0000-0000-000000000001"]
}

Response

WhisperGroupCreated for the creator and WhisperInvite for the invitees.

---

InviteToWhisperGroup

Invite participants to an existing whisper group.

Fields

Field	Type	Required	Description
action	enum	yes	Must be "invite_to_whisper_group"
whisper_id	string	yes	The id of the whisper group
participant_ids	Participant[]	yes	Ids of participants to invite

Example

{
    "action": "invite_to_whisper_group",
    "whisper_id": "00000000-0000-0000-0000-000000000000",
    "participant_ids": ["00000000-0000-0000-0000-000000000000", "00000000-0000-0000-0000-000000000001"]
}

Response

ParticipantsInvited for the creator and existing participants and WhisperInvite for the new invitees.

---

AcceptWhisperInvite

Accept an invite to a whisper group.

Fields

Field	Type	Required	Description
action	enum	yes	Must be "accept_whisper_invite"
whisper_id	string	yes	The id of the whisper group

Example

{
    "action": "accept_whisper_invite",
    "whisper_id": "00000000-0000-0000-0000-000000000000"
}

Response

WhisperToken to the accepting participant, containing the access token for the whisper room. Other participants in the whisper group receive a WhisperInviteAccepted as a notification that another participant joined the room.

---

DeclineWhisperInvite

Decline an invitation to a whisper group.

Fields

Field	Type	Required	Description
action	enum	yes	Must be "decline_whisper_invite"
whisper_id	string	yes	The id of the whisper group

Example

{
    "action": "decline_whisper_invite",
    "whisper_id": "00000000-0000-0000-0000-000000000000"
}

Response

Other participants in the whisper group receive a WhisperInviteDeclined.

---

KickWhisperParticipants

Remove a participant from the whisper group, only the creator of the group can kick participants.

Fields

Field	Type	Required	Description
action	enum	yes	Must be "kick_whisper_participants"
whisper_id	string	yes	The id of the whisper group
participant_ids	Participant[]	yes	Ids of participants to be removed from the group

Example

{
    "action": "kick_whisper_participants",
    "whisper_id": "00000000-0000-0000-0000-000000000000",
    "participant_ids": ["00000000-0000-0000-0000-000000000000", "00000000-0000-0000-0000-000000000001"]
}

Response

The kicked participants receive a Kicked message. Other participants in the whisper group receive a LeftWhisperGroup for each participant that has been kicked.

---

LeaveWhisperGroup

Leave the whisper group. The participant will get removed from the livekit whisper room.

The group gets disbanded when the last participant leaves the group.

Fields

Field	Type	Required	Description
action	enum	yes	Must be "leave_whisper_group"
whisper_id	string	yes	The id of the whisper group

Example

{
    "action": "leave_whisper_group",
    "whisper_id": "00000000-0000-0000-0000-000000000000"
}

Response

Other participants in the whisper group receive a LeftWhisperGroup.

---

Events

WhisperGroupCreated

Direct response to CreateWhisperGroup.

The participants in the list have a state associated with them, see WhisperParticipant for the type structure.

Fields

Field	Type	Required	Description
message	enum	yes	Is "whisper_group_created"
whisper_id	string	yes	The id of the whisper group
participants	WhisperParticipant[]	yes	List of invited participants and their state (see WhisperParticipant)
token	string	yes	The livekit access token that allows the participant to join the whisper room

Example

{
  "message": "whisper_group_created",
  "whisper_id": "00000000-0000-0000-0000-000000000000",
  "token": "<jwt-token>",
  "participants": [
    {
      "participant_id": "00000000-0000-0000-0000-000000000000",
      "state": "creator"
    },
    {
      "participant_id": "00000000-0000-0000-0000-000000000001",
      "state": "accepted"
    },
    {
      "participant_id": "00000000-0000-0000-0000-000000000002",
      "state": "invited"
    }
  ]
}

---

WhisperInvite

Received by participants that were invited through CreateWhisperGroup or InviteToWhisperGroup.

The participants in the list have a state associated with them, see WhisperParticipant for the type structure.

Fields

Field	Type	Required	Description
message	enum	yes	Is "whisper_invite"
whisper_id	string	yes	The id of the whisper group
issuer	string	yes	The participant id of the invite issuer
participants	WhisperParticipant[]	yes	List of invited participants and their state (see WhisperParticipant)

Example

{
  "message": "whisper_invite",
  "whisper_id": "00000000-0000-0000-0000-000000000000",
  "issuer": "00000000-0000-0000-0000-000000000000",
  "participants": [
    {
      "participant_id": "00000000-0000-0000-0000-000000000000",
      "state": "invited"
    },
    {
      "participant_id": "00000000-0000-0000-0000-000000000000",
      "state": {
        "accepted": {
          "track_id": "00000000-0000-0000-0000-000000000000"
        }
      }
    }
  ]
}

---

WhisperToken

A direct response to AcceptWhisperInvite. Contains the livekit access token to the whisper room.

Fields

Field	Type	Required	Description
message	enum	yes	Is "whisper_token"
whisper_id	string	yes	The id of the whisper group
token	string	yes	The livekit access token that allows the participant to join the whisper room

Example

{
  "message": "whisper_token",
  "whisper_id": "00000000-0000-0000-0000-000000000000",
  "token": "<jwt-token>"
}

---

ParticipantsInvited

Received by all participants when a new set of participants were invited through InviteToWhisperGroup.

Fields

Field	Type	Required	Description
message	enum	yes	Is "participants_invited"
whisper_id	string	yes	The id of the whisper group
participant_ids	Participant[]	yes	The list of invited participants

Example

{
  "message": "participants_invited",
  "whisper_id": "00000000-0000-0000-0000-000000000000",
  "participant_ids": ["00000000-0000-0000-0000-000000000000", "00000000-0000-0000-0000-000000000001"]
}

---

WhisperInviteAccepted

Received by all participants in the whisper group when another invitee accepts the group invite.

Fields

Field	Type	Required	Description
message	enum	yes	Is "whisper_invite_accepted"
whisper_id	string	yes	The id of the whisper group
participant_id	Participant	yes	The participant that accepted the group invite

Example

{
  "message": "whisper_invite_accepted",
  "whisper_id": "00000000-0000-0000-0000-000000000000",
  "participant_id": "00000000-0000-0000-0000-000000000000"
}

---

WhisperInviteDeclined

Received by all participants in the whisper group when another invitee declines the group invite.

Fields

Field	Type	Required	Description
message	enum	yes	Is "whisper_invite_declined"
whisper_id	string	yes	The id of the whisper group
participant_id	Participant	yes	The participant that declined the invite

Example

{
  "message": "whisper_invite_declined",
  "whisper_id": "00000000-0000-0000-0000-000000000000",
  "participant_id": "00000000-0000-0000-0000-000000000000"
}

---

Kicked

Received by a participant when they get kicked from the whisper group. The whisper group will be inaccessible after receiving this message.

Fields

Field	Type	Required	Description
message	enum	yes	Is "kicked"
whisper_id	string	yes	The id of the whisper group

Example

{
  "message": "kicked",
  "whisper_id": "00000000-0000-0000-0000-000000000000",
}

---

LeftWhisperGroup

Received when another participant leaves the whisper group either through LeaveWhisperGroup or gets kicked with the Kicked command.

Fields

Field	Type	Required	Description
message	enum	yes	Is "left_whisper_group"
whisper_id	string	yes	The id of the whisper group

Example

{
  "message": "left_whisper_group",
  "whisper_id": "00000000-0000-0000-0000-000000000000",
}

---

Error

Fields

Field	Type	Always	Description
message	enum	yes	Is "error"
error	enum	yes	Exhaustive list of error strings, see table below
participant_ids	Participant[]	non	Only present when error is invalid_participant_targets. A List of invalid participants

Error	Description
invalid_whisper_id	The provided whisper id does not exist
already_accepted	The participant already accepted an invite to this group
insufficient_permissions	The requesting user has insufficient permissions for the operation
empty_participant_list	The provided participant list is empty
invalid_participant_targets	The targeted participants do not exist
livekit_unavailable	The livekit service is unavailable
not_invited	The requesting participant is not invited to the whisper group

Example

{
    "message":"error",
    "error":"invalid_whisper_id"
}

{
    "message":"error",
    "error":"insufficient_permissions"
}

{
    "message":"error",
    "error":"empty_participant_list"
}

{
    "message":"error",
    "error":"invalid_participant_targets",
    "participant_ids": ["00000000-0000-0000-0000-000000000123"]
}

---

Structural Types

WhisperParticipant

A representation of a whisper participant and their invitation state. Used in WhisperGroupCreated and WhisperInvite

Field	Type	Required	Description
participant_id	Participant	yes	The participant id
state	enum	yes	The state of the participant in the whisper group, see table below

State	Description
creator	The initiator of the whisper group gets the creator state
invited	The participant has been invited to the whisper group
accepted	The participant has accepted the invite to the whisper group