Events

Handle call session events to build responsive UIs. The SDK provides five session listener protocols to monitor session status, participant activities, media changes, button clicks, and layout changes, plus two global listeners for incoming calls and login state. The SDK holds every listener weakly and removes none of them for you, so keep a strong reference to each listener object and remove it when your screen goes away.

Get CallSession Instance

The CallSession is a singleton that manages the active call. All event listener registrations and session control methods are accessed through this instance.

let callSession = CallSession.shared

CallSession.shared always exists, so listeners registered on it work before any session does. To ask whether there is a session right now, use CometChatCalls.getActiveSession():

// nil when no session is prepared or joined
if let session = CometChatCalls.getActiveSession() {
    print("Live session \(session.sessionId ?? "")")
}

getActiveSession() returns CallSession.shared as soon as a session is prepared, which is what CometChatCalls.initiateCall does on the caller and what the Push SDK’s ring does on the callee, before anyone joins. That is what lets a caller listen for “ringing” and “answered” without joining (see Ringing). Before a session is prepared or joined it returns nil, so code that registers through it (getActiveSession()?.addSessionStatusListener(self)) registers nothing; register on CallSession.shared instead.

CallSession holds listeners weakly. It does not keep your listener alive, so the object you register must be owned elsewhere, such as the view controller itself (as in the examples below) or a stored property. A listener created inline, like addSessionStatusListener(MyListener()), is deallocated right away and never receives an event. A deallocated listener is dropped automatically. Call removeSessionStatusListener, removeParticipantEventListener, etc. when you want events to stop before the listener goes away.

Session Events

Monitor the call session lifecycle including join/leave events and connection status.

class CallViewController: UIViewController, SessionStatusListener {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        CallSession.shared.addSessionStatusListener(self)
    }
    
    deinit {
        CallSession.shared.removeSessionStatusListener(self)
    }
    
    func onConnected() {
        // A prepared session is connected (signalling only): the join will be near-instant
    }

    func onSessionJoined() {
        // Successfully connected to the session
    }

    func onSessionLeft() {
        // Left the session
        navigationController?.popViewController(animated: true)
    }

    func onSessionTimedOut() {
        // Session ended due to inactivity
        navigationController?.popViewController(animated: true)
    }

    func onConnectionLost() {
        // Network interrupted, attempting reconnection
    }

    func onConnectionRestored() {
        // Connection restored after being lost
    }

    func onConnectionClosed() {
        // Connection permanently closed. On a session that was only prepared
        // (an outgoing call still ringing), this means the call ended before anyone joined.
        navigationController?.popViewController(animated: true)
    }
}

Event	Description
`onConnected()`	A prepared session connected: signalling only, no media, and other participants do not see you yet. Fires once per prepare (`initiateCall` on the caller, the Push SDK’s ring on the callee); the media join is `onSessionJoined()`
`onSessionJoined()`	Successfully connected and joined the session
`onSessionLeft()`	Left the session via `leave()` or was removed
`onSessionTimedOut()`	Session ended due to inactivity timeout. Not used on a prepared session: one nobody joins within 5 minutes reports `onConnectionClosed()`
`onConnectionLost()`	Network interrupted, SDK attempting reconnection
`onConnectionRestored()`	Connection restored after being lost
`onConnectionClosed()`	Connection permanently closed, cannot reconnect. On a prepared session: it closed before anyone joined (a decline or ring-out when the callee’s device had prepared it, a cancel, the room going away, or nobody joining within 5 minutes). A busy decline doesn’t close it

Participant Events

Monitor participant activities including join/leave, audio/video state, hand raise, screen sharing, and recording.

class CallViewController: UIViewController, ParticipantEventListener {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        CallSession.shared.addParticipantEventListener(self)
    }
    
    deinit {
        CallSession.shared.removeParticipantEventListener(self)
    }
    
    func onParticipantConnected(participant: Participant) {
        // A participant's device prepared the session but has not joined yet.
        // On an outgoing call: the callee's phone is ringing.
    }

    func onParticipantJoined(participant: Participant) {
        // A participant joined the call. On an outgoing call: the callee answered.
    }

    func onParticipantLeft(participant: Participant) {
        // A participant left the call
    }

    func onParticipantListChanged(participants: [Participant]) {
        // Participant list updated
    }

    func onParticipantAudioMuted(participant: Participant) {}
    func onParticipantAudioUnmuted(participant: Participant) {}
    func onParticipantVideoPaused(participant: Participant) {}
    func onParticipantVideoResumed(participant: Participant) {}
    func onParticipantHandRaised(participant: Participant) {}
    func onParticipantHandLowered(participant: Participant) {}
    func onParticipantStartedScreenShare(participant: Participant) {}
    func onParticipantStoppedScreenShare(participant: Participant) {}
    func onParticipantStartedRecording(participant: Participant) {}
    func onParticipantStoppedRecording(participant: Participant) {}
    func onDominantSpeakerChanged(participant: Participant) {}
}

Event	Parameter	Description
`onParticipantConnected`	`Participant`	A remote participant’s device prepared the session without joining. On the caller’s prepared session this is the callee ringing
`onParticipantJoined`	`Participant`	A participant joined the call. On the caller’s prepared session this is the callee answering: join now
`onParticipantLeft`	`Participant`	A participant disconnected from the call
`onParticipantListChanged`	`[Participant]`	Participant list updated
`onParticipantAudioMuted`	`Participant`	A participant muted their microphone
`onParticipantAudioUnmuted`	`Participant`	A participant unmuted their microphone
`onParticipantVideoPaused`	`Participant`	A participant turned off their camera
`onParticipantVideoResumed`	`Participant`	A participant turned on their camera
`onParticipantHandRaised`	`Participant`	A participant raised their hand
`onParticipantHandLowered`	`Participant`	A participant lowered their hand
`onParticipantStartedScreenShare`	`Participant`	A participant started screen sharing
`onParticipantStoppedScreenShare`	`Participant`	A participant stopped screen sharing
`onParticipantStartedRecording`	`Participant`	A participant started recording
`onParticipantStoppedRecording`	`Participant`	A participant stopped recording
`onDominantSpeakerChanged`	`Participant`	The active speaker changed

Media Events

Monitor your local media state changes including audio/video status, recording, and device changes.

class CallViewController: UIViewController, MediaEventsListener {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        CallSession.shared.addMediaEventsListener(self)
    }
    
    deinit {
        CallSession.shared.removeMediaEventsListener(self)
    }
    
    func onAudioMuted() {
        // Your microphone was muted
    }

    func onAudioUnMuted() {
        // Your microphone was unmuted
    }

    func onVideoPaused() {
        // Your camera was turned off
    }

    func onVideoResumed() {
        // Your camera was turned on
    }

    func onRecordingStarted() {
        // Call recording started
    }

    func onRecordingStopped() {
        // Call recording stopped
    }

    func onAudioModeChanged(audioMode: AudioMode) {
        // Audio output device changed
    }

    func onCameraFacingChanged(cameraFacing: CameraFacing) {
        // Camera switched between front and back
    }
}

Event	Parameter	Description
`onAudioMuted`	-	Your microphone was muted
`onAudioUnMuted`	-	Your microphone was unmuted
`onVideoPaused`	-	Your camera was turned off
`onVideoResumed`	-	Your camera was turned on
`onRecordingStarted`	-	Call recording started
`onRecordingStopped`	-	Call recording stopped
`onAudioModeChanged`	`AudioMode`	Audio output device changed
`onCameraFacingChanged`	`CameraFacing`	Camera switched between front and back

MediaEventsListener has no screen-share callback. Screen sharing is observed on ParticipantEventListener via onParticipantStartedScreenShare / onParticipantStoppedScreenShare — and on iOS those are receive-only: the SDK reports a share started from another client, but has no API to start one locally.

AudioMode Values

Value	Description
`.speaker`	Audio routed through device loudspeaker
`.earpiece`	Audio routed through phone earpiece
`.bluetooth`	Audio routed through connected Bluetooth device
`.headphones`	Audio routed through wired headphones

CameraFacing Values

Value	Description
`.FRONT`	Front-facing (selfie) camera is active
`.REAR`	Rear-facing (main) camera is active

Button Click Events

Intercept UI button clicks from the default call interface to add custom behavior or analytics.

class CallViewController: UIViewController, ButtonClickListener {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        CallSession.shared.addButtonClickListener(self)
    }
    
    deinit {
        CallSession.shared.removeButtonClickListener(self)
    }
    
    func onLeaveSessionButtonClicked() {
        // Leave button tapped
    }

    func onToggleAudioButtonClicked() {
        // Mute/unmute button tapped
    }

    func onToggleVideoButtonClicked() {
        // Video on/off button tapped
    }

    func onSwitchCameraButtonClicked() {}
    func onRaiseHandButtonClicked() {}
    func onShareInviteButtonClicked() {}
    func onChangeLayoutButtonClicked() {}
    func onParticipantListButtonClicked() {}
    func onChatButtonClicked() {}
    func onRecordingToggleButtonClicked() {}
}

Event	Description
`onLeaveSessionButtonClicked`	Leave/end call button was tapped
`onToggleAudioButtonClicked`	Mute/unmute button was tapped
`onToggleVideoButtonClicked`	Video on/off button was tapped
`onSwitchCameraButtonClicked`	Camera switch button was tapped
`onRaiseHandButtonClicked`	Raise hand button was tapped
`onShareInviteButtonClicked`	Share/invite button was tapped
`onChangeLayoutButtonClicked`	Layout change button was tapped
`onParticipantListButtonClicked`	Participant list button was tapped
`onChatButtonClicked`	In-call chat button was tapped
`onRecordingToggleButtonClicked`	Recording toggle button was tapped

Button click events fire before the SDK’s default action executes. Use these to add custom logic alongside default behavior. The Leave button is the exception: the SDK leaves the session itself when it is tapped, so only clean up in onLeaveSessionButtonClicked.

Layout Events

Monitor layout changes including layout type switches and Picture-in-Picture mode transitions.

class CallViewController: UIViewController, LayoutListener {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        CallSession.shared.addLayoutListener(self)
    }
    
    deinit {
        CallSession.shared.removeLayoutListener(self)
    }
    
    func onCallLayoutChanged(layoutType: LayoutType) {
        // Layout changed (TILE, SPOTLIGHT)
    }

    func onParticipantListVisible() {
        // Participant list panel opened
    }

    func onParticipantListHidden() {
        // Participant list panel closed
    }

    func onPictureInPictureLayoutEnabled() {
        // Entered PiP mode
    }

    func onPictureInPictureLayoutDisabled() {
        // Exited PiP mode
    }
}

Event	Parameter	Description
`onCallLayoutChanged`	`LayoutType`	Call layout changed
`onParticipantListVisible`	-	Participant list panel was opened
`onParticipantListHidden`	-	Participant list panel was closed
`onPictureInPictureLayoutEnabled`	-	Call entered Picture-in-Picture mode
`onPictureInPictureLayoutDisabled`	-	Call exited Picture-in-Picture mode

LayoutType Values

Value	Description	Best For
`.tile`	Grid layout with equally-sized tiles	Group discussions, team meetings
`.spotlight`	Large view for active speaker, small tiles for others	Presentations, one-on-one calls

Clear All Listeners

Remove all registered listeners at once. Useful when cleaning up resources.

CallSession.shared.clearAllListeners()

Incoming Call Events

CometChatCalls.addIncomingCallListener is a global listener, not tied to a session. It reports a call ringing on this device and the end of that ring, whether the call arrived by VoIP push while the app was killed or while it was running. The Push Notifications SDK feeds it; it reports incoming calls only, not the end of your own outgoing call.

final class CallEvents: NSObject, CometChatIncomingCallListener {
    func onIncomingCallReceived(call: CometChatIncomingCall) {
        // A call for this user is ringing (CallKit already shows it)
    }

    func onIncomingCallEnded(call: CometChatIncomingCall, reason: String) {
        // The ring ended: "cancelled", "ongoing", "unanswered", "rejected", "busy", "ended"
    }
}

let callEvents = CallEvents()   // held weakly by the SDK: keep this reference
CometChatCalls.addIncomingCallListener("my-screen", callEvents)

CometChatCalls.removeIncomingCallListener("my-screen")

Event	Parameters	Description
`onIncomingCallReceived`	`CometChatIncomingCall`	A call for the logged-in user is ringing on this device
`onIncomingCallEnded`	`CometChatIncomingCall`, `reason`	The call ended before it was answered here, once per call: `cancelled` (the caller gave up), `ongoing` (answered on another device), `unanswered`, `rejected` / `busy`, or `ended` (the session prepared for it closed before the answer). Treat any other reason as “the ring is over”. A decline or ring-out on this device is reported to the Push SDK delegate’s `callDidEnd(_:reason:)` instead

CometChatIncomingCall carries sessionId, callerUid, callerName, callerAvatarUrl, callType, receiverType, receiverUid, conversationId, initiatedAt (milliseconds), isVideo and isPeerCall.

Listener ids are keys: registering the same id twice replaces the earlier listener. Do not use the id cometchat-push-notifications, which the Push SDK registers under.

CometChatCalls.addLoginListener reports the Calls SDK login state. The Push SDK uses it to register and unregister the push tokens and to stop a ring when the user logs out; your app can use it to gate call UI.

import CometChatCallsSDK

// Qualify the protocol if your app also imports the Chat SDK, which has its own CometChatLoginDelegate.
final class CallsLoginEvents: NSObject, CometChatCallsSDK.CometChatLoginDelegate {
    func onLoginSuccess(user: CallsUser) {}
    func onLoginFailed(error: CometChatCallException?) {}
    func onLogoutSuccess() {}
    func onLogoutFailed(error: CometChatCallException?) {}
}

let loginEvents = CallsLoginEvents()   // held weakly by the SDK: keep this reference
CometChatCalls.addLoginListener("my-app", loginEvents)

CometChatCalls.removeLoginListener("my-app")

Event	Description
`onLoginSuccess(user:)`	A user logged in to the Calls SDK
`onLoginFailed(error:)`	A login failed
`onLogoutSuccess()`	The user logged out
`onLogoutFailed(error:)`	A logout failed

Login listener ids are keys too: registering the same id twice replaces the earlier listener. Do not use the id cometchat-push-notifications-calls, which the Push SDK registers under.

Overview

Getting Started

Call Session

Features

Advanced

Migration Guide

Resources

Get CallSession Instance

Session Events

Participant Events

Media Events

Button Click Events

Layout Events

Clear All Listeners

Incoming Call Events

​Get CallSession Instance

​Session Events

​Participant Events

​Media Events

​Button Click Events

​Layout Events

​Clear All Listeners

​Incoming Call Events

​Login Events

Get CallSession Instance

Session Events

Participant Events

Media Events

Button Click Events

Layout Events

Clear All Listeners

Incoming Call Events

Login Events