AI Integration Quick Reference
AI Integration Quick Reference
| Issue | Fix |
|---|---|
init() fails | Verify App ID and Region from Dashboard |
| Login fails with “UID not found” | Create user via Dashboard or REST API first |
| SDK methods fail | Ensure init() completes before calling other methods |
| No real-time events | Check WebSocket connection, verify listeners registered |
| Build fails | Check Gradle dependency version and repository URL |
Initialization & Authentication
| Symptom | Cause | Fix |
|---|---|---|
init() fails with “App ID not found” | Invalid App ID or Region | Verify credentials in Dashboard → API & Auth Keys |
init() fails silently | Missing credentials | Double-check App ID and Region are non-null strings |
| ”CometChat not initialized” | init() not awaited | Ensure init() callback’s onSuccess fires before calling other methods |
| Login fails with “UID not found” | User doesn’t exist | Create user via Dashboard or REST API |
| Login fails with “Auth Key is not valid” | Wrong Auth Key | Verify Auth Key in Dashboard. Don’t confuse with REST API Key |
getLoggedInUser() returns null | Session cleared or init() not called | Call init() on every app start before checking session |
| Auth Token expired | Token lifetime exceeded | Generate new token via REST API |
| User appears offline after login | Presence not configured | Use subscribePresenceForAllUsers() in AppSettingsBuilder |
Gradle & Build Issues
| Symptom | Cause | Fix |
|---|---|---|
Could not resolve com.cometchat:chat-sdk-android | Missing repository | Add https://dl.cloudsmith.io/public/cometchat/cometchat/maven/ to your project-level build.gradle repositories block |
| Duplicate class errors at compile time | Multiple versions of a dependency | Run ./gradlew dependencies to find conflicts. Use exclude group: or force a single version |
Manifest merger failed | Conflicting minSdkVersion | Set minSdkVersion to at least 21 (24 if using the Calls SDK) in your app-level build.gradle |
Java 8 features not supported | Missing compile options | Add compileOptions { sourceCompatibility JavaVersion.VERSION_1_8; targetCompatibility JavaVersion.VERSION_1_8 } to your android block |
| Build succeeds but crashes on launch | AndroidX not enabled | Add android.useAndroidX=true and android.enableJetifier=true to gradle.properties |
| Calls SDK not found | Not added to Gradle | Add implementation 'com.cometchat:calls-sdk-android:4.x.x' to your app-level build.gradle |
Permissions
| Symptom | Cause | Fix |
|---|---|---|
| App crashes when sending media | Missing storage permission | Request READ_EXTERNAL_STORAGE / READ_MEDIA_IMAGES at runtime before file access |
| No audio in calls | RECORD_AUDIO not granted | Request RECORD_AUDIO permission before initiating or joining a call |
| No video in calls | CAMERA not granted | Request CAMERA permission before initiating or joining a video call |
| Permission dialog never appears | Permission not declared in manifest | Add the required <uses-permission> tags to AndroidManifest.xml |
| Permission permanently denied | User selected “Don’t ask again” | Use shouldShowRequestPermissionRationale() to detect this and direct the user to app settings |
ProGuard & Release Builds
| Symptom | Cause | Fix |
|---|---|---|
| App works in debug but crashes in release | ProGuard stripping SDK classes | Add CometChat ProGuard rules (see below) to your proguard-rules.pro |
ClassNotFoundException in release build | Obfuscation removing required class | Ensure -keep class com.cometchat.** rules are applied |
| JSON parsing errors in release | Model class fields renamed by ProGuard | Add -keepclassmembers rules for SDK model classes |
| Calls SDK crashes in release | Calls SDK classes obfuscated | Add -keep class com.cometchat.calls.** to your ProGuard rules |
proguard-rules.pro:
Messaging
| Symptom | Cause | Fix |
|---|---|---|
sendMessage() fails | Not logged in or invalid receiver | Ensure login() completes. Verify receiver UID/GUID exists |
| Messages sent but not received | Listener not registered | Register addMessageListener() with onTextMessageReceived |
| Duplicate messages | Multiple listeners with same ID | Use unique listener IDs. Remove old listeners before re-registering |
| Wrong conversation | Wrong receiver type | Use CometChatConstants.RECEIVER_TYPE_USER for 1:1, RECEIVER_TYPE_GROUP for groups |
| Media upload fails | File too large or unsupported | Check limits. Supported: PNG, JPG, GIF, MP4, MP3, WAV |
| Metadata not appearing | Set after send | Call setMetadata() before the send method |
| Pagination not working | New request object | Reuse the same MessagesRequest for fetchPrevious()/fetchNext() |
| Thread replies in main chat | Missing filter | Add .hideReplies(true) to MessagesRequestBuilder |
| Deleted messages showing | Missing filter | Add .hideDeletedMessages(true) |
Groups
| Symptom | Cause | Fix |
|---|---|---|
| Cannot join group | Invalid GUID | Verify GUID. Create group first if needed |
| Cannot send to group | Not a member | Join group first with joinGroup() |
| Cannot kick/ban members | Insufficient scope | Only admins and moderators can kick/ban |
| Can’t join private group | Requires invite | Private groups require an admin to add you |
| Owner can’t leave | Ownership not transferred | Call transferGroupOwnership() first |
| Password join fails | Wrong password | Pass correct password as the third parameter |
fetchNext() returns same results | New request object | Reuse the same GroupsRequest instance |
| Scope filter returns nothing | Invalid strings | Use "admin", "moderator", "participant" |
| Cannot demote admin | Not owner | Only the group owner can demote admins |
| Kicked user can still see group | Kick vs ban | Use banGroupMember() to prevent rejoining |
Calling
| Symptom | Cause | Fix |
|---|---|---|
| Calls SDK not found | Not added to Gradle | Add implementation 'com.cometchat:calls-sdk-android:4.x.x' |
| No audio/video | Permissions denied | Request CAMERA and RECORD_AUDIO permissions at runtime before the call |
| Call not connecting | Session ID mismatch | Verify both participants use the same session ID |
| One-way audio | Firewall blocking WebRTC | Check network config. Corporate networks may block WebRTC ports |
| Incoming call not showing | Listener not registered | Register addCallListener() at the Application or root Activity level |
| Call ended event not received | Wrong callback | Use onCallEndedMessageReceived in CallListener for call-end messages, onCallEnded in OngoingCallListener for session events |
| Black screen after joining | View not visible or sized | Ensure the call container View has non-zero dimensions and is visible |
| Calls crash in release build | ProGuard stripping classes | Add -keep class com.cometchat.calls.** { *; } to proguard-rules.pro |
WebSocket & Connection
| Symptom | Cause | Fix |
|---|---|---|
| Real-time events not received | WebSocket disconnected | Check getConnectionStatus(). Reconnect if needed |
| WebSocket fails | Firewall blocking | Check network config. Corporate firewalls may block WebSocket connections |
| Connection drops frequently | Network instability | Use addConnectionListener() to monitor and reconnect |
| Stuck in “connecting” | Network or config issue | Verify network, appId, and region |
featureThrottled status | Feature rate-limited | Reduce frequency of the throttled feature. Listen for onFeatureThrottled in ConnectionListener |
| No events after login | Auto-connect disabled | Call CometChat.connect() manually if autoEstablishSocketConnection(false) |
connect() doesn’t work | Not logged in | Ensure user is logged in first |
Listeners & Lifecycle
| Symptom | Cause | Fix |
|---|---|---|
| Events not firing | Registered before init | Register after init() and login() complete |
| Duplicate events | Multiple listeners with same ID | Remove old listeners before adding new ones |
| Missing events after navigation | Listeners removed on onPause() | Re-register in onResume() when the screen becomes active |
| Events fire after screen is closed | Listeners not removed | Remove listeners in onPause() or onDestroy() |
| Receipt events not triggering | Receipts not sent | Call markAsDelivered()/markAsRead() explicitly |
| Memory leaks | Listeners holding Activity reference | Always remove listeners in onDestroy() |
Typing, Receipts & Reactions
| Symptom | Cause | Fix |
|---|---|---|
| Typing indicator stuck | endTyping() not called | Call on send, focus loss, or after 3–5s timeout using a Handler |
| Double-tick not showing | markAsDelivered() not called | Call on message fetch and real-time receive |
| Group receipts missing | Feature not enabled | Enable “Enhanced Messaging Status” in Dashboard |
onMessagesDeliveredToAll/onMessagesReadByAll not firing | Not registered | Register these callbacks in MessageListener for group-level receipt events |
| Reaction not appearing | UI not synced | Call updateMessageWithReactionInfo() on events |
| Duplicate reactions | No check before adding | Use getReactedByMe() first |
AI Features
| Symptom | Cause | Fix |
|---|---|---|
| AI features not appearing | Not enabled | Enable in Dashboard → AI Features |
| AI Agents not responding | Not configured | Configure Agent in Dashboard. Agents only respond to text |
onAIAssistantEventReceived not firing | Listener not registered | Register AIAssistantListener after login |
| Moderation always PENDING | Rules not configured | Configure rules in Dashboard → Moderation → Rules |
| Agentic messages not arriving | Wrong listener | Use MessageListener with onAIAssistantMessageReceived |
Upgrading from V3
| Symptom | Cause | Fix |
|---|---|---|
| Build fails after upgrade | Old artifact still in Gradle | Replace com.cometchat:chat-sdk-android:3.x.x with com.cometchat:chat-sdk-android:4.x.x |
| Calls SDK not working | Wrong artifact version | Use com.cometchat:calls-sdk-android:4.x.x |
| Both versions installed | Gradle conflict | Remove the v3 dependency and sync project |
Error Codes
For the complete SDK error code reference, see Error Codes. Common errors you’ll encounter:| Code | Description | Resolution |
|---|---|---|
ERR_UID_NOT_FOUND | User doesn’t exist | Create user via Dashboard or REST API |
AUTH_ERR_AUTH_TOKEN_NOT_FOUND | Invalid or expired auth token | Generate new token via REST API |
MISSING_PARAMETERS | Required parameter not provided | Check method signature and pass all required params |
NOT_INITIALIZED | init() not called | Call CometChat.init() before any other method |
USER_NOT_LOGGED_IN | No active session | Call login() first |
ERR_GUID_NOT_FOUND | Group doesn’t exist | Create group or verify GUID |
ERR_NOT_A_MEMBER | Not a group member | Join group first |
TOO_MANY_REQUEST | Rate limit exceeded | See Rate Limits |
FAILED_TO_FETCH | Network issue | Check internet connection and API endpoint |
NO_WEBSOCKET_CONNECTION | WebSocket disconnected | Check connection status, wait for reconnect |
Next Steps
Setup SDK
Installation and initialization guide
Best Practices
Recommended patterns and practices
Error Codes
Complete SDK error code reference
AI Integration
AI Agents, Moderation, and Copilot
Support
Open a support ticket