@cometchat/skills 4.0.0 → 4.2.0

package/skills/cometchat-android-v5-calls/references/group-calls.md

@@ -0,0 +1,205 @@
+# Group calls — broadcast meeting pattern (Android V5)
+
+Group calls in CometChat use a **different signaling channel than 1:1 user calls**. The Ringing flow (`CometChat.initiateCall` → `onIncomingCallReceived` on peer) is **1:1 user only**. For groups, the kit broadcasts a **custom message of type `"meeting"`** to the group; receivers see a "Join meeting" card in `CometChatMessageList` (kit) or need an explicit `MessageListener.onCustomMessageReceived` (custom UI).
+
+By-design kit behavior. Same semantic across all CometChat kits — confirmed against the React Native kit source 2026-05-15.
+
+**Canonical docs:** https://www.cometchat.com/docs/calls/android/group-calls
+
+---
+
+## Architecture
+
+```
+Caller (uidA, member of groupX)        CometChat                Receivers (members of groupX)
+  │                                       │                              │
+  │ CometChatCallButtons sends a          │                              │
+  │ CustomMessage(GUID, GROUP, "meeting", │                              │
+  │   { callType, sessionId })            │                              │
+  ├──────────────────────────────────────>│                              │
+  │                                       │ onCustomMessageReceived      │
+  │                                       ├─────────────────────────────>│
+  │                                       │                              │
+  │ caller mounts CometChatOngoingCallActivity                            │
+  │ with sessionID = groupGuid            │  receiver taps Join          │
+  │                                       │  → joinSession(GUID)         │
+  ├──────────────────────────────────────>│ <─────────────────────────── │
+  │            ───── WebRTC session active (sessionId = group GUID) ─────│
+```
+
+| Channel | 1:1 user calls | Group calls |
+|---|---|---|
+| Signaling | `CometChat.initiateCall(call, callback)` | `CometChat.sendCustomMessage(message, callback)` (type="meeting") |
+| Receiver event | `CallListener.onIncomingCallReceived` | `MessageListener.onCustomMessageReceived` |
+| Session ID | server-generated unique | group's GUID (persistent) |
+| Ring/decline | yes — `acceptCall` / `rejectCall` | no — receivers join or ignore |
+| Auto-cancel timeout | yes (45s default) | no — meeting persists in chat history |
+
+---
+
+## Hard rules
+
+1. **Group calls broadcast a custom message; they do NOT use the call listener.** Custom UI with only `CometChat.addCallListener` receives NOTHING for group meetings.
+2. **Session ID = group GUID.** Persistent, not auto-cancelled.
+3. **Joining = `CometChatCalls.joinSession(sessionId, sessionSettings, container, CallbackListener)`** — single-call shape (token generation internal). `startSession` is a deprecated v4 shim; use `joinSession`.
+4. **No `CometChat.endCall(sessionId)` for groups** — meeting messages have no call entity. Local `CallSession.getInstance().leaveSession()` only.
+5. **ConnectionService / VoIP push for group meetings is NOT built-in.** The CometChat dashboard's push provider routes meeting messages as regular FCM notifications, not as `ACTION_CALL`. Customers wanting ConnectionService-ring for group meetings must intercept the FCM data payload, construct a `Connection` manually, and route into telecom.
+
+---
+
+## Caller side — kit-based
+
+```kotlin
+// Inside a chat surface, e.g. inside CometChatMessageHeader:
+val callButtons = CometChatCallButtons(this)
+callButtons.setGroup(group)
+// Tapping voice/video automatically:
+// - sends CustomMessage(GUID, GROUP, "meeting", { callType, sessionId })
+// - opens CometChatOngoingCallActivity with sessionID = group.guid
+```
+
+No additional code on the caller side. The kit signs the user up for the WebRTC session immediately.
+
+## Caller side — custom UI
+
+```kotlin
+import com.cometchat.chat.core.CometChat
+import com.cometchat.chat.models.CustomMessage
+import com.cometchat.chat.constants.CometChatConstants
+import org.json.JSONObject
+
+fun startGroupCall(groupGuid: String, callType: String /* "audio" | "video" */) {
+    val sessionId = groupGuid
+    val customData = JSONObject().apply {
+        put("callType", callType)
+        put("sessionId", sessionId)
+    }
+
+    val meetingMessage = CustomMessage(
+        groupGuid,
+        CometChatConstants.RECEIVER_TYPE_GROUP,
+        "meeting",
+        customData,
+    ).apply {
+        category = CometChatConstants.CATEGORY_CUSTOM
+        metadata = JSONObject().apply {
+            put("incrementUnreadCount", true)
+            put("pushNotification", "meeting")
+            put("callType", callType)
+            put("sessionId", sessionId)
+        }
+    }
+
+    CometChat.sendCustomMessage(meetingMessage, object : CometChat.CallbackListener<CustomMessage>() {
+        override fun onSuccess(p0: CustomMessage) {
+            // Caller navigates to OngoingCallActivity with sessionId
+            CometChatOngoingCallActivity.launch(this@CallerActivity, sessionId, callType)
+        }
+        override fun onError(p0: CometChatException) { /* surface error */ }
+    })
+}
+```
+
+---
+
+## Receiver side — kit-based (auto-renders meeting card)
+
+If your group's chat surface uses `CometChatMessageList`, the kit renders the meeting `CustomMessage` as a "Join meeting" card. Tap → kit calls `getRTCToken` + opens `CometChatOngoingCallActivity` with `sessionID = group.guid`.
+
+```kotlin
+val messageList = CometChatMessageList(this)
+messageList.setGroup(group)
+// Meeting cards render automatically.
+```
+
+## Receiver side — custom UI (Kotlin Views / Compose — needs MessageListener)
+
+```kotlin
+private val GROUP_MEETING_LISTENER_ID = "APP_ROOT_GROUP_MEETING_LISTENER"
+
+CometChat.addMessageListener(GROUP_MEETING_LISTENER_ID, object : CometChat.MessageListener() {
+    override fun onCustomMessageReceived(msg: CustomMessage) {
+        if (msg.category != CometChatConstants.CATEGORY_CUSTOM) return
+        if (msg.type != "meeting") return
+
+        val customData = msg.customData ?: return
+        val sessionId = customData.optString("sessionId", msg.receiverUid)
+        val callType = customData.optString("callType", "video")
+        val fromUid = msg.sender.uid
+        val groupGuid = msg.receiverUid
+
+        // Switch to main thread for UI work
+        runOnUiThread {
+            // Show your custom incoming-meeting UI:
+            // - notification with "Join" action
+            // - or in-app banner / full-screen activity
+        }
+    }
+})
+
+// Tear down in onDestroy:
+override fun onDestroy() {
+    super.onDestroy()
+    CometChat.removeMessageListener(GROUP_MEETING_LISTENER_ID)
+}
+```
+
+Register in your `Application` class or main `Activity` AFTER login — same lifecycle constraint as the 1:1 `CallListener`.
+
+---
+
+## Edge cases
+
+### Late joining
+
+Meeting messages persist in chat history. Tapping the card joins the live session — works even hours later, until everyone has left.
+
+### Cancelling / leaving
+
+Each participant leaves independently. No "cancel meeting" — the message stays in history.
+
+```kotlin
+CallSession.getInstance().leaveSession()
+// NO CometChat.endCall — meetings have no call entity
+```
+
+### Push notifications
+
+The meeting `CustomMessage` carries `metadata.pushNotification = "meeting"`. CometChat's push system delivers it as a regular FCM notification. To get ConnectionService-ringing for meetings, intercept the FCM data payload in `FirebaseMessagingService.onMessageReceived` and route to `TelecomManager` manually. Not auto-wired.
+
+### Mixed cohorts
+
+If one side uses the kit (auto-renders meeting card in `CometChatMessageList`) and the other uses custom Activity-based UI (no message listener), the custom side receives nothing. Both sides must align on listener strategy.
+
+---
+
+## Anti-patterns
+
+1. **Only `CometChat.addCallListener` registered, expecting group calls to ring.** Won't fire. Add a `MessageListener` too.
+2. **`CometChat.endCall(sessionId)` after a group hangup.** No call entity exists — API errors. Use `CallSession.getInstance().leaveSession()` locally only.
+3. **`<CometChatIncomingCall>` overlay activity expected for group meetings.** It only listens to 1:1 channel.
+4. **Treating sessionId as ephemeral.** It IS the group's GUID. Persistent.
+5. **Sending `CustomMessage` without `metadata.pushNotification = "meeting"`.** Offline group members won't get any push.
+6. **Registering the `MessageListener` before login.** The SDK silently drops listeners registered pre-login. Wire AFTER login, as part of `CometChat.login`'s callback or `addCallListener` lifecycle.
+
+---
+
+## Verification checklist
+
+- [ ] If using kit caller: `CometChatCallButtons.setGroup(group)` + voice/video tap initiates the meeting message
+- [ ] If using custom caller: `CometChat.sendCustomMessage` called with `type="meeting"`, `category=CATEGORY_CUSTOM`, `customData={callType, sessionId: groupGuid}`, `metadata.pushNotification="meeting"`
+- [ ] If using kit receiver: `CometChatMessageList` renders the meeting card with a "Join" CTA
+- [ ] If using custom receiver UI: `CometChat.addMessageListener` registered + filters `category==CATEGORY_CUSTOM && type=="meeting"`
+- [ ] Listener registered AFTER login, NOT before
+- [ ] On hangup: `CallSession.getInstance().leaveSession()` (NOT `CometChat.endCall`)
+- [ ] Late-joining works
+- [ ] FCM data payload routed to ConnectionService manually if OS-ring for meetings is desired
+
+---
+
+## Pointers
+
+- `ringing-integration.md` — 1:1 user calls (different signaling channel)
+- `cometchat-android-v5-calls/SKILL.md` rules — V5 hard rules (calls-sdk-android peer dep, etc.)
+- Canonical docs: https://www.cometchat.com/docs/calls/android/group-calls
+- Reference impl (cross-platform semantic): `cometchat-react-calls/references/group-calls.md`

package/skills/cometchat-android-v5-calls/references/idle-timeout.md

@@ -0,0 +1,111 @@
+# Idle timeout on Android V5
+
+SDK API: SessionSettingsBuilder setters + listener event. ViewModel + StateFlow pattern (cf. `references/raise-hand.md`). Material AlertDialog or BottomSheet for the prompt.
+
+**Canonical docs:** https://www.cometchat.com/docs/calls/android/idle-timeout
+**Read first:** `cometchat-react-calls/references/idle-timeout.md` — settings + archetype timeouts.
+
+---
+
+## SDK API
+
+```kotlin
+import com.cometchat.calls.core.SessionSettingsBuilder
+import com.cometchat.calls.core.SessionType
+
+val settings = SessionSettingsBuilder(context, callContainer)
+  .setSessionType(SessionType.VIDEO)
+  .setIdleTimeoutPeriodBeforePrompt(60_000)
+  .setIdleTimeoutPeriodAfterPrompt(120_000)
+  .build()
+```
+
+Listener — implement on `CometChatCallsEventsListener`:
+
+```kotlin
+override fun onSessionTimedOut() {
+  // Runs on background thread — dispatch to main
+  runOnUiThread {
+    Toast.makeText(this, "Call ended due to inactivity", Toast.LENGTH_LONG).show()
+    finish()  // or NavController.popBackStack()
+  }
+}
+```
+
+---
+
+## ViewModel pattern
+
+```kotlin
+data class CallUiState(val timedOut: Boolean = false)
+
+class CallViewModel : ViewModel() {
+  private val _state = MutableStateFlow(CallUiState())
+  val state: StateFlow<CallUiState> = _state
+
+  fun onSessionTimedOut() {
+    _state.update { it.copy(timedOut = true) }
+  }
+}
+
+// Activity collects:
+lifecycleScope.launch {
+  repeatOnLifecycle(Lifecycle.State.STARTED) {
+    viewModel.state.collect { state ->
+      if (state.timedOut) {
+        showIdleTimeoutToast()
+        finish()
+      }
+    }
+  }
+}
+```
+
+The bridge is the listener calling `viewModel.onSessionTimedOut()` (cf. raise-hand.md ViewModel pattern).
+
+---
+
+## Prompt UI — Material AlertDialog
+
+```kotlin
+fun showIdlePrompt(onStay: () -> Unit, onEnd: () -> Unit) {
+  MaterialAlertDialogBuilder(this)
+    .setTitle("Still there?")
+    .setMessage("You're alone in this call. It'll end in 60 seconds.")
+    .setCancelable(false)
+    .setPositiveButton("Stay") { _, _ -> onStay() }
+    .setNegativeButton("End now") { _, _ -> onEnd() }
+    .show()
+}
+```
+
+`setCancelable(false)` prevents back-button dismiss; user must explicitly choose.
+
+---
+
+## Anti-patterns
+
+Web sister rules + Android-specific:
+
+1. **`Toast.makeText` from background thread.** Crashes — must be on main. `runOnUiThread { ... }` or `lifecycleScope.launch { ... }`.
+2. **Dialog without `setCancelable(false)`.** Back-button dismisses; the timer keeps running and disconnects without user response.
+3. **Listener attached to a Fragment that's been replaced.** Idle timeout fires after fragment destroyed → IllegalStateException. Detach listener in `onDestroyView`.
+
+---
+
+## Verification checklist
+
+- [ ] SessionSettingsBuilder sets both idle periods
+- [ ] `onSessionTimedOut` dispatches to main thread (`runOnUiThread` or coroutine)
+- [ ] Dialog uses `setCancelable(false)`
+- [ ] Listener attached in `onCreate`/`onResume`, detached in matching teardown
+- [ ] Real-device smoke: 2 phones in call, hangup → other shows prompt after delay
+
+---
+
+## Pointers
+
+- `cometchat-react-calls/references/idle-timeout.md` — sister reference
+- `cometchat-android-v5-calls` SKILL.md
+- `references/raise-hand.md` — ViewModel + StateFlow sibling pattern
+- Canonical docs: https://www.cometchat.com/docs/calls/android/idle-timeout

package/skills/cometchat-android-v5-calls/references/in-call-chat.md

@@ -0,0 +1,134 @@
+---
+name: in-call-chat
+description: Add in-call messaging using CometChat Chat SDK and UI Kit. Use when implementing chat during calls, chat button, unread badge count, or group messaging linked to call session. Triggers on "in-call chat", "chat during call", "chat button", "in call messaging", "setChatButtonUnreadCount".
+inclusion: manual
+---
+
+# CometChat Calls SDK v5 — In-Call Chat
+
+## Overview
+
+Add real-time text messaging during calls. Uses a CometChat Group (GUID = session ID) for chat. Requires Chat SDK + UI Kit alongside the Calls SDK.
+
+## Prerequisites
+
+- Calls SDK + Chat SDK + UI Kit integrated
+- Dependencies:
+  ```kotlin
+  implementation("com.cometchat:chat-sdk-android:4.0.+")
+  implementation("com.cometchat:calls-sdk-android:5.0.0-beta.2")
+  implementation("com.cometchat:chat-uikit-android:4.+")
+  ```
+
+## Key Imports
+
+```kotlin
+import com.cometchat.calls.core.CallSession
+import com.cometchat.calls.listeners.ButtonClickListener
+import com.cometchat.chat.core.CometChat
+import com.cometchat.chat.constants.CometChatConstants
+import com.cometchat.chat.models.Group
+```
+
+## Implementation
+
+### 1. Enable Chat Button
+
+```kotlin
+val sessionSettings = CometChatCalls.SessionSettingsBuilder()
+    .hideChatButton(false)  // show chat button (hidden by default)
+    .build()
+```
+
+### 2. Create/Join Chat Group
+
+Use session ID as group GUID:
+
+```kotlin
+private fun setupChatGroup(sessionId: String, meetingName: String) {
+    CometChat.getGroup(sessionId, object : CometChat.CallbackListener<Group>() {
+        override fun onSuccess(group: Group) {
+            if (!group.isJoined) {
+                CometChat.joinGroup(sessionId, group.groupType, null, /* listener */)
+            }
+        }
+        override fun onError(e: CometChatException) {
+            if (e.code == "ERR_GUID_NOT_FOUND") {
+                val group = Group(sessionId, meetingName, CometChatConstants.GROUP_TYPE_PUBLIC, null)
+                CometChat.createGroup(group, /* listener */)
+            }
+        }
+    })
+}
+```
+
+### 3. Handle Chat Button Click
+
+```kotlin
+var unreadCount = 0
+
+callSession.addButtonClickListener(this, object : ButtonClickListener() {
+    override fun onChatButtonClicked() {
+        unreadCount = 0
+        callSession.setChatButtonUnreadCount(0)
+        startActivity(Intent(this@CallActivity, ChatActivity::class.java).apply {
+            putExtra("SESSION_ID", sessionId)
+        })
+    }
+    // ... other overrides
+})
+```
+
+### 4. Track Unread Messages
+
+```kotlin
+CometChat.addMessageListener(TAG, object : CometChat.MessageListener() {
+    override fun onTextMessageReceived(textMessage: TextMessage) {
+        val receiver = textMessage.receiver
+        if (receiver is Group && receiver.guid == sessionId) {
+            unreadCount++
+            CallSession.getInstance().setChatButtonUnreadCount(unreadCount)
+        }
+    }
+})
+
+// Remove in onDestroy
+override fun onDestroy() {
+    CometChat.removeMessageListener(TAG)
+    super.onDestroy()
+}
+```
+
+### 5. Chat Activity (UI Kit)
+
+```kotlin
+class ChatActivity : AppCompatActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContentView(R.layout.activity_chat)
+        val sessionId = intent.getStringExtra("SESSION_ID") ?: return
+
+        CometChat.getGroup(sessionId, object : CometChat.CallbackListener<Group>() {
+            override fun onSuccess(group: Group) {
+                findViewById<CometChatMessageList>(R.id.message_list).setGroup(group)
+                findViewById<CometChatMessageComposer>(R.id.message_composer).setGroup(group)
+                findViewById<CometChatMessageHeader>(R.id.message_header).setGroup(group)
+            }
+            override fun onError(e: CometChatException) {}
+        })
+    }
+}
+```
+
+## Gotchas
+
+- Chat button is **hidden by default** — use `.hideChatButton(false)` to show it
+- The group GUID should match the session ID to link chat to the call
+- `setChatButtonUnreadCount()` updates the badge on the built-in chat button
+- Remove message listeners in `onDestroy()` to prevent leaks
+- UI Kit components (`CometChatMessageList`, etc.) require the UI Kit dependency
+- Create the group before or when joining the call — not after
+
+## Sample App Reference
+
+- `CallActivity.kt` — Session settings and button click listener setup

package/skills/cometchat-android-v5-calls/references/join-session.md

@@ -0,0 +1,120 @@
+---
+name: join-session
+description: Join a CometChat call session using CometChatCalls.joinSession with SessionSettingsBuilder. Use when joining calls, configuring session settings, voice vs video calls, or generating tokens. Triggers on "join session", "join call", "start call", "SessionSettingsBuilder".
+inclusion: manual
+---
+
+# CometChat Calls SDK v5 — Join Session
+
+## Overview
+
+Join a call session using `CometChatCalls.joinSession()`. Supports two approaches: direct session ID (simple) or manual token generation (advanced). Requires a `RelativeLayout` container and configured `SessionSettings`.
+
+## Prerequisites
+
+- Calls SDK initialized and user logged in
+- A valid session ID (from Chat SDK's `Call.sessionId` or your backend)
+- A `RelativeLayout` container in your layout XML
+
+## Key Imports
+
+```kotlin
+import com.cometchat.calls.core.CometChatCalls
+import com.cometchat.calls.core.CallSession
+import com.cometchat.calls.model.SessionType
+import com.cometchat.calls.model.LayoutType
+import com.cometchat.calls.model.AudioMode
+import com.cometchat.calls.exceptions.CometChatException
+```
+
+## Implementation
+
+### Layout Container
+
+```xml
+<RelativeLayout
+    android:id="@+id/call_view_container"
+    android:layout_width="match_parent"
+    android:layout_height="match_parent" />
+```
+
+### Join with Session ID (Recommended)
+
+```kotlin
+val callContainer = findViewById<RelativeLayout>(R.id.call_view_container)
+
+val sessionSettings = CometChatCalls.SessionSettingsBuilder()
+    .setTitle("Team Meeting")
+    .setSessionType(if (isVoiceCall) SessionType.VOICE else SessionType.VIDEO)
+    .setLayout(LayoutType.TILE)
+    .setAudioMode(if (isVoiceCall) AudioMode.EARPIECE else AudioMode.SPEAKER)
+    .startAudioMuted(false)
+    .startVideoPaused(isVoiceCall)
+    .build()
+
+CometChatCalls.joinSession(
+    sessionId,
+    sessionSettings,
+    callContainer,
+    object : CometChatCalls.CallbackListener<CallSession>() {
+        override fun onSuccess(callSession: CallSession) {
+            Log.d(TAG, "Joined session: $sessionId")
+            // Setup listeners on callSession
+        }
+        override fun onError(e: CometChatException) {
+            Log.e(TAG, "Failed to join: ${e.message}")
+        }
+    }
+)
+```
+
+### Join with Token (Advanced)
+
+```kotlin
+// Step 1: Generate token
+CometChatCalls.generateToken(sessionId, object : CometChatCalls.CallbackListener<GenerateToken>() {
+    override fun onSuccess(token: GenerateToken) {
+        // Step 2: Join with token
+        CometChatCalls.joinSession(token, sessionSettings, callContainer,
+            object : CometChatCalls.CallbackListener<CallSession>() {
+                override fun onSuccess(callSession: CallSession) { /* joined */ }
+                override fun onError(e: CometChatException) { /* error */ }
+            }
+        )
+    }
+    override fun onError(e: CometChatException) { /* token error */ }
+})
+```
+
+### Voice Call vs Video Call
+
+```kotlin
+// Video call
+val videoSettings = CometChatCalls.SessionSettingsBuilder()
+    .setSessionType(SessionType.VIDEO)
+    .setLayout(LayoutType.TILE)
+    .setAudioMode(AudioMode.SPEAKER)
+    .startVideoPaused(false)
+    .build()
+
+// Voice call
+val voiceSettings = CometChatCalls.SessionSettingsBuilder()
+    .setSessionType(SessionType.VOICE)
+    .setLayout(LayoutType.SPOTLIGHT)
+    .setAudioMode(AudioMode.EARPIECE)
+    .startVideoPaused(true)
+    .build()
+```
+
+## Gotchas
+
+- The container **must** be a `RelativeLayout`, not `FrameLayout`
+- All participants must use the **same session ID** to join the same call
+- `SessionType` values are `VIDEO` and `VOICE` (not "AUDIO")
+- Call `joinSession` only after SDK is initialized and user is logged in
+- The `CallSession` returned in `onSuccess` is used to register all event listeners
+
+## Sample App Reference
+
+- `CallActivity.kt` — `joinSession()` method with voice/video branching
+- `Repository.kt` — `loginCallsUser()` for authentication before joining