Set room participant audience

Rate limit: Per command · Burst: 15 · Refill: 10 req/s

Set who hears a room participant. The request body is an audience object selected by type:

• everyone: everyone in the room hears the participant.
• nobody: nobody in the room hears the participant.
• participants: only the room participants listed in participants hear the participant.

Triggered webhooks: room.participant.audience_changed (deferred, emitted only when the participant’s effective audience changes), room.participant.audience_change_failed

With participants, the listed participants still hear the room normally, and the participant keeps hearing the whole room. Nobody else in the room hears the participant, and neither does the room recording. A session recording of a listed participant includes the participant. For example:

{"type": "participants", "participants": [{"uuid": "<session uuid of a listed participant>", "volume": 5}]}

Each listed participant has an optional volume, an integer from 1 to 9 (default 5, normal/unchanged, the same scale as POST /v1/sessions/{uuid}/room/volume). It sets how loudly that participant hears this participant’s whisper, and nothing else: how the listed participant hears the room, how the room hears them, and their own room/volume setting are unchanged. To change one participant’s volume, send the audience again with the new value; the other listed participants keep their volume, and the whisper continues without interruption.

A participants request returns 400 with code: invalid_request when the list is empty, repeats a uuid, contains the participant itself, has a volume outside 1 to 9, or lists more sessions than the room’s participant limit.

A listed session that is not a current participant of the same room is not an error: a participant can leave between reading the participant list and sending the request, so that session is dropped from the list and the request is still accepted.

When a listed participant leaves the room, it is removed from the list. An empty list means nobody hears the participant; the audience never reverts to everyone. Changing the audience to everyone or nobody stops the listed participants from hearing the participant privately.

The 202 response acknowledges asynchronous admission. The change is complete when one of these webhooks arrives:

• room.participant.audience_changed after the whole requested audience is in effect, only when the effective audience changes. Its audience is the effective new audience, including participants without any dropped session.
• room.participant.audience_change_failed with reason: execution_failed when the requested audience could not be put fully in effect, including a volume that could not be applied. failed_participants lists the session UUIDs of the participants that do not hear the participant, and audience is the audience actually in effect.

After a participants audience is in effect, room.participant.audience_change_failed with reason: audience_lost reports a listed participant that stopped hearing the participant. A failure never makes the participant audible to the whole room.

Requests are applied in the order they are accepted, so the last accepted request determines the final audience. Requesting the audience the participant already has returns 202 and emits no event.

See Room lifecycle, participant, and playback events for complete payload schemas and examples.