Events

Handle CometChat Calls SDK v5 events on iOS for call lifecycle, participants, media state, errors, and real-time updates.

Handle call session events to build responsive UIs. The SDK provides five event listener protocols to monitor session status, participant activities, media changes, button clicks, and layout changes.

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.

Swift

let callSession = CallSession.shared

Objective-C

CallSession *callSession = [CallSession shared];

Remember to remove listeners when your view controller is deallocated to prevent memory leaks. Use removeSessionStatusListener, removeParticipantEventListener, etc.

---

Session Events

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

Swift

class CallViewController: UIViewController, SessionStatusListener {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        CallSession.shared.addSessionStatusListener(self)
    }
    
    deinit {
        CallSession.shared.removeSessionStatusListener(self)
    }
    
    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
        navigationController?.popViewController(animated: true)
    }
}

Objective-C

@interface CallViewController () <SessionStatusListener>
@end

@implementation CallViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    [[CallSession shared] addSessionStatusListener:self];
}

- (void)dealloc {
    [[CallSession shared] removeSessionStatusListener:self];
}

- (void)onSessionJoined {
    // Successfully connected to the session
}

- (void)onSessionLeft {
    // Left the session
    [self.navigationController popViewControllerAnimated:YES];
}

- (void)onSessionTimedOut {
    // Session ended due to inactivity
    [self.navigationController popViewControllerAnimated:YES];
}

- (void)onConnectionLost {
    // Network interrupted, attempting reconnection
}

- (void)onConnectionRestored {
    // Connection restored after being lost
}

- (void)onConnectionClosed {
    // Connection permanently closed
    [self.navigationController popViewControllerAnimated:YES];
}

@end

Event	Description
onSessionJoined()	Successfully connected and joined the session
onSessionLeft()	Left the session via leaveSession() or was removed
onSessionTimedOut()	Session ended due to inactivity timeout
onConnectionLost()	Network interrupted, SDK attempting reconnection
onConnectionRestored()	Connection restored after being lost
onConnectionClosed()	Connection permanently closed, cannot reconnect

---

Participant Events

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

Swift

class CallViewController: UIViewController, ParticipantEventListener {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        CallSession.shared.addParticipantEventListener(self)
    }
    
    deinit {
        CallSession.shared.removeParticipantEventListener(self)
    }
    
    func onParticipantJoined(participant: Participant) {
        // A participant joined the call
    }

    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) {}
}

Objective-C

@interface CallViewController () <ParticipantEventListener>
@end

@implementation CallViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    [[CallSession shared] addParticipantEventListener:self];
}

- (void)dealloc {
    [[CallSession shared] removeParticipantEventListener:self];
}

- (void)onParticipantJoinedWithParticipant:(Participant *)participant {
    // A participant joined the call
}

- (void)onParticipantLeftWithParticipant:(Participant *)participant {
    // A participant left the call
}

- (void)onParticipantListChangedWithParticipants:(NSArray<Participant *> *)participants {
    // Participant list updated
}

// Other callbacks...

@end

Event	Parameter	Description
onParticipantJoined	Participant	A participant connected to the call
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.

Swift

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 onScreenShareStarted() {}
    func onScreenShareStopped() {}

    func onAudioModeChanged(audioModeType: AudioModeType) {
        // Audio output device changed
    }

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

Objective-C

@interface CallViewController () <MediaEventsListener>
@end

@implementation CallViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    [[CallSession shared] addMediaEventsListener:self];
}

- (void)dealloc {
    [[CallSession shared] removeMediaEventsListener:self];
}

- (void)onAudioMuted {
    // Your microphone was muted
}

- (void)onAudioUnMuted {
    // Your microphone was unmuted
}

- (void)onVideoPaused {
    // Your camera was turned off
}

- (void)onVideoResumed {
    // Your camera was turned on
}

- (void)onRecordingStarted {
    // Call recording started
}

- (void)onRecordingStopped {
    // Call recording stopped
}

- (void)onAudioModeChangedWithAudioModeType:(AudioModeType)audioModeType {
    // Audio output device changed
}

- (void)onCameraFacingChangedWithCameraFacing:(CameraFacing)cameraFacing {
    // Camera switched between front and back
}

// Other callbacks...

@end

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
onScreenShareStarted	-	You started screen sharing
onScreenShareStopped	-	You stopped screen sharing
onAudioModeChanged	AudioModeType	Audio output device changed
onCameraFacingChanged	CameraFacing	Camera switched between front and back

AudioModeType 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
.BACK	Rear-facing (main) camera is active

---

Button Click Events

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

Swift

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() {}
}

Objective-C

@interface CallViewController () <ButtonClickListener>
@end

@implementation CallViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    [[CallSession shared] addButtonClickListener:self];
}

- (void)dealloc {
    [[CallSession shared] removeButtonClickListener:self];
}

- (void)onLeaveSessionButtonClicked {
    // Leave button tapped
}

- (void)onToggleAudioButtonClicked {
    // Mute/unmute button tapped
}

- (void)onToggleVideoButtonClicked {
    // Video on/off button tapped
}

// Other callbacks...

@end

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.

---

Layout Events

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

Swift

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
    }
}

Objective-C

@interface CallViewController () <LayoutListener>
@end

@implementation CallViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    [[CallSession shared] addLayoutListener:self];
}

- (void)dealloc {
    [[CallSession shared] removeLayoutListener:self];
}

- (void)onCallLayoutChangedWithLayoutType:(LayoutType)layoutType {
    // Layout changed (TILE, SPOTLIGHT)
}

- (void)onParticipantListVisible {
    // Participant list panel opened
}

- (void)onParticipantListHidden {
    // Participant list panel closed
}

- (void)onPictureInPictureLayoutEnabled {
    // Entered PiP mode
}

- (void)onPictureInPictureLayoutDisabled {
    // Exited PiP mode
}

@end

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.

Swift

CallSession.shared.clearAllListeners()

Objective-C

[[CallSession shared] clearAllListeners];