@cometchat/skills 4.1.0 → 4.2.0

package/skills/cometchat-react-calls/references/custom-ui.md

@@ -0,0 +1,201 @@
+# Custom call UI on web
+
+When the kit's default `<CometChatOngoingCall />` doesn't fit your app's design system, drop down to the Calls SDK directly. Two escalation paths:
+
+1. **Style the kit's component** — pass style props / CSS variable overrides. Cheapest. Covers most cases.
+2. **Build your own surface on the SDK** — use `CometChatCalls.joinSession(token, settings, container)` directly with your own DOM container. Maximum control. The kit doesn't render anything; you do. (`startSession` is a deprecated v4 shim — use `joinSession`.)
+
+This reference covers path 2 — full custom UI on the SDK. Path 1 is in the kit's component documentation (see `cometchat-customization`).
+
+---
+
+## Architecture
+
+```
+Your React component
+├── Local user video (mic + camera preview)         ← <video> element + getUserMedia
+├── Remote participant video tile(s)                ← <video> elements piped from Calls SDK
+├── Custom control panel (mute, end, switch cam)    ← buttons calling SDK methods
+└── Layout (full-screen / picture-in-picture / grid) ← your CSS
+```
+
+The Calls SDK gives you:
+
+- A `RTCMultiConnection`-like internal connection it manages
+- Track-add events (when a participant's track arrives)
+- Track-remove events
+- Methods to mute/unmute, switch camera, end session
+- A `htmlElement` you pass to `startSession` — **required** — where the SDK draws the call surface. With `enableDefaultLayout(false)`, the SDK still uses this container for internal video elements; your custom UI overlays on top via absolute positioning, OR you keep the container hidden and use the listener events to drive your own `<video>` elements (advanced; see "Advanced — bypassing the SDK's container" below).
+
+---
+
+## Hooking into track events
+
+```tsx
+// CustomOngoingCallView.tsx
+import { useEffect, useRef } from "react";
+import { CometChatCalls } from "@cometchat/calls-sdk-javascript";
+
+interface Props {
+  sessionId: string;
+  authToken: string;
+  onCallEnded: () => void;
+}
+
+export function CustomOngoingCallView({ sessionId, authToken, onCallEnded }: Props) {
+  const localVideoRef = useRef<HTMLVideoElement>(null);
+  const remoteVideoRef = useRef<HTMLVideoElement>(null);
+
+  useEffect(() => {
+    const callListener = new CometChatCalls.OngoingCallListener({
+      onUserListUpdated: (userList: unknown) => {
+        // userList = current participants — re-render your custom roster
+      },
+      onCallEnded: () => {
+        cleanup();
+        onCallEnded();
+      },
+      onCallEndButtonPressed: () => {
+        // User clicked YOUR end button — we still have to call endSession
+        CometChatCalls.leaveSession();
+      },
+      onError: (error: unknown) => {
+        console.error("Call error:", error);
+      },
+      onAudioModesUpdated: (audioModes: unknown[]) => {
+        // available mic / speaker devices
+      },
+      onCallSwitchedToVideo: (call: unknown) => {
+        // remote upgraded the call from voice to video
+      },
+      onMediaDeviceListUpdated: (devices: unknown) => {
+        // user plugged in headphones, etc.
+      },
+    });
+
+    const settings = new CometChatCalls.CallSettingsBuilder()
+      .setSessionID(sessionId)
+      .setIsAudioOnly(false)
+      .enableDefaultLayout(false)            // ← key: we render the UI ourselves
+      .setCallEventListener(callListener)
+      .build();
+
+    // v5 generateToken takes ONLY sessionId — authToken is internal after CometChatCalls.login().
+    CometChatCalls.generateToken(sessionId).then((tokenRes) => {
+      // htmlElement is REQUIRED — pass a container the SDK can draw into.
+      // With custom UI you typically render your own <video> elements; the
+      // container can be hidden but must still be a real DOM node.
+      const container = document.getElementById("calls-container")!;
+      // joinSession is the v5 canonical — startSession is a deprecated shim.
+      CometChatCalls.joinSession(tokenRes.token, settings, container);
+    });
+
+    return () => cleanup();
+
+    function cleanup() {
+      // leaveSession is v5 canonical — endSession() is deprecated (still works as a shim).
+      CometChatCalls.leaveSession();
+      if (localVideoRef.current) localVideoRef.current.srcObject = null;
+      if (remoteVideoRef.current) remoteVideoRef.current.srcObject = null;
+    }
+  }, [sessionId, authToken, onCallEnded]);
+
+  return (
+    <div className="ongoing-call">
+      <video ref={remoteVideoRef} autoPlay playsInline className="remote-tile" />
+      <video ref={localVideoRef} autoPlay playsInline muted className="local-tile" />
+      <ControlPanel
+        onMute={() => CometChatCalls.muteAudio(true)}
+        onUnmute={() => CometChatCalls.muteAudio(false)}
+        onCameraOff={() => CometChatCalls.pauseVideo(true)}
+        onCameraOn={() => CometChatCalls.pauseVideo(false)}
+        onSwitchCamera={() => CometChatCalls.switchCamera()}
+        onEnd={() => {
+          CometChatCalls.leaveSession();
+          onCallEnded();
+        }}
+      />
+    </div>
+  );
+}
+```
+
+---
+
+## Custom control panel — the canonical mute/end/camera buttons
+
+```tsx
+function ControlPanel(props: {
+  onMute: () => void;
+  onUnmute: () => void;
+  onCameraOff: () => void;
+  onCameraOn: () => void;
+  onSwitchCamera: () => void;
+  onEnd: () => void;
+}) {
+  const [muted, setMuted] = useState(false);
+  const [cameraOff, setCameraOff] = useState(false);
+
+  return (
+    <div className="control-panel">
+      <button onClick={() => { muted ? props.onUnmute() : props.onMute(); setMuted(!muted); }}>
+        {muted ? "Unmute" : "Mute"}
+      </button>
+      <button onClick={() => { cameraOff ? props.onCameraOn() : props.onCameraOff(); setCameraOff(!cameraOff); }}>
+        {cameraOff ? "Camera on" : "Camera off"}
+      </button>
+      <button onClick={props.onSwitchCamera}>Switch camera</button>
+      <button onClick={props.onEnd} className="end-call">End</button>
+    </div>
+  );
+}
+```
+
+The SDK methods (`muteAudio`, `pauseVideo`, `switchCamera`) propagate to all participants via the SDK's signaling — you don't manage track state yourself.
+
+---
+
+## Local preview (before the call connects)
+
+For a "ringing" UI where the local user sees their own camera before the receiver picks up:
+
+```tsx
+useEffect(() => {
+  let stream: MediaStream | null = null;
+  navigator.mediaDevices.getUserMedia({ video: true, audio: true }).then((s) => {
+    stream = s;
+    if (localVideoRef.current) localVideoRef.current.srcObject = s;
+  }).catch((err) => {
+    if (err.name === "NotAllowedError") setError("Camera/mic permission denied");
+    if (err.name === "NotFoundError") setError("No camera or mic on this device");
+  });
+
+  return () => {
+    stream?.getTracks().forEach((t) => t.stop());     // CRITICAL — release tracks (rule 1.3)
+    if (localVideoRef.current) localVideoRef.current.srcObject = null;
+  };
+}, []);
+```
+
+Once `startSession` runs, the SDK takes over the camera/mic — release your preview stream first or you'll have two consumers fighting over the device.
+
+---
+
+## Layout customization
+
+The Calls SDK is layout-agnostic when `enableDefaultLayout(false)`. You compose remote tiles in any CSS layout:
+
+- **Spotlight** — one large remote tile + small thumbnails for others. Track which user is speaking (`onActiveSpeakerUpdated` event in some SDK builds) and swap the spotlight.
+- **Grid** — CSS grid with auto-fit columns, 1-N participant tiles equally sized.
+- **Picture-in-picture** — small floating remote video that survives navigation. Mount it in a portal at the layout root (similar to `<CometChatIncomingCall />`).
+
+---
+
+## When to NOT go custom
+
+- Default kit UI works for 80% of apps; custom is a real engineering investment.
+- Recording / screen-share / participant-management features require deeper SDK plumbing — `references/recording-screen-share.md` covers them but custom-UI authors must wire all of them themselves.
+- Kit components handle accessibility (keyboard nav, ARIA roles, focus traps) — custom must replicate.
+- The kit is updated when CometChat ships breaking SDK changes; custom code is yours to migrate.
+
+The dispatcher asks the user whether to go custom (defaults to "no — use kit") and only loads this reference when they say yes.

package/skills/cometchat-react-calls/references/device-management.md

@@ -0,0 +1,206 @@
+# Device management on web
+
+Camera / mic / speaker enumeration + switching mid-call. SDK exposes `getAudioInputDevices()` / `getVideoInputDevices()` / `getAudioOutputDevices()` plus `setAudioInputDevice(deviceId)` etc. Browser handles the underlying `navigator.mediaDevices.enumerateDevices()` plumbing.
+
+**Canonical docs:** https://www.cometchat.com/docs/calls/javascript/device-management
+**Use it for:** "I'm on AirPods, switch from laptop mic"; "this monitor's webcam is bad, use the external one"; pre-call device picker; in-call settings menu.
+
+---
+
+## SDK API
+
+```ts
+import { CometChatCalls } from "@cometchat/calls-sdk-javascript";
+
+// Enumerate
+const mics = await CometChatCalls.getAudioInputDevices();
+const speakers = await CometChatCalls.getAudioOutputDevices();
+const cameras = await CometChatCalls.getVideoInputDevices();
+
+// Currently selected
+const currentMic = CometChatCalls.getCurrentAudioInputDevice();
+
+// Switch (mid-call OK)
+await CometChatCalls.setAudioInputDevice(deviceId);
+await CometChatCalls.setAudioOutputDevice(deviceId);
+await CometChatCalls.setVideoInputDevice(deviceId);
+
+// Listen for device changes (user plugs in headphones, etc.)
+CometChatCalls.addEventListener("onAudioModesUpdated", (devices) => {
+  // re-enumerate; show toast "AirPods connected"
+});
+```
+
+Each device looks like:
+```ts
+interface MediaDevice {
+  id: string;          // browser-assigned ID
+  label: string;       // "Built-in Microphone", "AirPods Pro"
+  // ... other fields per browser
+}
+```
+
+---
+
+## Pre-call device picker
+
+```tsx
+import { useEffect, useState } from "react";
+import { CometChatCalls } from "@cometchat/calls-sdk-javascript";
+
+interface MediaDevice { id: string; label: string; }
+
+function DevicePicker({ onConfirm }: { onConfirm: () => void }) {
+  const [mics, setMics] = useState<MediaDevice[]>([]);
+  const [cameras, setCameras] = useState<MediaDevice[]>([]);
+  const [speakers, setSpeakers] = useState<MediaDevice[]>([]);
+  const [selectedMic, setSelectedMic] = useState<string>();
+  const [selectedCamera, setSelectedCamera] = useState<string>();
+  const [selectedSpeaker, setSelectedSpeaker] = useState<string>();
+
+  useEffect(() => {
+    async function load() {
+      // Devices have empty labels until permission is granted; trigger getUserMedia first
+      try {
+        await navigator.mediaDevices.getUserMedia({ audio: true, video: true });
+      } catch {
+        // permission denied — labels will be empty; offer settings link
+      }
+
+      const [m, c, s] = await Promise.all([
+        CometChatCalls.getAudioInputDevices(),
+        CometChatCalls.getVideoInputDevices(),
+        CometChatCalls.getAudioOutputDevices(),
+      ]);
+      setMics(m); setCameras(c); setSpeakers(s);
+
+      setSelectedMic(CometChatCalls.getCurrentAudioInputDevice()?.id ?? m[0]?.id);
+      setSelectedCamera(CometChatCalls.getCurrentVideoInputDevice()?.id ?? c[0]?.id);
+      setSelectedSpeaker(CometChatCalls.getCurrentAudioOutputDevice()?.id ?? s[0]?.id);
+    }
+    load();
+  }, []);
+
+  async function confirm() {
+    if (selectedMic) await CometChatCalls.setAudioInputDevice(selectedMic);
+    if (selectedCamera) await CometChatCalls.setVideoInputDevice(selectedCamera);
+    if (selectedSpeaker) await CometChatCalls.setAudioOutputDevice(selectedSpeaker);
+    onConfirm();
+  }
+
+  return (
+    <form>
+      <label>
+        Microphone
+        <select value={selectedMic} onChange={(e) => setSelectedMic(e.target.value)}>
+          {mics.map(d => <option key={d.id} value={d.id}>{d.label || `Mic ${d.id.slice(0, 6)}`}</option>)}
+        </select>
+      </label>
+      <label>
+        Camera
+        <select value={selectedCamera} onChange={(e) => setSelectedCamera(e.target.value)}>
+          {cameras.map(d => <option key={d.id} value={d.id}>{d.label || `Camera ${d.id.slice(0, 6)}`}</option>)}
+        </select>
+      </label>
+      <label>
+        Speaker
+        <select value={selectedSpeaker} onChange={(e) => setSelectedSpeaker(e.target.value)}>
+          {speakers.map(d => <option key={d.id} value={d.id}>{d.label || `Speaker ${d.id.slice(0, 6)}`}</option>)}
+        </select>
+      </label>
+      <button type="button" onClick={confirm}>Join call</button>
+    </form>
+  );
+}
+```
+
+**Empty labels gotcha:** browsers return empty `label` strings until permission is granted. Trigger `getUserMedia` once before enumerating to populate labels.
+
+---
+
+## Hot-swap during a call (settings menu)
+
+```tsx
+function InCallDeviceSettings() {
+  const [showMenu, setShowMenu] = useState(false);
+  const [mics, setMics] = useState<MediaDevice[]>([]);
+
+  useEffect(() => {
+    if (!showMenu) return;
+    CometChatCalls.getAudioInputDevices().then(setMics);
+    
+    const onModesUpdated = () => {
+      CometChatCalls.getAudioInputDevices().then(setMics);
+    };
+    CometChatCalls.addEventListener("onAudioModesUpdated", onModesUpdated);
+    return () => CometChatCalls.removeEventListener("onAudioModesUpdated", onModesUpdated);
+  }, [showMenu]);
+
+  async function selectMic(id: string) {
+    await CometChatCalls.setAudioInputDevice(id);
+    setShowMenu(false);
+  }
+
+  return (
+    <div>
+      <button onClick={() => setShowMenu(s => !s)}>Mic ▾</button>
+      {showMenu && (
+        <ul role="menu">
+          {mics.map(d => (
+            <li key={d.id}>
+              <button role="menuitem" onClick={() => selectMic(d.id)}>{d.label}</button>
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+```
+
+`onAudioModesUpdated` fires when the user plugs in headphones, AirPods connect, etc. Re-enumerate on the event.
+
+---
+
+## Bluetooth / AirPods routing
+
+Browsers expose Bluetooth speakers in `getAudioOutputDevices()`. Selecting one calls `HTMLMediaElement.setSinkId()` under the hood — works in Chrome/Edge/Firefox, NOT in Safari (Safari uses system audio routing only).
+
+```ts
+// Detect Safari (limited device-output support)
+const safari = /^((?!chrome|android).)*safari/i.test(navigator.userAgent);
+if (safari) {
+  // Hide speaker selection; show "Use system audio" hint
+}
+```
+
+---
+
+## Anti-patterns
+
+1. **Calling `getAudioInputDevices` before requesting permission.** Returns devices with empty `label` strings — UI shows "undefined" or empty entries.
+2. **Caching device list.** Devices change (plug/unplug). Re-enumerate on every menu open AND on `onAudioModesUpdated`.
+3. **Hardcoding the first device as default.** Browsers may sort differently (built-in vs USB). Read `getCurrent*Device` first; only fall back to first if no current selection.
+4. **Switching speakers in Safari.** `setAudioOutputDevice` silently fails. Detect Safari and hide the speaker picker (or show a "iOS uses system routing" tooltip).
+5. **No listener cleanup on unmount.** Event accumulates listeners on remount; spam every device change.
+
+---
+
+## Verification checklist
+
+- [ ] Permission requested before enumeration (empty-label fix)
+- [ ] `getCurrent*Device()` used as default in pickers
+- [ ] `onAudioModesUpdated` listener for hot-swap detection
+- [ ] Listener cleanup on unmount
+- [ ] Safari speaker picker hidden / fallback message
+- [ ] Browser smoke: plug/unplug headphones during call, picker updates
+- [ ] AirPods smoke: connect AirPods → "AirPods" appears in mic + speaker lists
+- [ ] Multi-camera smoke: USB webcam + built-in, switch between
+
+---
+
+## Pointers
+
+- `cometchat-react-calls` SKILL.md — the seven hard rules
+- `references/custom-ui.md` — full custom call UI integration
+- Canonical docs: https://www.cometchat.com/docs/calls/javascript/device-management

package/skills/cometchat-react-calls/references/group-calls.md

@@ -0,0 +1,262 @@
+# Group calls — broadcast meeting pattern (web)
+
+Group calls in CometChat use a **different signaling channel than 1:1 user calls**. The Ringing flow (Chat SDK `initiateCall` → `onIncomingCallReceived` on peer) fires for **1:1 user calls only**. For groups, the kit broadcasts a **custom message** of type `meeting` to the group; receivers see a "Join meeting" card in their message list (kit-based) OR need an explicit message listener (custom UI).
+
+This is by-design kit behavior — not a bug. Documented across all platform kits.
+
+**Canonical docs:** https://www.cometchat.com/docs/calls/javascript/group-calls
+
+---
+
+## Architecture
+
+```
+Caller (uid-A, member of group-X)        CometChat                Receivers (all other members of group-X)
+  │                                          │                              │
+  │ <CometChatCallButtons group={x}>         │                              │
+  │ → CometChatUIKit.sendCustomMessage(      │                              │
+  │     CustomMessage(GUID, GROUP,           │                              │
+  │       "meeting",                         │                              │
+  │       { callType, sessionId }))          │                              │
+  ├─────────────────────────────────────────>│                              │
+  │                                          │ onCustomMessageReceived      │
+  │                                          ├─────────────────────────────>│ (each member's
+  │                                          │                              │  MessageListener
+  │                                          │                              │  fires if they're
+  │                                          │                              │  in the group)
+  │                                          │                              │
+  │ caller jumps straight to OngoingCall     │                              │
+  │ (joins session GUID directly)            │   receiver taps "Join"       │
+  │                                          │   → joinSession(GUID)        │
+  │  CometChatCalls.joinSession(token, GUID) │ <─────────────────────────── │
+  ├─────────────────────────────────────────>│                              │
+  │            ───── WebRTC session active (sessionId = group GUID) ─────   │
+```
+
+Key contrast with 1:1 ringing:
+
+| Channel | 1:1 user calls | Group calls |
+|---|---|---|
+| Signaling API | `CometChat.initiateCall(call)` | `CometChatUIKit.sendCustomMessage(meetingMessage)` |
+| Receiver event | `CallListener.onIncomingCallReceived` | `MessageListener.onCustomMessageReceived` (category=CATEGORY_CUSTOM + type="meeting") |
+| Session ID | server-generated unique per call | the group's GUID |
+| Ring/decline semantics | yes — `acceptCall` / `rejectCall` | no — receivers just tap to join (or ignore) |
+| Auto-cancel timeout | yes (45s default) | no — meeting card persists in chat history |
+
+---
+
+## Hard rules
+
+1. **Group calls broadcast a custom message; they do NOT use the call listener.** If your custom UI only registers `addCallListener`, group-call recipients will see NOTHING. Add a `MessageListener` that handles `category === CATEGORY_CUSTOM && type === 'meeting'`.
+2. **The session ID equals the group's GUID** — not a generated unique ID like 1:1 calls. Anyone with the GUID can join the session at any time (it's persistent, not auto-cancelled).
+3. **Anyone can join, including after the meeting started.** Late joiners are normal — the WebRTC session is open until all participants leave. UI must handle "joining an already-active meeting" as a valid state.
+4. **Joining = `CometChatCalls.joinSession(token, sessionSettings, container)` with sessionId set to the group GUID.** Same `generateToken(sessionId)` step as 1:1 ringing — auth is internal after `CometChatCalls.login()`.
+5. **No `CometChat.endCall(sessionId)` on the chat side for groups** — the meeting message is the persistent record, not a call entity. Each participant just calls `CometChatCalls.leaveSession()` when they hang up.
+6. **`onCallEndedMessageReceived` does NOT fire for group sessions.** The session persists as long as anyone's in it. Use `CometChatCalls.OngoingCallListener.onCallEnded` to detect when YOUR client's session ends.
+
+---
+
+## Caller side — kit-based
+
+If you're using `<CometChatMessageHeader>` + `<CometChatCallButtons>`, the kit handles everything:
+
+```tsx
+import { CometChatCallButtons } from "@cometchat/chat-uikit-react";
+
+<CometChatCallButtons group={group} />
+```
+
+Tapping voice/video automatically:
+1. Sends a `CustomMessage` of type `meeting` to the group
+2. Opens `<CometChatOutgoingCall>` UI (which transitions to `<CometChatOngoingCall>`)
+3. Joins the WebRTC session with `sessionId = group.getGuid()`
+
+No additional code on the caller side.
+
+## Caller side — custom UI
+
+If you don't use kit components and want full control:
+
+```ts
+import { CometChat } from "@cometchat/chat-sdk-javascript";
+import { CometChatCalls } from "@cometchat/calls-sdk-javascript";
+
+async function startGroupCall(guid: string, callType: "audio" | "video") {
+  const loggedInUser = await CometChat.getLoggedInUser();
+  if (!loggedInUser) throw new Error("Not logged in");
+
+  // 1. Broadcast the meeting message to the group
+  const sessionId = guid;  // group GUID becomes the session ID
+  const customData = { callType, sessionId };
+  const meetingMessage = new CometChat.CustomMessage(
+    guid,
+    CometChat.RECEIVER_TYPE.GROUP,
+    "meeting",
+    customData,
+  );
+  meetingMessage.setCategory(CometChat.CATEGORY_CUSTOM);
+  meetingMessage.setMetadata({
+    incrementUnreadCount: true,
+    pushNotification: "meeting",
+    ...customData,
+  });
+  await CometChat.sendCustomMessage(meetingMessage);
+
+  // 2. Generate a call token + join the session
+  const authToken = loggedInUser.getAuthToken();
+  const { token: callToken } = await CometChatCalls.generateToken(sessionId);
+
+  const callSettings = new CometChatCalls.CallSettingsBuilder()
+    .setIsAudioOnlyCall(callType === "audio")
+    .enableDefaultLayout(true)
+    .setCallListener(
+      new CometChatCalls.OngoingCallListener({
+        onCallEnded: () => { /* hangup UI */ },
+        onError: (err) => { /* show error */ },
+      }),
+    )
+    .build();
+
+  // 3. Mount the WebRTC view into your container element
+  await CometChatCalls.joinSession(callToken, callSettings, containerElement);
+}
+```
+
+The `meeting` message lands in the group's chat history immediately; other members get `onCustomMessageReceived` if they have a listener.
+
+---
+
+## Receiver side — kit-based (auto-renders meeting card)
+
+If your app uses `<CometChatMessageList />` to render the group's messages, the kit auto-renders the meeting message as a **"Join meeting" card** with a tap target. No additional code needed:
+
+```tsx
+<CometChatMessageList group={group} />
+```
+
+When a user taps the meeting card, the kit:
+1. Calls `CometChatCalls.generateToken(sessionId, authToken)`
+2. Opens `<CometChatOngoingCall>` with `sessionID={group.getGuid()}`
+3. Joins the WebRTC session
+
+The receiver is now in the same WebRTC session as the caller (and any other members who joined).
+
+## Receiver side — custom UI (needs a message listener)
+
+If you DON'T use `<CometChatMessageList />` — e.g. you have a custom chat surface, OR you want incoming-meeting notifications globally — register a `MessageListener` and handle the meeting message yourself:
+
+```ts
+import { CometChat } from "@cometchat/chat-sdk-javascript";
+
+const GROUP_MEETING_LISTENER_ID = "APP_GROUP_MEETING_LISTENER";
+
+CometChat.addMessageListener(
+  GROUP_MEETING_LISTENER_ID,
+  new CometChat.MessageListener({
+    onCustomMessageReceived: (msg: CometChat.CustomMessage) => {
+      if (msg.getCategory() !== CometChat.CATEGORY_CUSTOM) return;
+      if (msg.getType() !== "meeting") return;
+
+      const customData = msg.getCustomData() as { callType?: "audio" | "video"; sessionId?: string };
+      const sessionId = customData.sessionId ?? msg.getReceiverId();
+      const callType = customData.callType ?? "video";
+      const fromUid = msg.getSender().getUid();
+      const groupGuid = msg.getReceiverId();
+
+      // Show YOUR group-call incoming UI here
+      // (e.g. toast notification with "Join" button, badge on the group, etc.)
+      showIncomingGroupCallUI({ sessionId, callType, fromUid, groupGuid });
+    },
+  }),
+);
+
+// On hangup or logout:
+CometChat.removeMessageListener(GROUP_MEETING_LISTENER_ID);
+```
+
+Tap-to-join from your custom UI:
+
+```ts
+async function joinGroupCall(sessionId: string, callType: "audio" | "video", container: HTMLElement) {
+  const loggedInUser = await CometChat.getLoggedInUser();
+  const authToken = loggedInUser!.getAuthToken();
+  const { token: callToken } = await CometChatCalls.generateToken(sessionId);
+
+  const callSettings = new CometChatCalls.CallSettingsBuilder()
+    .setIsAudioOnlyCall(callType === "audio")
+    .enableDefaultLayout(true)
+    .setCallListener(
+      new CometChatCalls.OngoingCallListener({
+        onCallEnded: () => { /* hangup UI */ },
+      }),
+    )
+    .build();
+
+  await CometChatCalls.joinSession(callToken, callSettings, container);
+}
+```
+
+No `acceptCall` step — receivers just join the session. The meeting message remains in the chat history regardless of who joins.
+
+---
+
+## Edge cases
+
+### Late joining
+
+A meeting can be active for an hour before a member opens the app. The custom message persists in chat history; tapping the card joins the live session.
+
+**UI implication:** the meeting card should reflect live state. Listen for `MessageListener.onCustomMessageReceived` to add new cards; poll or use presence to know if the session is currently active. There's no built-in "meeting is live" signal — apps typically render the card with a "Join meeting" CTA regardless and let the WebRTC layer fail gracefully if everyone has left.
+
+### Cancelling / leaving
+
+There's no "cancel the meeting" — the meeting message is permanent in chat history. Each participant leaves independently:
+
+```ts
+CometChatCalls.leaveSession();   // your local WebRTC session (v5 — endSession() is deprecated)
+// No CometChat.endCall — meetings don't have a call entity.
+```
+
+If you want to mark a meeting as "ended" UX-wise, send a follow-up message (e.g. another custom message of type `meeting_ended`) and have the receiver UI update its cards based on it. Not built into the SDK.
+
+### Push notifications
+
+The meeting `CustomMessage` carries `metadata.pushNotification = "meeting"`. The CometChat push system can route this to a "meeting started in your group" push. Configure on the dashboard side under Notifications → Push Notification.
+
+### Missed meetings
+
+Since meetings don't ring, there's no "missed call" entity. If you want missed-meeting UI, derive it from message history: list meeting messages where the current user has NOT joined the session.
+
+---
+
+## Anti-patterns
+
+1. **Registering only `addCallListener` and expecting group calls to ring.** They won't. Group calls fire `onCustomMessageReceived`, not `onIncomingCallReceived`. Always add both listeners if you support both 1:1 and group calling.
+2. **Treating `sessionId` as ephemeral for groups.** It's the group GUID — persistent. Don't generate a new sessionId per group call; the kit uses the GUID intentionally so all joiners hit the same WebRTC session.
+3. **Calling `CometChat.endCall(sessionId)` after a group hangup.** Meetings have no call entity to end; the API returns an error. Use `CometChatCalls.leaveSession()` (local) only.
+4. **Using `acceptCall` / `rejectCall` on the meeting message.** Those only work on 1:1 call entities. For meetings, you just join (no accept) or ignore (no reject).
+5. **Assuming all group members ring simultaneously.** Only members with an active `MessageListener` get `onCustomMessageReceived`. Offline members see the meeting card when they next open the group.
+6. **Sending the meeting message without `metadata.pushNotification`.** Offline members won't get a push. The kit handles this for you when you use `<CometChatCallButtons>`; if you're building custom, copy the metadata pattern in §"Caller side — custom UI".
+
+---
+
+## Verification checklist
+
+- [ ] If using kit components: `<CometChatCallButtons group={g}>` renders + tap initiates a meeting message
+- [ ] If using custom caller UI: `CometChat.sendCustomMessage` is called with `type: "meeting"`, `category: CATEGORY_CUSTOM`, `customData: { callType, sessionId: groupGuid }`
+- [ ] If using kit receiver: `<CometChatMessageList group={g}>` renders the meeting card with a "Join" button
+- [ ] If using custom receiver: `addMessageListener` registers `onCustomMessageReceived` and filters by category + type
+- [ ] On hangup, `CometChatCalls.leaveSession()` is called (NOT `CometChat.endCall`)
+- [ ] Late-joining works — open app while meeting is live; tap card; join session
+- [ ] Push notifications fire for offline group members (server-side configured)
+- [ ] Both listeners (`addCallListener` + `addMessageListener`) wired if app supports both 1:1 and group calls
+
+---
+
+## Pointers
+
+- `ringing-integration.md` — the 1:1 user-call flow (different channel — call listener, not message listener)
+- `call-session.md` — pure session-mode (URL-based, no chat-side signaling at all)
+- `cometchat-react-calls/SKILL.md` rule 1.7 — IncomingCall mount (1:1 only; group calls don't use this)
+- Canonical docs: https://www.cometchat.com/docs/calls/javascript/group-calls
+- Kit source (verified 2026-05-15): `node_modules/@cometchat/chat-uikit-react-native/src/calls/CometChatCallButtons/CometChatCallButtons.tsx:138-201`