Calling overview
Understand audio and video calling signaling, room models, and event lifecycles in the OpenIM Android SDK.
The OpenIM Android SDK's SignalingManager provides the signaling pipeline required to initiate, accept, reject, cancel, and hang up calls, query room states, and synchronize call participants. It orchestrates call metadata, participant rosters, and call lifecycles, but does not capture camera frames, process audio streams, or render video views.
Pass the roomID, token, and liveURL returned by the SDK to your chosen WebRTC or LiveKit media engine. Your application handles Android runtime permissions, audio routing, media tracks, network adaptation, and calling UI state.
Calling lifecycle
- The caller initiates a call using Start a single call or Start a group call.
- The callee receives an incoming invitation event and accepts or rejects the call.
- The answering party calls Accept a call, and both sides connect to LiveKit or WebRTC using room credentials returned by the server.
- Active screens render participant lists, published tracks, and custom business signals during the call.
- Before connection, the caller can Cancel a call invitation; after connection, any participant can Hang up a call.
Core data structures
| Structure | Description |
|---|---|
SignalingInvitationInfo | Inviter, invitees, group ID, room ID, media type, timeout, session type, and custom extension payload. |
SignalingInfo | Current operator, complete invitation data received in events, participant profiles, and optional offline push details. |
SignalingCertificate | roomID, token, liveURL, and busy user lists returned by OpenIMServer. |
RoomCallingInfo | Room details, active invitation, participant roster, group metadata, and access credentials queried by group ID. |
Use customData and custom signaling to exchange lightweight, transient session negotiation data. Do not use signaling channels for bulk file transfers or persistent database storage.
State updates and event ownership
Distinguish clearly between asynchronous API callbacks and real-time signaling events. An API success callback indicates that the server accepted the signaling request; participant state transitions are delivered asynchronously through event listeners.
For the centralized listener handling invitation lifecycles, room entries, exits, hang-ups, and stream updates, see Handle call events. For application-specific signals, see Send a custom signal.
The global primary key for call state is roomID; individual participant state is keyed by roomID combined with userID. When recovering after app restarts or network disconnections, query room APIs to calibrate local state.
Navigation by task
| Task | Documentation page |
|---|---|
| Initiate a direct or group call | Start a single call, Start a group call |
| Accept or decline an invitation | Accept a call, Reject a call |
| Cancel an invitation or terminate a call | Cancel a call invitation, Hang up a call |
| Recover room state or pending invitations | Query group call room, Get call room token, Restore pending invitation received before launch |
| Handle signaling events and custom messages | Handle call events, Send a custom signal |
Was this page helpful?