--- name: cometchat-features description: Add features (calls, reactions, polls, file sharing, presence, etc.) to an already-integrated CometChat project. Routes to the right sub-flow based on feature type — default (already enabled), extension (API toggle), ai-feature (API toggle + OpenAI key), dashboard-only (third-party config), package-install (calls), or component-swap (rich text). license: "MIT" compatibility: "Node.js >=18; @cometchat/chat-uikit-react ^6; integration must already be applied" metadata: author: "CometChat" version: "3.0.0" tags: "cometchat features extensions calls reactions polls ai-features" --- > **Ground truth:** the 5-tier feature catalog `packages/registry/v6/features/catalog.json` + the per-platform UI Kit `defaultExtensions[]`. (Official docs linked below.) Verify symbols against the installed package/source before relying on them. > **Scope — this IS the web / React features skill** (`@cometchat/chat-uikit-react`). Web/React intentionally has no separate "react-features" skill: this one is it. Each other family has its own features skill (native / angular / android-v5 / android-v6 / ios / flutter-v6). **Flutter V5 has none — it proxies to `cometchat-flutter-v6-features`** for enablement: feature *enablement* is the SDK/dashboard `apply-feature` path (identical across V5/V6); only the in-UI wiring differs, and V5 is legacy/maintenance-only. The `apply-feature` CLI + the 5-tier taxonomy below apply to all families. > **Companion skills:** `cometchat-core` covers initialization and the > provider pattern; `cometchat-customization` is the next step when a > feature is enabled but needs visual customization; > `cometchat-troubleshooting` handles post-feature-enable failures. ## Purpose This skill teaches Claude how CometChat features are structured and what work is actually required to enable each one. Most features require **zero code** — they are either already built into the UI Kit, toggled via the `cometchat apply-feature` CLI (which hits the dashboard API), or activated by a single npm install. Understanding which type a feature is prevents unnecessary work. --- ## 1. Use this skill when The user wants to add a specific feature to an already-integrated CometChat project. Trigger phrases: - `/cometchat features` (or invoke the cometchat-features skill via your agent's mechanism — keyword "cometchat feature" or "add chat feature" works in most agents) - `/cometchat features ` (e.g. `/cometchat features reactions`) - `/cometchat ` (e.g. `/cometchat polls`, `/cometchat calls`) - "add reactions to my chat" - "add video calling" - "enable polls" - "add file sharing" - "enable smart replies" - "add typing indicators" ## 2. Preconditions The user must have an existing integration: ```bash npx @cometchat/skills-cli info --json ``` If `integrated` is `false`, **stop** and tell the user to run `/cometchat` first to create the integration. ## 3. The 5 feature categories (customer-facing) — and what work each needs CometChat's canonical "Feature Availability" model sorts every feature into **5 categories by the work needed** (the catalog encodes this per-feature as `tier` + the operative columns `code` / `dashboard_settings` / `builder`; run `cometchat features info --json`). > **Canonical public decision-reference (source of truth):** [Features & Extensions Guide](https://www.cometchat.com/docs/fundamentals/features-and-extensions-guide) on the public docs. It is the authoritative, always-current matrix of *which integration method supports each feature* (UI Kit / UI Kit Builder / Widget Builder / SDK), *what dashboard setup it needs*, and *whether code is required*. **When the local `catalog.json` and this page disagree, the docs page wins** — the catalog is a build-time snapshot derived from the same model and can lag a release. For any "can the builder do X? / is feature Y code-or-dashboard?" decision, consult this page (WebFetch it, or query the docs MCP) rather than answering from memory or a stale snapshot. | Tier | Category | Work needed | Example | |---|---|---|---| | **1** | Core Messaging (Zero Setup) | Nothing — renders out of the box | Typing Indicators | | **2** | Builder-Enabled (Config + UI Toggle) | Enable via Dashboard API; toggle/place in the UI Kit Builder | Polls | | **3** | Config-Only (Dashboard-Driven) | Enable via Dashboard API; works automatically | Link Preview | | **4** | Config + Settings (Smart) | Dashboard API + extra settings (API keys, thresholds) — no code | Smart Replies | | **5** | SDK-Integrated (Config + Code) | Dashboard API + **custom client code** | Bitly | Tiers 1–4 need **no client code** (`code: "none"`). **Tier 5 needs code — and the implementation already lives in the docs.** When a feature's `code` is `custom-code` or `steps-in-docs` (i.e. `auto_wired_in_uikit: false`), the flow is: flip the dashboard toggle (`apply-feature `), then **fetch the reference implementation from the docs (`docs_topic`, via the docs MCP) and adapt it — do NOT hand-roll.** A few Core features carry `code: "stitch-components"` (e.g. Threaded Conversations, Advanced Search): no extension, but you **compose existing kit components** — the kit sample apps show the wiring (see [[uikit-local-clones-canonical-source]]). The 14 code-needed extensions: bitly, message-shortcuts, pin-message, rich-media-preview, save-message, tinyurl, voice-transcription, giphy, reminders, stipop, tenor, disappearing-messages, chatwoot, intercom. > T2 vs T3 is a Builder-surface nuance (does the Builder expose a placement/toggle for it). Operationally both are "enable via Dashboard, no code" — the `builder: "toggle"` flag marks the ones the Builder surfaces. --- ## 3b. Enablement mechanism (how the CLI flips each on) Independently of the 5 customer-facing tiers above, the catalog tags each feature with an **enablement mechanism** — what the CLI's `apply-feature` actually does: - **default (compiled-in):** Shipped inside the UI Kit component bundle unconditionally. CometChat builds reactions, typing indicators, mentions, etc. into `CometChatMessageList` and `CometChatMessageComposer` at compile time. The feature is always present; the only question is whether the prop that surfaces it is enabled. No action needed. - **extension (backend boolean toggle):** Pure on/off backend extension. The CLI's `apply-feature` command flips the toggle via the same REST API the dashboard UI uses (`POST /apps/{id}/extensions`), so no browser visit required. Once enabled, the UI Kit renders the matching UI automatically **only for the auto-wired subset** (`auto_wired_in_uikit: true`, `code: "none"`); the rest (tier 5) need client code from the docs. Examples: polls, link-preview, message-translation, stickers. - **ai-feature (backend AI toggle + OpenAI key):** Same API path as extensions but split out because the AI feature requires an OpenAI API key on the app's AI settings (`PUT /apps/{id}/ai/settings`) before the toggle (`POST /apps/{id}/features/ai.{key}/enabled`) succeeds. The CLI handles both calls in one invocation when given `--openai-key sk-…`. Examples: smart-replies, conversation-summary, conversation-starter. - **dashboard-only (third-party config):** Requires entering config the user has to fetch themselves — third-party API keys (Giphy, Stipop, Tenor), webhooks (Chatwoot), or multi-field choices (disappearing-messages interval, message-shortcuts list). The CLI cannot automate these; the skill prints the dashboard path and stops. - **package-install (separate SDK):** Voice/video calling requires `@cometchat/calls-sdk-javascript` because it links against browser media APIs that would bloat every integration if bundled unconditionally. Once installed, the UI Kit detects it via dynamic import. - **component-swap (variant component):** Replaces one UI Kit component with a drop-in variant whose default behavior differs (e.g. `CometChatCompactMessageComposer` enables rich text by default). The CLI does a safe word-boundary replace in `state.files_owned`. Requires `cometchat apply` to have run (i.e. web/RN integrations only — native cohorts can't use this path). --- ## 4. The feature catalog ### Type 1 — Default features (~14, already enabled in UI Kit) These are already part of the components your integration uses. The skill's job is to **tell the user they're already there** and point at the relevant component: - Instant Messaging - Media Sharing (file/image/audio/video) - Read Receipts - Mark as Unread - Typing Indicator - User Presence (online/offline) - Reactions - Mentions (incl. @all) - Threaded Conversations - Quoted Replies - Group Chat - Report Message - Conversation/Advanced Search For these: query the docs MCP for the feature's component/usage docs, show the user where it is in their integration. **No code changes needed.** ### Type 2a — Extensions (pure boolean, CLI-toggleable) These are backend extensions enabled by a single API call (`POST /apps/{id}/extensions`). Use the CLI — no browser visit required: ```bash cometchat apply-feature ``` For native cohorts (iOS / Android / Flutter / Angular) where there's no `.cometchat/state.json`, pass `--app-id` explicitly: ```bash cometchat apply-feature --app-id ``` Once enabled, the UI Kit auto-integrates them. **No code changes needed — for the auto-wired subset.** > ⚠️ **The "no code needed" pitch only holds for ~7 of 24 dashboard-toggle features (ENG-35721).** The dashboard exposes 24 extensions; only the ones marked `auto_wired_in_uikit: true` in the CLI's catalog (~7 — Link Preview, Polls, Stickers, Message Translation, Smart Replies, Conversation Starter, and a handful more) render automatically via the kit's bubbles + composer. The other ~17 (Bitly, TinyURL, Voice Transcription, Reminders, Save Message, Pin Message, etc.) require **either a kit prop opt-in OR a small component-side handler** — `apply-feature ` flips the dashboard toggle but does NOT wire client-side rendering for those. **Before promising "no code needed" to the customer**, run `cometchat features info --json` and check the `auto_wired_in_uikit` field; if `false`, set expectations honestly and emit the wiring code. > ⚠️ **`features enable` has TWO unstated prereqs (ENG-35721):** > 1. **`auth login` must have completed** — the toggle is gated on the dashboard bearer token. The CLI's "no app" error says nothing about login; running `cometchat features enable ` cold (after only `provision setup`) fails with a misleading message. Run `cometchat auth status --json` first; if `"logged-out"`, run `cometchat auth login` before any `features enable`. > 2. **Either `.cometchat/config.json` OR `--app-id `** — the toggle needs an app context. If the user pasted credentials manually (the dispatcher's Step 2d path) they may NOT have a `.cometchat/config.json` yet. **Manual `.env` users:** run `cometchat config save --app-id --region --json` to bridge into `.cometchat/config.json` before `apply-feature`, OR pass `--app-id` on every `apply-feature` call. > **Note:** Conversation and Advanced Search has its own toggle on the > Features page. It is on by default but can be disabled. If a user > reports that search is missing, check this toggle. **Extensions — User Experience:** Avatar, Bitly, Link Preview, Message Shortcuts, Pin Message, Rich Media Preview, Save Message, Thumbnail Generation, TinyURL, Voice Transcription **Extensions — User Engagement:** Giphy, Message Translation, Polls, Reminders, Stickers, Stipop, Tenor > ⚠️ **Broadcast was removed (ENG-35699).** Earlier versions of this skill listed "Broadcast" here, but the CLI's 40-feature catalog has no `broadcast` or `broadcast-message` id — `cometchat-skills-cli features info broadcast` returns "not found." Broadcast as a *use case* is achievable via standard CometChat extensions (one-to-many group messages with `subscribePresenceForAllUsers`) or via Custom Messages — but there is no "Broadcast" extension toggle in the dashboard today. If a customer asks for broadcast functionality, route them at custom messages + a server-side fan-out webhook, not a feature toggle. **Extensions — Collaboration:** Collaborative Document, Collaborative Whiteboard **Extensions — Security:** Disappearing Messages, E2E Encryption (Enterprise plan only) **Extensions — Moderation (LEGACY — prefer Rules Management, see §"Moderation" below):** Data Masking, Image Moderation, Profanity Filter, Sentiment Analysis, XSS Filter, Human Moderation, Report User, Slow Mode, Virus/Malware Scanner. ⚠️ Deprecated; don't run alongside moderation Rules (double-processes every message). **Notifications extensions** (Chat & Messaging → Features): Email Notification, Push Notification, SMS Notification **Extensions — Customer Support:** Chatwoot, Intercom ### Type 2b — AI features (CLI-toggleable, OpenAI key required) `smart-replies`, `conversation-summary`, `conversation-starter`. These need an OpenAI API key on the app's AI settings before the toggle succeeds. The CLI does both calls in one invocation: ```bash cometchat apply-feature smart-replies --openai-key sk-... # native: cometchat apply-feature smart-replies --app-id --openai-key sk-... ``` After the first AI feature is enabled the key is stored on the app, so subsequent ai-feature applies don't need `--openai-key` repeated. Get an OpenAI key: https://platform.openai.com/api-keys ### Type 2c — Dashboard-only (third-party config required) These extensions require config the user has to provide themselves (third-party API keys / webhooks / multi-field setup) — `apply-feature` returns `manual-action-required` and prints the dashboard path. The CLI cannot automate these: - **Third-party API keys:** Giphy, Stipop, Tenor, Intercom - **Webhooks:** Chatwoot - **Multi-field config:** Message Shortcuts (shortcut list), Disappearing Messages (interval) Manual flow for these: 1. https://app.cometchat.com → select your app 2. Sidebar → Chat & Messaging → Features 3. Find the extension, enter the third-party config, toggle ON ### Moderation — use Rules Management (NOT the legacy extensions) **The canonical moderation system is Rules Management**, not the old per-extension toggles. Configure rules once in the Dashboard (**Moderation → Settings → Rules**, or the `/moderation/rules` REST API — also `/moderation/{keywords,reasons, blocked-messages,flagged-messages,reviewed-messages}`) and they auto-apply to every message with **no client code** (the UI Kit + SDK enforce them seamlessly). Docs: `moderation/overview` + `moderation/rules-management`. > ⚠️ **Do NOT run legacy moderation extensions AND Rules on the same app.** The > legacy extensions (Data Masking, Image Moderation, Profanity Filter, Sentiment > Analysis, XSS Filter, Slow Mode, Virus/Malware Scanner) are **deprecated**. If > both a legacy extension and a Rule are active, **every message is processed > twice** → delays + perf issues. Disable the legacy extensions (Dashboard → > Extensions) before creating Rules. `apply-feature ` still works but > emits this same warning — prefer Rules. - **Notifications** (separate, unaffected): Email, Push, SMS — Sidebar → **Extensions** → configure + enable. After enabling any feature, run `cometchat verify` to ensure the existing integration still passes. No code changes are needed — the UI Kit picks up enabled features automatically. ### Type 3 — Package-install features (4, calls) These require installing `@cometchat/calls-sdk-javascript`. Once installed, the UI Kit auto-detects it and surfaces the call UI in CometChatMessageHeader, CometChatConversations, etc. - Call Buttons (in message headers) - Incoming Call notifications - Outgoing Call interface - Call Logs (call history) For these, the user opting in IS consent — run the install directly: ```bash npm install @cometchat/calls-sdk-javascript@^5 npx @cometchat/skills-cli verify --json ``` The UI Kit's `initiateAfterLogin()` auto-calls `enableCalling()` after the package is installed. No manual wiring needed for default call buttons in CometChatMessageHeader. Restart the dev server. ### Type 5 — Custom message types (APPEND, never REPLACE — ENG-35706) When a customer wants to send a new message type (location, product card, custom event), the V6 React kit ships a templates API that is **dangerously easy to misuse.** Two testers hit the same trap: they added one custom template and watched ALL existing bubbles (text, image, audio, video, file) disappear AND the composer's entire attachment menu (Camera/Image/Video/File/Whiteboard/Document) get replaced by their one new attachment. **Cause:** `` and `` **REPLACE** the kit's built-in templates / options rather than appending to them. **Correct pattern — always merge with the kit's defaults:** ```tsx import { CometChatMessageList, CometChatMessageComposer, CometChatMessageTemplate, // the kit's template class — verified export (src/index.ts:79) CometChatMessageComposerAction, // attachment-menu action class CometChatUIKit, // exposes getDataSource() CometChatUIKitConstants, // MessageTypes / MessageCategory enums } from "@cometchat/chat-uikit-react"; // 1. Build your custom template with the kit's CometChatMessageTemplate class. // ⚠️ It is `new CometChatMessageTemplate(...)` (UI Kit) — NOT // `new CometChat.MessageTemplate(...)`. The Chat SDK has no MessageTemplate // export; that form does not exist and will not compile. const locationTemplate = new CometChatMessageTemplate({ type: "location", category: CometChatUIKitConstants.MessageCategory.custom, // "custom" contentView: (message, alignment) => , // headerView / footerView / bottomView / bubbleView / statusInfoView / options // all inherit the kit's defaults when omitted. }); // 2. Merge with the kit's defaults — DO NOT pass only your template. // CometChatUIKit.getDataSource() is the public accessor; it returns the same // DataSource as ChatConfigurator.getDataSource() (the latter is internal). const defaultTemplates = CometChatUIKit.getDataSource().getAllMessageTemplates(); const mergedTemplates = [...defaultTemplates, locationTemplate]; ``` **Same rule for attachment options.** `getAttachmentOptions` takes a `ComposerId` (`{ user?, group?, parentMessageId? }`) **AND a required second argument** (`additionalConfigurations`), then append your action: ```tsx // ComposerId = { parentMessageId, user, group } — all three keys, values nullable. const composerId = { parentMessageId: null, user: selectedUser?.getUid() ?? null, group: selectedGroup?.getGuid() ?? null, }; // ⚠️ MUST pass a defined object as the 2nd arg. The extension data sources // (Polls, Collaborative Document/Whiteboard) read `messageToReplyRef` off it // WITHOUT optional chaining — passing nothing/undefined throws at runtime: // "Cannot read properties of undefined (reading 'messageToReplyRef')" // (Verified against the official v6 sample app's live-location feature.) const additionalConfigurations = { messageToReplyRef: { current: null } }; const defaultAttachments = CometChatUIKit.getDataSource().getAttachmentOptions( composerId, additionalConfigurations, ); const mergedAttachments = [...defaultAttachments, new CometChatMessageComposerAction({ id: "send-location", title: "Location", iconURL: "/icons/location.svg", onClick: () => { /* open location picker */ }, })]; ``` **Also**: when sending the custom message, set both `receiverType` AND `type` correctly. Two testers hit `"Cannot determine message recipient"` because they passed a partial `CustomMessage` constructor. Use the full form: ```tsx const msg = new CometChat.CustomMessage( receiverID, // who to send to (required) receiverType, // CometChat.RECEIVER_TYPE.USER or .GROUP (required — this is the field testers missed) "location", // custom type identifier { lat, lng, label } // your payload ); CometChat.sendCustomMessage(msg); ``` > **Custom type sends + renders live, but vanishes on reload?** The custom message > appears immediately (the `ccMessageSent` event), but to **fetch it from history** > you must include your custom category + type in the list's `messagesRequestBuilder`. > Extend the kit's defaults (don't hand-list them) — append to > `getAllMessageCategories()` + `getAllMessageTypes()`: > > ```tsx > const categories = CometChatUIKit.getDataSource().getAllMessageCategories(); > if (!categories.includes(CometChatUIKitConstants.MessageCategory.custom)) > categories.push(CometChatUIKitConstants.MessageCategory.custom); > const types = CometChatUIKit.getDataSource().getAllMessageTypes(); > if (!types.includes("location")) types.push("location"); > > const messagesRequestBuilder = new CometChat.MessagesRequestBuilder() > .setCategories(categories).setTypes(types).hideReplies(true).setLimit(30); > > > ``` > (Verified against the official v6 sample app's live-location feature.) Tip: on the > `CustomMessage`, call `setConversationText("Live Location")` so it reads nicely as > the conversation-list preview, and `setSender(loggedInUser)` for optimistic render. #### Override an existing message type's bubble (text / image / etc.) Same templates API — fetch all, replace `contentView` (or `bubbleView` for the whole bubble) on the matching template, pass the array. There is NO separate "override" call; you reuse `getAllMessageTemplates()`: ```tsx const templates = CometChatUIKit.getDataSource().getAllMessageTemplates(); const withCustomTextBubble = templates.map((t) => { if ( t.type === CometChatUIKitConstants.MessageTypes.text && t.category === CometChatUIKitConstants.MessageCategory.message ) { t.contentView = (message, alignment) => ; // or t.bubbleView = (...) => <... /> to replace the ENTIRE bubble (header+content+footer) } return t; }); ``` (`CometChatUIKit.getDataSource().getMessageTemplate(type, category)` returns a single template if you'd rather fetch just one — but you still pass the full array to the `templates` prop.) #### Add a custom message option (Forward-style long-press action) Message options live on each template's `options` function. Override it and **merge with the kit defaults** (same REPLACE-vs-APPEND rule) via `getMessageOptions`. Custom actions use `CometChatActionsIcon` (NOT `CometChatMessageComposerAction` — that's composer-only): ```tsx import { CometChatActionsIcon } from "@cometchat/chat-uikit-react"; const templates = CometChatUIKit.getDataSource().getAllMessageTemplates(); const withForward = templates.map((t) => { if (t.type === CometChatUIKitConstants.MessageTypes.text) { t.options = (loggedInUser, message, group) => { // getMessageOptions(loggedInUser, messageObject, group?, additionalParams?) const options = CometChatUIKit.getDataSource().getMessageOptions(loggedInUser, message, group); options.push( new CometChatActionsIcon({ id: "forward", title: "Forward", iconURL: "/icons/forward.svg", onClick: (id) => { /* open your forward-to picker → CometChat.sendMessage(...) */ }, }) ); return options; }; } return t; }); ``` "Forward" is not a built-in kit option, so it's added as a custom `CometChatActionsIcon`. The built-ins (reply, edit, delete, react, …) come from `getMessageOptions` — keep them by merging, don't return only your action. > ⚠️ **Kit-side limitation (ENG-35706):** custom message send sometimes **replaces** an existing message in the list in real-time (UI-side overwrite, not server-side). No client workaround today; file a kit ticket if you observe this and document for the customer. #### Text formatters (inline text styling — mentions, URLs, custom @/#/! tokens) Text formatters transform message text inline. The kit ships `CometChatMentionsFormatter`, `CometChatUrlsFormatter`, `CometChatMarkdownFormatter` (all subclasses of the base `CometChatTextFormatter`). **Same APPEND-not-REPLACE rule** as templates/options: passing a bare `textFormatters={[...]}` array drops the built-ins — start from `getAllTextFormatters({})` and append. (Pattern verified against the kit sample app `sample-app/src/components/CometChatMessages/CometChatMessages.tsx`.) ```tsx import { CometChatUIKit, CometChatMessageList, CometChatTextFormatter, } from "@cometchat/chat-uikit-react"; // getAllTextFormatters({}) returns the kit defaults (mentions, URLs, …). // START here and append — don't hand the component a bare array. const formatters: CometChatTextFormatter[] = CometChatUIKit.getDataSource().getAllTextFormatters({}); // Append your own: subclass CometChatTextFormatter (override its regex + view // hooks) and push it. See the per-pattern guides below for full subclasses. // formatters.push(new MyHashtagFormatter()); ; ``` > **Guides (canonical subclass examples):** custom-text-formatter-guide, mentions-formatter-guide, url-formatter-guide, shortcut-formatter-guide — all under `ui-kit/react/` (query the docs MCP, or `documentation/docs/ui-kit/react/*-formatter-guide.mdx` locally). Each shows a complete `CometChatTextFormatter` subclass (regex + `getFormattedText` + a custom view). ### Type 6 — Dashboard-AI mode (UI-side side-effects — ENG-35706) When the customer enables the AI Agent on the dashboard (e.g. `aiAssistant: true` for an app), the SAME `` renders with thread reply buttons + call buttons that don't make sense in an AI-only conversation surface. **Detect AI mode and branch the layout:** ```tsx // Read app's AI config from the dashboard via the CLI // npx @cometchat/skills-cli features info ai-assistant --json // → { enabled: true, models: [...], ... } const isAiMode = aiAssistantConfig?.enabled === true; ``` The kit doesn't auto-detect dashboard AI mode and adjust its layout — that's a kit-side gap (filed as part of ENG-35706). Until the kit ships a built-in `aiMode` prop, the skill must read the dashboard flag via `features info ai-assistant --json` (see ENG-35716 dispatcher rule) and gate the relevant buttons. ### Type 4 — Component-swap features (drop-in variant) Some features require swapping one component for a variant that has different default behavior. The CLI handles the swap automatically — it walks `state.files_owned`, performs a word-boundary regex replace, updates `state.json` checksums, and records the applied feature so re-runs are no-ops. Idempotent. Currently available: - `rich-text-formatting` — swaps `CometChatMessageComposer` → `CometChatCompactMessageComposer` (the compact variant enables rich text formatting by default; the regular composer has `enableRichTextEditor=false` baked in) ```bash npx @cometchat/skills-cli apply-feature rich-text-formatting ``` Do NOT hand-edit the swap. The CLI is the source of truth. If future SDK releases add new variant components, they will follow this same `apply-feature ` pattern. --- ## 4b. Deep patterns for three most-requested features For calls, AI smart replies, and presence, the catalog above only says "install a package" or "toggle in dashboard." Here are the concrete compositional patterns so common requests don't require a docs MCP round-trip. ### Calls (audio + video) After `npm install @cometchat/calls-sdk-javascript`, call buttons auto-appear in `CometChatMessageHeader` and the call UI renders in place. **No manual wiring needed** for basic 1:1 audio/video calls. For custom integration — e.g. putting a "Start video call" button outside the message header, or handling an incoming call notification in a custom way — use `CometChatCallButtons` + `CometChatIncomingCall` + `CometChatOngoingCall`: ```tsx import { useState, useEffect } from "react"; import { CometChatCallButtons, CometChatIncomingCall, CometChatOngoingCall, } from "@cometchat/chat-uikit-react"; import { CometChat } from "@cometchat/chat-sdk-javascript"; export function CustomCallUI({ targetUser }: { targetUser: CometChat.User }) { const [ongoingCall, setOngoingCall] = useState(); useEffect(() => { // Listen for call state changes const listenerId = "custom-call-listener"; CometChat.addCallListener( listenerId, new CometChat.CallListener({ onOutgoingCallAccepted: (call: CometChat.Call) => setOngoingCall(call), onIncomingCallCancelled: () => setOngoingCall(undefined), // CallListener uses onCallEndedMessageReceived (NOT onCallEnded — that's // an OngoingCallListener callback, passed to CallSettingsBuilder). onCallEndedMessageReceived: () => setOngoingCall(undefined), }), ); return () => CometChat.removeCallListener(listenerId); }, []); return ( <> {ongoingCall && } ); } ``` **Common gotchas — UI Kit path:** - Calls require a logged-in CometChat user on *both* sides. Test from two browsers (or incognito) logged in as different UIDs. - `CometChatIncomingCall` must be mounted globally (e.g. in your provider or layout) so incoming calls ring on every page. - Group calls use `CometChat.Group` instead of `CometChat.User` on `CometChatCallButtons`. **Common gotchas — SDK-only path (no UI Kit components, ENG-35707 Birendra follow-up):** When the integrator opts out of `` / `` / `` and builds the call surface directly on the Calls SDK, the UI-Kit gotchas above don't apply but a different set kicks in: - **`CometChat.CALL_TYPE.AUDIO` vs `.VIDEO` (Chat SDK)** are NOT the same as **`CometChatCalls.constants.TYPE.VOICE` / `.VIDEO` (Calls SDK)** — use Chat SDK enum on the `Call` entity, Calls SDK enum on `CallSettings`. See `cometchat-react-calls` §4c constants table. - **`setIsAudioOnlyCall(true)` on `CallSettingsBuilder`** for voice calls — without it, voice calls still acquire the camera (just don't render it). - **`joinSession` MUST fire after the container is mounted** — don't call it inside the `onOutgoingCallAccepted` listener directly; set state and let a `useEffect(phase, containerRef)` join when the ref + phase agree. The natural site fires before the in-call panel renders. - **Group calls have no "ring a group" primitive** — use a CustomMessage broadcast + a shared sessionId; the UI Kit's `CometChatCallButtons` for groups sends a `meeting`-type CustomMessage, not `initiateCall`. SDK-only mirrors that. - **Default call types** — 1:1 = video, group = voice (mirroring the kit's defaults). If you build custom buttons, replicate this so customers' integrations behave consistently. - **`CometChatCalls.login` is mandatory on raw-SDK paths** (NOT when using the UI Kit, where `enableCalls = true` / kit-managed init auto-logs the Calls SDK). On raw SDK, after Chat SDK login, separately call `CometChatCalls.login(uid, apiKey)` — without it, `generateToken` returns 401. These map to the React-specific recipes in `cometchat-react-calls` §4c. Same primitives apply across families; container-mount race + ref-state coordination is generic. ### AI smart replies Smart replies is an `ai-feature`. Enable with one CLI call (the first time also sets the OpenAI key on the app): ```bash cometchat apply-feature smart-replies --openai-key sk-... # native cohorts: add --app-id ``` **No code changes are required** — the `CometChatMessageComposer` automatically renders suggested replies as chips above the input when there's a recent incoming message. For a custom UI — e.g. showing smart replies inline instead of above the composer, or only for certain conversation types — you read the extension data from the incoming message and render your own chips: ```tsx function SmartReplyChips({ message }: { message: CometChat.BaseMessage }) { const metadata = message.getMetadata() as Record | undefined; const extensions = (metadata?.["@injected"] as Record)?.["extensions"] as | Record | undefined; const smartReply = extensions?.["smart-reply"] as { reply_positive?: string; reply_neutral?: string; reply_negative?: string } | undefined; if (!smartReply) return null; const replies = [smartReply.reply_positive, smartReply.reply_neutral, smartReply.reply_negative].filter(Boolean) as string[]; return (
{replies.map((r) => ( ))}
); } ``` Smart replies are server-generated and attached to messages via the `@injected.extensions.smart-reply` metadata path — the AI feature runs on CometChat's backend, not in your code. ### Presence (online / offline status) Presence is a **default feature** (Type 1) — online status indicators appear automatically on user avatars in `CometChatConversations`, `CometChatUsers`, and `CometChatGroupMembers`. Nothing to install, nothing to enable. For custom UI that needs to know a specific user's online state — e.g. a "Sold by Aria Chen · online now" label on a product page — subscribe to user events: ```tsx import { useEffect, useState } from "react"; import { CometChat } from "@cometchat/chat-sdk-javascript"; export function useUserPresence(uid: string): "online" | "offline" | "unknown" { const [status, setStatus] = useState<"online" | "offline" | "unknown">("unknown"); useEffect(() => { // 1. Fetch initial state CometChat.getUser(uid).then((u) => { setStatus(u.getStatus() === "online" ? "online" : "offline"); }); // 2. Subscribe to live changes const listenerId = `presence-${uid}`; CometChat.addUserListener( listenerId, new CometChat.UserListener({ onUserOnline: (user: CometChat.User) => { if (user.getUid() === uid) setStatus("online"); }, onUserOffline: (user: CometChat.User) => { if (user.getUid() === uid) setStatus("offline"); }, }), ); return () => CometChat.removeUserListener(listenerId); }, [uid]); return status; } ``` **Common gotchas:** - Presence events only fire for users the current user has interacted with (conversation exists, in same group, etc.). For arbitrary UIDs with no prior interaction, you may need to call `CometChat.getUser(uid)` periodically instead. - `getStatus()` returns `"online"` or `"offline"` — also check `getLastActiveAt()` for a "last seen X ago" timestamp. - "Last seen" is disabled by default on free-tier apps. Enable it in the dashboard (Settings → Chat → Last Seen). --- ## 5. Docs lookup contract For any feature question not in our local catalog (`cometchat features info`), the canonical CometChat docs are the source of truth for: - **Feature/method availability matrix** — [Features & Extensions Guide](https://www.cometchat.com/docs/fundamentals/features-and-extensions-guide): which of UI Kit / UI Kit Builder / Widget Builder / SDK supports each feature, dashboard setup, and code-required flags. **This page outranks the local `catalog.json` snapshot when they disagree.** - Per-feature SDK reference (props, callbacks, builders, events) - Per-feature configuration details beyond the dashboard path above - Feature compatibility notes (which features need backend setup, which auto-wire, which require explicit `setExtensions([...])`) The docs MCP at `cometchat-docs` is the **best** way to query them when available, but it is **not** a hard requirement. **Hard rules:** 1. **Look up the docs before answering** any feature question that's not in our local catalog. Never invent feature config from training-data memory. Use whichever lookup path is available, in order: - **(a) docs MCP** — query the `cometchat-docs` MCP tool if your agent has it. Richest path. - **(b) install the MCP, if your agent supports it** — Claude Code: `claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp`. Other agents (Cursor, Codex, Cline, …) configure MCP their own way, or not at all — do NOT block. - **(c) fetch/search the public docs** — same content at the canonical URLs below, or web-search `site:cometchat.com/docs`. Universal fallback; never STOP and dead-end the user when the MCP isn't installed — fall through to (c). 2. **Use `cometchat apply-feature ` for extension and ai-feature types.** The CLI is the canonical path. Only fall back to the dashboard URL when the CLI returns `manual-action-required`, `auth-required`, or `error`. 4. **Canonical reference URLs** (use as starting points if the agent doesn't have an MCP query handy): - Extensions: https://www.cometchat.com/docs/ui-kit/react/extensions - AI features: https://www.cometchat.com/docs/ui-kit/react/ai-features - Calls: https://www.cometchat.com/docs/ui-kit/react/call-features - Core features: https://www.cometchat.com/docs/ui-kit/react/core-features --- ## 6. Steps ### Step 1 — Read state ```bash npx @cometchat/skills-cli info --json ``` If not integrated, stop. Otherwise note the framework + experience so you can find the right files. ### Step 2 — Determine feature If the user named a feature, use it. Otherwise list the categories above and ask which feature they want. ### Step 3 — Classify the feature Match the feature name against the 4 types in section 4. If you don't know the type, query the docs MCP first. ### Step 4 — Execute the right sub-flow - **Default:** show the user it's already there. Point at the component. Use `npx @cometchat/skills-cli features info ` to surface the walkthrough verbatim. - **CRITICAL — if the user explicitly wants a UI element to surface the default feature** (e.g. "implement conversation search", "add a search bar", "show typing indicators in the header", "expose mentions in the composer"), **do NOT add a new component yet**. Most default features are exposed via PROPS on the components your integration already mounts: - "search bar" → `showSearchBar` on `CometChatConversations` (and `onSearchBarClicked` to swap in `` for advanced dual-scope search if the user wants that) - "filter conversations / messages" → `conversationsRequestBuilder` / `messagesRequestBuilder` - "custom empty / error / loading state" → `emptyView`, `errorView`, `loadingView` on the list components (verified vs the v6 React kit; the `*StateView` form is only on `CometChatNotificationFeed`) - "custom message bubble" → `templates` prop on `CometChatMessageList` (NOT a custom bubble component) - "hide / disable a sub-feature" → `disable*` boolean props - "click handler" → `onItemClick`, `onMessageClick`, `onSearchBarClicked`, `onBack` - "custom subtitle / status / timestamp" → `subtitleView`, `statusView`, `timestampView` Process before any code change: 1. Read the files in `.cometchat/state.json` `files_owned` and grep for the `/dev/null) \ 2>/dev/null | sort -u ``` 2. Query the docs MCP for `" props"` for each one. 3. If a prop matches the user's intent, **add the prop and stop**. No new components, no custom CSS, no new files. 4. Only if no prop matches, route to the `cometchat-customization` skill for the full four-tier discovery. - **Extension / AI feature:** run `cometchat apply-feature `. The CLI hits the dashboard API directly using the bearer token from `cometchat auth login` (stored in the OS keychain). For native cohorts (iOS / Android / Flutter / Angular), pass `--app-id ` explicitly because there's no `.cometchat/state.json`. AI features also take `--openai-key sk-…` the first time: ```bash # Web/RN (state.json present): cometchat apply-feature polls cometchat apply-feature smart-replies --openai-key sk-... # Native (stateless): cometchat apply-feature polls --app-id A1B2C3 cometchat apply-feature smart-replies --app-id A1B2C3 --openai-key sk-... ``` Response shapes (`--json`): - `"status": "applied"` → done. Tell the user to hard-refresh (Cmd+Shift+R) the browser tab running their dev server. - `"status": "already-applied"` → the feature is already enabled in this integration's `state.applied_features`. - `"status": "auth-required"` → run `cometchat auth login` first. - `"status": "openai-key-required"` (ai-feature only) → re-run with `--openai-key sk-…`. - `"status": "error"` → surface `next_steps` verbatim. **Only fall back to the dashboard** when the CLI returns `error` or isn't available. Manual flow for extensions: app.cometchat.com → *Chat & Messaging → Features → flip Status toggle*. **Note:** if the feature has `auto_wired_in_uikit: false` in the catalog (most non-default extensions), the toggle alone isn't enough — you also need to register the extension via `UIKitSettingsBuilder.setExtensions([...])` before `init`. Query the docs MCP for the exact builder syntax. - **Dashboard-only:** the CLI returns `manual-action-required` and prints the dashboard path. These need third-party config (Giphy API key, Chatwoot webhook, etc.) that only the user can supply. Walk them through the dashboard. - **Package-install (calls):** run `npm install @cometchat/calls-sdk-javascript` directly. The user opted in, that IS consent. - **Component-swap:** run `cometchat apply-feature ` (web/RN only — needs `state.json`). The CLI handles the swap deterministically. Do NOT hand-edit. ### Step 5 — Verify ```bash npx @cometchat/skills-cli verify --json ``` Surface any failed checks verbatim. If anything looks off after enabling a feature (drift, unexpected build error, env warning), run `cometchat doctor` for combined drift + env + AST diagnostics with per-issue fix instructions, or route to the `cometchat-troubleshooting` skill for deeper triage. ## Hard rules - Never modify a project without an existing CometChat integration. - Always query the docs MCP for SDK reference (do not invent function names). - For component-swap, extension, and ai-feature types, always use `cometchat apply-feature ` — the CLI is the source of truth, never hand-edit and never tell the user to navigate the dashboard unless the CLI itself returns `manual-action-required`. - For ai-feature types, the OpenAI key prerequisite is the only manual input — pass it as `--openai-key sk-…` the first time per app. - For native cohorts (iOS / Android / Flutter / Angular), always pass `--app-id ` because their projects don't write `.cometchat/state.json`. - For package-install features (calls), the user opting in IS consent — run `npm install ` directly. - For dashboard-only features (third-party API keys, webhooks, multi-field config), walk the user through the dashboard — these cannot be automated. - Always use `npx @cometchat/skills-cli`. ## Sources - [Core features](https://www.cometchat.com/docs/ui-kit/react/core-features) - [Extensions](https://www.cometchat.com/docs/ui-kit/react/extensions) - [AI features](https://www.cometchat.com/docs/ui-kit/react/ai-features) - [Call features](https://www.cometchat.com/docs/ui-kit/react/call-features)