Preflight Checklist
Describe your problem
Hi,
I'm implementing a calling module around Matrix chats using this SDK + LiveKit, and I'd like to flag that the documentation around calls / MatrixRTC is currently very hard to use as an integrator. There are API references and scattered mentions, but no end-to-end guide that walks through a real client implementation, so I've been reverse-engineering from the source and the Element clients.
Rather than just complaining, here are the concrete questions I got stuck on — answers would both unblock me and, ideally, become the basis for a docs page:
1. Call lifecycle
- What is the recommended entry point to start a call against a 1:1 room? Is it through
MatrixRTCSession / GroupCallSession / something else?
- What's the correct sequence: create session → join → publish tracks → ... ?
- How do I cleanly tear a call down on hangup vs. on disconnect vs. on app kill?
2. State tracking
- Which streams or listeners expose call state transitions (ringing → connecting → connected → ended)?
- How do I observe remote participants joining/leaving, and their media state (mute/unmute, video on/off)?
- Is there a single object I should treat as the source of truth, or do I need to combine multiple?
3. Incoming-call signalling
- What event do I send to tell the callee "I'm calling you" so their client can show an incoming-call screen?
- What should the receiving client listen for to detect an incoming call?
- How is this expected to integrate with push notifications (VoIP push / FCM data messages) when the app is backgrounded or killed?
Describe your ideal solution
A "Building calls with LiveKit" guide with a minimal, runnable 1:1 call example covering: starting a MatrixRTC call backed by LiveKit, signalling the callee over Matrix so an incoming-call UI can be shown before joining the LiveKit room, observing both Matrix call state and LiveKit room/participant events, publishing and muting media tracks, and cleanly hanging up — including how this is expected to work alongside push notifications when the app is backgrounded.
Version
matrix: ^6.2.0
Security requirements
No response
Additional Context
livekit_client: ^2.4.5
Preflight Checklist
Describe your problem
Hi,
I'm implementing a calling module around Matrix chats using this SDK + LiveKit, and I'd like to flag that the documentation around calls / MatrixRTC is currently very hard to use as an integrator. There are API references and scattered mentions, but no end-to-end guide that walks through a real client implementation, so I've been reverse-engineering from the source and the Element clients.
Rather than just complaining, here are the concrete questions I got stuck on — answers would both unblock me and, ideally, become the basis for a docs page:
1. Call lifecycle
MatrixRTCSession/GroupCallSession/ something else?2. State tracking
3. Incoming-call signalling
Describe your ideal solution
A "Building calls with LiveKit" guide with a minimal, runnable 1:1 call example covering: starting a MatrixRTC call backed by LiveKit, signalling the callee over Matrix so an incoming-call UI can be shown before joining the LiveKit room, observing both Matrix call state and LiveKit room/participant events, publishing and muting media tracks, and cleanly hanging up — including how this is expected to work alongside push notifications when the app is backgrounded.
Version
matrix: ^6.2.0
Security requirements
No response
Additional Context
livekit_client: ^2.4.5