Ringing - CometChat Docs

Quick Reference for AI Agents & Developers

// Initiate call
val call = Call("UID", CometChatConstants.RECEIVER_TYPE_USER, CometChatConstants.CALL_TYPE_VIDEO)
CometChat.initiateCall(call, object : CometChat.CallbackListener<Call>() {
    override fun onSuccess(call: Call) { /* Show outgoing UI */ }
    override fun onError(e: CometChatException) { }
})

// Accept call
CometChat.acceptCall(sessionID, object : CometChat.CallbackListener<Call>() {
    override fun onSuccess(call: Call) { /* Start session */ }
    override fun onError(e: CometChatException) { }
})

// Reject/Cancel call
CometChat.rejectCall(sessionID, CometChatConstants.CALL_STATUS_REJECTED, callback)

Available via: SDK | UI Kits

Overview

This section explains how to implement a complete calling workflow with ringing functionality, including incoming/outgoing call UI, call acceptance, rejection, and cancellation. Previously known as Default Calling.

After the call is accepted, you need to start the call session. See the Call Session guide for details on starting and managing the actual call.

Call Flow:

Caller initiates a call using initiateCall()
Receiver gets notified via onIncomingCallReceived() callback
Receiver can either:
- Accept the call using acceptCall()
- Reject the call using rejectCall() with status CALL_STATUS_REJECTED
Caller can cancel the call using rejectCall() with status CALL_STATUS_CANCELLED
Once accepted, both participants call startSession() to join the call

Initiate Call

The initiateCall() method sends a call request to a user or a group. On success, the receiver gets an onIncomingCallReceived() callback.

Java (User)
Kotlin (User)
Java (Group)
Kotlin (Group)

String receiverID = "UID";
String receiverType = CometChatConstants.RECEIVER_TYPE_USER;
String callType = CometChatConstants.CALL_TYPE_VIDEO;

Call call = new Call(receiverID, receiverType, callType);

CometChat.initiateCall(call, new CometChat.CallbackListener<Call>() {
    @Override
    public void onSuccess(Call call) {
        // Call initiated, show outgoing call UI
        // Store call.getSessionId() for later use
    }

    @Override
    public void onError(CometChatException e) {
        Log.e(TAG, "Call initiation failed: " + e.getMessage());
    }
});

val receiverID = "UID"
val receiverType = CometChatConstants.RECEIVER_TYPE_USER
val callType = CometChatConstants.CALL_TYPE_VIDEO

val call = Call(receiverID, receiverType, callType)

CometChat.initiateCall(call, object : CometChat.CallbackListener<Call>() {
    override fun onSuccess(call: Call) {
        // Call initiated, show outgoing call UI
        // Store call.sessionId for later use
    }

    override fun onError(e: CometChatException) {
        Log.e(TAG, "Call initiation failed: ${e.message}")
    }
})

String receiverID = "GUID";
String receiverType = CometChatConstants.RECEIVER_TYPE_GROUP;
String callType = CometChatConstants.CALL_TYPE_VIDEO;

Call call = new Call(receiverID, receiverType, callType);

CometChat.initiateCall(call, new CometChat.CallbackListener<Call>() {
    @Override
    public void onSuccess(Call call) {
        // Call initiated, show outgoing call UI
    }

    @Override
    public void onError(CometChatException e) {
        Log.e(TAG, "Call initiation failed: " + e.getMessage());
    }
});

val receiverID = "GUID"
val receiverType = CometChatConstants.RECEIVER_TYPE_GROUP
val callType = CometChatConstants.CALL_TYPE_VIDEO

val call = Call(receiverID, receiverType, callType)

CometChat.initiateCall(call, object : CometChat.CallbackListener<Call>() {
    override fun onSuccess(call: Call) {
        // Call initiated, show outgoing call UI
    }

    override fun onError(e: CometChatException) {
        Log.e(TAG, "Call initiation failed: ${e.message}")
    }
})

Parameter	Description
`receiverID`	The UID or GUID of the recipient
`receiverType`	The type of the receiver: `CometChatConstants.RECEIVER_TYPE_USER` or `CometChatConstants.RECEIVER_TYPE_GROUP`
`callType`	The type of the call: `CometChatConstants.CALL_TYPE_AUDIO` or `CometChatConstants.CALL_TYPE_VIDEO`

On success, a Call object is returned containing the call details including a unique sessionId required for starting the call session.

Call Listeners

Register the CallListener to receive real-time call events. Each listener requires a unique listenerId string to prevent duplicate registrations and enable targeted removal.

Java
Kotlin

private String listenerId = "UNIQUE_LISTENER_ID";

// Register listener (e.g., in onCreate or onResume)
CometChat.addCallListener(listenerId, new CometChat.CallListener() {
    @Override
    public void onIncomingCallReceived(Call call) {
        // Show incoming call UI
    }

    @Override
    public void onOutgoingCallAccepted(Call call) {
        // Receiver accepted, start the call session
    }

    @Override
    public void onOutgoingCallRejected(Call call) {
        // Receiver rejected, dismiss outgoing call UI
    }

    @Override
    public void onIncomingCallCancelled(Call call) {
        // Caller cancelled, dismiss incoming call UI
    }

    @Override
    public void onCallEndedMessageReceived(Call call) {
        // Call ended by remote participant
    }
});

// Unregister listener (e.g., in onDestroy or onPause)
CometChat.removeCallListener(listenerId);

val listenerId = "UNIQUE_LISTENER_ID"

// Register listener (e.g., in onCreate or onResume)
CometChat.addCallListener(listenerId, object : CometChat.CallListener() {
    override fun onIncomingCallReceived(call: Call) {
        // Show incoming call UI
    }

    override fun onOutgoingCallAccepted(call: Call) {
        // Receiver accepted, start the call session
    }

    override fun onOutgoingCallRejected(call: Call) {
        // Receiver rejected, dismiss outgoing call UI
    }

    override fun onIncomingCallCancelled(call: Call) {
        // Caller cancelled, dismiss incoming call UI
    }

    override fun onCallEndedMessageReceived(call: Call) {
        // Call ended by remote participant
    }
})

// Unregister listener (e.g., in onDestroy or onPause)
CometChat.removeCallListener(listenerId)

Always remove call listeners when they’re no longer needed (e.g., in onDestroy() or when navigating away). Failing to remove listeners can cause memory leaks and duplicate event handling.

Events

Event	Description
`onIncomingCallReceived(call: Call)`	Invoked when an incoming call is received. The `call` contains caller details, session ID, and call type. Display incoming call UI here.
`onOutgoingCallAccepted(call: Call)`	Invoked on the caller’s device when the receiver accepts. Generate call token and start the session here.
`onOutgoingCallRejected(call: Call)`	Invoked on the caller’s device when the receiver rejects the call. Dismiss outgoing call UI here.
`onIncomingCallCancelled(call: Call)`	Invoked on the receiver’s device when the caller cancels before answering. Dismiss incoming call UI here.
`onCallEndedMessageReceived(call: Call)`	Invoked when a call ends. The `call` contains final status and duration. Update call history here.

Accept Call

When an incoming call is received via onIncomingCallReceived(), use acceptCall() to accept it. On success, start the call session.

Java
Kotlin

String sessionID = call.getSessionId(); // From onIncomingCallReceived

CometChat.acceptCall(sessionID, new CometChat.CallbackListener<Call>() {
    @Override
    public void onSuccess(Call call) {
        // Call accepted, now start the call session
        // Generate token and call startSession()
    }

    @Override
    public void onError(CometChatException e) {
        Log.e(TAG, "Accept call failed: " + e.getMessage());
    }
});

val sessionID = call.sessionId // From onIncomingCallReceived

CometChat.acceptCall(sessionID, object : CometChat.CallbackListener<Call>() {
    override fun onSuccess(call: Call) {
        // Call accepted, now start the call session
        // Generate token and call startSession()
    }

    override fun onError(e: CometChatException) {
        Log.e(TAG, "Accept call failed: ${e.message}")
    }
})

Reject Call

Use rejectCall() to reject an incoming call. Set the status to CALL_STATUS_REJECTED.

Java
Kotlin

String sessionID = call.getSessionId();
String status = CometChatConstants.CALL_STATUS_REJECTED;

CometChat.rejectCall(sessionID, status, new CometChat.CallbackListener<Call>() {
    @Override
    public void onSuccess(Call call) {
        // Call rejected, dismiss incoming call UI
    }

    @Override
    public void onError(CometChatException e) {
        Log.e(TAG, "Reject call failed: " + e.getMessage());
    }
});

val sessionID = call.sessionId
val status = CometChatConstants.CALL_STATUS_REJECTED

CometChat.rejectCall(sessionID, status, object : CometChat.CallbackListener<Call>() {
    override fun onSuccess(call: Call) {
        // Call rejected, dismiss incoming call UI
    }

    override fun onError(e: CometChatException) {
        Log.e(TAG, "Reject call failed: ${e.message}")
    }
})

Cancel Call

The caller can cancel an outgoing call before it’s answered using rejectCall() with status CALL_STATUS_CANCELLED.

Java
Kotlin

String sessionID = call.getSessionId();
String status = CometChatConstants.CALL_STATUS_CANCELLED;

CometChat.rejectCall(sessionID, status, new CometChat.CallbackListener<Call>() {
    @Override
    public void onSuccess(Call call) {
        // Call cancelled, dismiss outgoing call UI
    }

    @Override
    public void onError(CometChatException e) {
        Log.e(TAG, "Cancel call failed: " + e.getMessage());
    }
});

val sessionID = call.sessionId
val status = CometChatConstants.CALL_STATUS_CANCELLED

CometChat.rejectCall(sessionID, status, object : CometChat.CallbackListener<Call>() {
    override fun onSuccess(call: Call) {
        // Call cancelled, dismiss outgoing call UI
    }

    override fun onError(e: CometChatException) {
        Log.e(TAG, "Cancel call failed: ${e.message}")
    }
})

Start Call Session

Once the call is accepted, both participants need to start the call session. Caller flow: In the onOutgoingCallAccepted() callback, generate a token and start the session. Receiver flow: In the acceptCall() success callback, generate a token and start the session.

Java
Kotlin

String sessionId = call.getSessionId();
String userAuthToken = CometChat.getUserAuthToken();

// Step 1: Generate call token
CometChatCalls.generateToken(sessionId, userAuthToken, new CometChatCalls.CallbackListener<GenerateToken>() {
    @Override
    public void onSuccess(GenerateToken token) {
        // Step 2: Start the call session
        RelativeLayout videoContainer = findViewById(R.id.video_container);
        
        CallSettings callSettings = new CometChatCalls.CallSettingsBuilder(activity, videoContainer)
            .setDefaultLayoutEnable(true)
            .setIsAudioOnly(false)
            .build();

        CometChatCalls.startSession(token, callSettings, new CometChatCalls.CallbackListener<String>() {
            @Override
            public void onSuccess(String s) {
                // Call session started
            }

            @Override
            public void onError(CometChatException e) {
                Log.e(TAG, "Start session failed: " + e.getMessage());
            }
        });
    }

    @Override
    public void onError(CometChatException e) {
        Log.e(TAG, "Token generation failed: " + e.getMessage());
    }
});

val sessionId = call.sessionId
val userAuthToken = CometChat.getUserAuthToken()

// Step 1: Generate call token
CometChatCalls.generateToken(sessionId, userAuthToken, object : CometChatCalls.CallbackListener<GenerateToken>() {
    override fun onSuccess(token: GenerateToken) {
        // Step 2: Start the call session
        val videoContainer: RelativeLayout = findViewById(R.id.video_container)
        
        val callSettings = CometChatCalls.CallSettingsBuilder(activity, videoContainer)
            .setDefaultLayoutEnable(true)
            .setIsAudioOnly(false)
            .build()

        CometChatCalls.startSession(token, callSettings, object : CometChatCalls.CallbackListener<String> {
            override fun onSuccess(s: String) {
                // Call session started
            }

            override fun onError(e: CometChatException) {
                Log.e(TAG, "Start session failed: ${e.message}")
            }
        })
    }

    override fun onError(e: CometChatException) {
        Log.e(TAG, "Token generation failed: ${e.message}")
    }
})

For more details on call settings and customization, see the Call Session guide.

End Call

To end an active call in the ringing flow, the process differs based on who ends the call. User who ends the call: When the user presses the end call button, the onCallEndButtonPressed() callback is triggered. Inside this callback, call CometChat.endCall() to notify other participants. On success, call CometChat.clearActiveCall() and CometChatCalls.endSession() to release resources.

Java
Kotlin

@Override
public void onCallEndButtonPressed() {
    CometChat.endCall(sessionId, new CometChat.CallbackListener<Call>() {
        @Override
        public void onSuccess(Call call) {
            CometChat.clearActiveCall();
            CometChatCalls.endSession();
            // Close the calling screen
        }

        @Override
        public void onError(CometChatException e) {
            Log.e(TAG, "End call failed: " + e.getMessage());
        }
    });
}

override fun onCallEndButtonPressed() {
    CometChat.endCall(sessionId, object : CometChat.CallbackListener<Call>() {
        override fun onSuccess(call: Call) {
            CometChat.clearActiveCall()
            CometChatCalls.endSession()
            // Close the calling screen
        }

        override fun onError(e: CometChatException) {
            Log.e(TAG, "End call failed: ${e.message}")
        }
    })
}

Remote participant (receives onCallEnded() callback):

Java
Kotlin

@Override
public void onCallEnded() {
    CometChat.clearActiveCall();
    CometChatCalls.endSession();
    // Close the calling screen
}

override fun onCallEnded() {
    CometChat.clearActiveCall()
    CometChatCalls.endSession()
    // Close the calling screen
}

For more details, see the End Call Session guide.

Busy Call Handling

If the receiver is already on another call, you can reject the incoming call with CALL_STATUS_BUSY status.

Java
Kotlin

String sessionID = call.getSessionId();
String status = CometChatConstants.CALL_STATUS_BUSY;

CometChat.rejectCall(sessionID, status, new CometChat.CallbackListener<Call>() {
    @Override
    public void onSuccess(Call call) {
        // Busy status sent to caller
    }

    @Override
    public void onError(CometChatException e) {
        Log.e(TAG, "Busy rejection failed: " + e.getMessage());
    }
});

val sessionID = call.sessionId
val status = CometChatConstants.CALL_STATUS_BUSY

CometChat.rejectCall(sessionID, status, object : CometChat.CallbackListener<Call>() {
    override fun onSuccess(call: Call) {
        // Busy status sent to caller
    }

    override fun onError(e: CometChatException) {
        Log.e(TAG, "Busy rejection failed: ${e.message}")
    }
})

Best Practices

Always Remove Call Listeners

Remove call listeners in onDestroy() or onPause() to prevent memory leaks and duplicate callbacks. Use unique listener IDs to manage multiple listeners effectively.

Handle All Call States

Implement all call listener callbacks (onIncomingCallReceived, onOutgoingCallAccepted, onOutgoingCallRejected, onIncomingCallCancelled) to provide a complete user experience and handle edge cases.

Store Session ID

Store the sessionId from the Call object after initiating a call. You’ll need it for accepting, rejecting, canceling, and ending the call.

Show Appropriate UI States

Display different UI for incoming calls (accept/reject buttons), outgoing calls (cancel button), and active calls (end call button) to match user expectations.

Troubleshooting

Call Initiation Failed

Symptom: initiateCall() fails with “User not logged in” or “Invalid receiver” error.Cause: User not logged in or invalid receiver UID/GUID.Solution: Ensure CometChat.login() is called successfully before initiating calls. Verify the receiver UID or GUID exists using CometChat.getUser() or CometChat.getGroup().

Listener Not Receiving Events

Symptom: Call listener callbacks are not triggered when calls are received or accepted.Cause: Listener not registered or removed prematurely.Solution: Register the call listener in onCreate() or onResume() and ensure it’s not removed until onDestroy() or onPause(). Verify the listener ID is unique.

Call Session Won't Start

Symptom: After accepting a call, the call session doesn’t start or shows a black screen.Cause: Missing token generation or incorrect call settings.Solution: Ensure you call generateToken() and startSession() in the acceptCall() success callback. Verify the video container layout exists in your XML. See Call Session for details.

Next Steps

Call Session

Start and manage call sessions with video and audio controls

Call Logs

Retrieve and display call history for users and groups

Recording

Record calls and access recordings from the Dashboard

Calling Setup

Configure calling dependencies and initialization

​Overview

​Initiate Call

​Call Listeners

​Events

​Accept Call

​Reject Call

​Cancel Call

​Start Call Session

​End Call

​Busy Call Handling

​Best Practices

​Troubleshooting

​Next Steps

Call Session

Call Logs

Recording

Calling Setup

Overview

Initiate Call

Call Listeners

Events

Accept Call

Reject Call

Cancel Call

Start Call Session

End Call

Busy Call Handling

Best Practices

Troubleshooting

Next Steps