TRaX Docs
guides

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.