Join a private intercom
Intercom is private audio for the crew. Joining it does not add a program source and does not open a microphone, camera or screen. A successful request confirms membership only; it does not prove that anyone can hear you.
Scopes and permissions
| Scope | Allows | Studio permission |
|---|---|---|
intercom:read |
GET /v1/studios/{studioId}/intercom/rooms, and room updates on the studio events stream |
View |
intercom:join |
Join, refresh, update and leave a membership | View |
intercom:publish |
Turn on your microphone (together with intercom:join) |
Edit |
None of these scopes is added to existing API keys automatically.
Join and listen
Send POST /v1/studios/{studioId}/intercom/memberships:
{"channel":"crew","idempotencyKey":"client-generated-unique-attempt-key"}
channel must be crew. idempotencyKey is 8 to 128 characters your client
generates for this join attempt. If the response is lost, retry with the same
key. After leaving, a new join needs a new key; an old key never replaces a
newer membership.
The response is a grant:
| Field | What it is |
|---|---|
membershipId |
Opaque id for this membership. Use it in every later call. |
room |
The room and its participants |
canPublish |
Whether this grant allows you to publish audio |
token |
Private media credential. Never log it, cache it, or send it anywhere else. |
mediamtxBaseUrl, publishPath, whipUrl, iceServers |
Where and how to connect media. iceServers may include TURN credentials, which are also secret. |
expiresAt |
When the membership expires |
credentialExpiresAt |
When the media credential expires |
To listen, subscribe to each other participant's audioPath using
mediamtxBaseUrl and token. Leave out your own publishPath. A participant
with a microphone grant is not necessarily sending audio yet: check their
microphoneState, and expect a short delay before a new stream is ready.
Browsers may block audio playback until the user interacts with the page, so
show when playback is blocked, pending or failed.
Turn on the microphone
Only after the user explicitly asks to talk, send
POST /v1/studios/{studioId}/intercom/memberships/{membershipId}/microphone:
{"publish":true}
This needs intercom:publish and edit permission. Your client then asks for
microphone permission itself and publishes only that audio track, using the
returned grant. Never open a microphone just because a roster or a refreshed
grant says canPublish: true. Keep the microphone muted until the publisher is
connected and the user chooses to talk.
Send {"publish":false} to give up the microphone and keep listening; it needs
only view permission. Stop your publisher and microphone tracks at once. The
server does not instantly cut off a media token or media session it has already
issued, so do not rely on this call to stop the audio.
Refresh, update and leave
Refresh before either expiry with
POST /v1/studios/{studioId}/intercom/memberships/{membershipId}/refresh, with
no body. Refresh never turns a listener into a publisher. Refreshing a
membership that is publishing needs intercom:publish; a key without it is
refused and the membership is left as it was. Stop your media when access
expires or a refresh fails. An expired membership needs a new join.
Report your local state with
PATCH /v1/studios/{studioId}/intercom/memberships/{membershipId}. Every field
is optional, and omitted fields are left unchanged:
{"listenState":"connected","microphoneState":"idle","mediaErrorCode":"none"}
| Field | Values |
|---|---|
listenState, microphoneState |
idle, connecting, connected, failed |
mediaErrorCode |
none, permission_denied, publish_failed, subscribe_failed, playback_blocked, credential_expired |
talking |
true or false. true needs intercom:publish and an existing publish grant. |
listenMuted |
true or false |
listenLevel |
A number from 0 to 1 |
Never send raw device errors, tokens, SDP or private URLs. The server records
when it received the report as mediaObservedAt. These are your client's
reports, not server measurements of audible audio. If an update to talking
fails, leave the local microphone muted.
Leave with DELETE /v1/studios/{studioId}/intercom/memberships/{membershipId}
and stop all your tracks and readers. This ends only your membership.
Discard any delayed response whose studio, connection or membership no longer matches your client's current state. In particular, a late leave must never act on a newer membership.
Follow the room
With intercom:read on top of the usual event-stream scopes,
GET /v1/studios/{studioId}/events sends whole-room intercom events, and its
snapshot includes intercomRooms. Neither contains tokens or TURN credentials.
Replace that room's roster with each event, including when it becomes empty.
Show reported progress and failures separately from membership.
After a disconnect, recover missed state from the fresh snapshot or from
GET /v1/studios/{studioId}/intercom/rooms. Reconnecting with Last-Event-ID
does not guarantee a replay of every intermediate audio state change.