cometchat-native-features by cometchat/cometchat-skills

Purpose

Teaches Claude how to add features on top of a working CometChat React Native integration. Classifies each feature into one of four types and gives the correct recipe for each.

Read cometchat-native-core + cometchat-native-components + (cometchat-native-expo-patterns or cometchat-native-bare-patterns) first — a base integration must already exist before features layer on.

Ground truth: docs/ui-kit/react-native/core-features.mdx, calling-integration.mdx, call-*.mdx, incoming-call.mdx, outgoing-call.mdx, extensions.mdx, guide-ai-agent.mdx, ai-assistant-chat-history.mdx, and @cometchat/chat-uikit-react-native@5.3.3 exports.

1. Feature taxonomy

Every CometChat feature falls into exactly one of four categories. The category determines the recipe:

Category	What it means	Example features	How to enable
Default	Already on — no action needed. Shipped with the kit's base components.	Instant messaging, typing indicators, read receipts, reactions on messages, replies, @mentions, media upload, edit/delete, message info	Just render `CometChatMessageHeader` + `CometChatMessageList` + `CometChatMessageComposer`
Dashboard-toggle	Flip an extension toggle in the CometChat dashboard (or via the CLI). UI Kit auto-wires the feature once enabled.	Polls, stickers, smart replies, message translation, link previews, collaborative whiteboard, collaborative document, thumbnail generation	Toggle on → hard-reload the app
Package-install	Install an additional npm package + maybe native peer deps. The UI Kit auto-detects the package on next init.	Voice + video calls (`@cometchat/calls-sdk-react-native`)	`npm install ...` → pod install (iOS) → rebuild
Component-swap	Replace or wrap a UI Kit component with a customized version.	Custom text formatter (emoji shortcuts, custom tags), custom message templates, AI Agent chat history	Write a new component + pass via prop

Reminder — don't confuse these with customization (per-skill-coverage under cometchat-native-customization). This skill is "add a feature that CometChat ships"; customization is "change how an existing feature looks or behaves".

2. Enabling dashboard-toggle features

Most extensions (polls, stickers, translation, link preview, smart replies, collaborative doc, collaborative whiteboard, thumbnails) are dashboard-toggle features. To enable one:

Option A — use the CLI (preferred — no dashboard trip)

npx @cometchat/skills-cli features list --json            # browse available features
npx @cometchat/skills-cli features info polls --json      # details for one
npx @cometchat/skills-cli features enable polls --json    # flip the toggle

The CLI reads the app ID from .cometchat/config.json and the bearer token from the OS keychain (requires a prior cometchat auth login). Response:

"status": "enabled" → done. Hard-reload (stop Metro + restart + rebuild if on iOS).
"status": "no-op" → already enabled.
"status": "not-logged-in" → cometchat auth login first.
"status": "no-app" → run /cometchat or cometchat provision setup first.
"status": "error" → surface next_steps — includes the dashboard URL as a manual fallback.

Only fall back to the dashboard walkthrough if the CLI errors.

Option B — dashboard (fallback when CLI isn't available)

https://app.cometchat.com → your app
Chat & Messaging → Features
Find the extension by name → flip Status ON
Hard-reload the RN app (stop Metro, restart, rebuild native if the extension adds native deps — most don't)

What each toggle does

Extension	UI surface when enabled
Polls	Polls option in `CometChatMessageComposer`'s attachment Action Sheet
Stickers	Sticker picker in the composer
Smart replies	Chip suggestions above the composer input after an incoming message
Message translation	"Translate" option in the message long-press menu
Link preview	Rich-card bubble for URLs in the message list
Collaborative document	Option in composer's Action Sheet; opens a shared doc on tap
Collaborative whiteboard	Option in composer's Action Sheet; opens a shared canvas
Thumbnail generation	Image / video bubbles show thumbnails instead of full-size downloads

Gotcha — `auto_wired_in_uikit: false`

A minority of extensions need extra wiring via the extensions field on CometChatUIKit.init(). The CLI flags this in its success response:

{
  "status": "enabled",
  "name": "stickers",
  "auto_wired_in_uikit": false,
  "next_steps": [
    "Pass the extension via the `extensions` field on CometChatUIKit.init({ ... })"
  ]
}

If auto_wired_in_uikit is false, import the matching ExtensionsDataSource from @cometchat/chat-uikit-react-native and pass it via the flat extensions field:

import {
  CometChatUIKit,
  StickersExtension,
  PollsExtension,
} from "@cometchat/chat-uikit-react-native";

await CometChatUIKit.init({
  appId: APP_ID,
  region: REGION,
  authKey: AUTH_KEY,
  subscriptionType: "ALL_USERS",
  extensions: [new StickersExtension(), new PollsExtension()],   // ← new
});

Query the docs MCP for the exact extension class name if you don't remember it — extensions.mdx lists all of them.

3. Calls (package-install)

Calls are the biggest "add a feature" step. They require the separate @cometchat/calls-sdk-react-native package, additional peer native modules (WebRTC + netinfo + background-timer + callstats), and app-side listener setup.

3a — Install the calls SDK + peer deps

Expo (managed workflow):

npm install @cometchat/calls-sdk-react-native
npx expo install \
  @react-native-community/netinfo \
  react-native-background-timer \
  react-native-callstats \
  react-native-webrtc
npx expo prebuild --clean

Bare RN:

npm install \
  @cometchat/calls-sdk-react-native \
  @react-native-community/netinfo \
  react-native-background-timer \
  react-native-callstats \
  react-native-webrtc
cd ios && pod install && cd ..

3b — Platform permissions (if not already from core integration)

iOS — ios/<App>/Info.plist:

<key>NSCameraUsageDescription</key>
<string>Camera access for video calls</string>
<key>NSMicrophoneUsageDescription</key>
<string>Microphone access for voice and video calls</string>

Android — android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

3c — iOS deployment target + build settings

Calls SDK requires iOS 12+ and specific Podfile flags. Add to ios/Podfile:

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '12.0'
      config.build_settings['EXCLUDED_ARCHS[sdk=iphonesimulator*]'] = 'arm64 i386'
      config.build_settings['ENABLE_BITCODE'] = 'NO'
    end
  end
end

Android (android/app/build.gradle):

android {
    compileSdkVersion 33
    defaultConfig {
        minSdkVersion 24
        targetSdkVersion 33
    }
}

3d — Register the call listener at app root

The incoming-call UI only shows up if you've registered a listener to pick up call events. Add this once at the app root (typically in App.tsx or Expo Router's _layout.tsx):

import React, { useEffect, useRef, useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { CometChatIncomingCall } from "@cometchat/chat-uikit-react-native";

function CallEventsProvider({ children }: { children: React.ReactNode }) {
  const [callReceived, setCallReceived] = useState(false);
  const incomingCall = useRef<CometChat.Call | null>(null);
  const LISTENER_ID = "APP_CALL_LISTENER";

  useEffect(() => {
    CometChat.addCallListener(
      LISTENER_ID,
      new CometChat.CallListener({
        onIncomingCallReceived: (call) => {
          incomingCall.current = call;
          setCallReceived(true);
        },
        onOutgoingCallAccepted: (call) => {
          // navigate to the ongoing-call screen
        },
        onOutgoingCallRejected: () => {
          incomingCall.current = null;
          setCallReceived(false);
        },
        onIncomingCallCancelled: () => {
          incomingCall.current = null;
          setCallReceived(false);
        },
        onCallEndedMessageReceived: () => {
          incomingCall.current = null;
          setCallReceived(false);
        },
      })
    );
    return () => CometChat.removeCallListener(LISTENER_ID);
  }, []);

  return (
    <>
      {children}
      {callReceived && incomingCall.current && (
        <CometChatIncomingCall
          call={incomingCall.current}
          onAccept={() => { /* navigate to ongoing-call screen */ }}
          onDecline={() => setCallReceived(false)}
        />
      )}
    </>
  );
}

Wrap the app (inside the existing provider chain, below CometChatProvider):

<CometChatProvider ...>
  <CallEventsProvider>
    <AppNavigator />
  </CallEventsProvider>
</CometChatProvider>

3e — Call buttons in the message header

Once the calls SDK is installed, CometChatMessageHeader auto-renders voice + video call buttons. To customize (e.g., hide one):

<CometChatMessageHeader
  user={selectedUser}
  hideVoiceCallButton={false}
  hideVideoCallButton={false}
  AuxiliaryButtonView={(user, group) => (
    <CometChatCallButtons
      user={user}
      group={group}
      onVoiceCallPress={(session) => navigation.navigate("OngoingCall", { session })}
      onVideoCallPress={(session) => navigation.navigate("OngoingCall", { session })}
    />
  )}
/>

3f — Ongoing call screen

Navigate to a dedicated screen that hosts CometChatOngoingCall when a call connects:

// OngoingCallScreen.tsx
import { CometChatOngoingCall } from "@cometchat/chat-uikit-react-native";

export function OngoingCallScreen({ route, navigation }: any) {
  const { session } = route.params;
  return (
    <CometChatOngoingCall
      sessionID={session.sessionId}
      callType={session.type}   // "audio" | "video"
      onCallEnded={() => navigation.goBack()}
    />
  );
}

3g — Call logs

A history view of past calls. Typically one tab in a tab-based layout (see cometchat-native-placement § 2):

import { CometChatCallLogs } from "@cometchat/chat-uikit-react-native";

export function CallLogsScreen() {
  return <CometChatCallLogs onItemPress={(callLog) => openCallDetails(callLog)} />;
}

3h — Verifying calls work

Rebuild the app after adding the calls SDK (Expo: expo run:ios / run:android; bare: npx react-native run-ios / run-android)
Log in as one user on device A, another on device B
On device A, tap the voice or video call icon in the message header
Device B should show CometChatIncomingCall within a few seconds
Accept on B → both devices transition to CometChatOngoingCall

If incoming calls don't show: listener not registered, or the listener ID collides. See cometchat-native-troubleshooting.

3i — Testing calls in CI

Real WebRTC calls can't run in Jest or Maestro — they need two real devices plus a TURN server. What you CAN test:

Call button renders — mount CometChatMessageHeader with a user prop and assert the call testID is present (requires the calls SDK import to not crash; mock @cometchat/calls-sdk-react-native in your jest setup).
Call listener registration — spy on CometChat.addCallListener from the SDK mock and assert your registerCallListener() fires exactly once per mount.
Incoming-call UI — render <CometChatIncomingCall call={mockCall} /> with a stubbed CometChat.Call object; assert accept/reject buttons are wired.

See cometchat-native-testing § 5 for the SDK mock shape (includes a addCallListener / removeCallListener stub) and § 10 for why actual call E2E belongs in manual QA, not Detox/Maestro.

4. In-call chat (optional, during-call feature)

During an active call, users can chat without leaving the call UI. This is a toggle on the ongoing-call component:

<CometChatOngoingCall
  sessionID={session.sessionId}
  callType={session.type}
  callSettingsBuilder={/* ... with enableInCallChat(true) */}
  onCallEnded={() => navigation.goBack()}
/>

In-call chat adds a collapsible chat panel to the call screen. Participants see messages for the duration of the call.

5. AI Agent (component-swap + dashboard)

The AI Agent integration adds an AI-powered conversational assistant to your app. Two parts:

5a — Dashboard setup

https://app.cometchat.com → your app → AI → Agents
Create a new agent (name, system prompt, model)
Assign a UID to the agent (e.g. ai-support-agent)

Once the agent exists in the dashboard, users can message it like any other user.

5b — Optional: AI Assistant Chat History UI

The UI Kit exports CometChatAIAssistantChatHistory for apps that want a dedicated AI-chat entry point (distinct from a regular chat with a human user). This component shows past AI conversations and a "New chat" trigger.

import { CometChatAIAssistantChatHistory } from "@cometchat/chat-uikit-react-native";

export function AIChatScreen({ navigation }: any) {
  return (
    <CometChatAIAssistantChatHistory
      user={loggedInUser}
      onMessageClicked={(message) => navigation.navigate("AIChat", { message })}
      onNewChatButtonClick={() => navigation.navigate("AIChat", { new: true })}
    />
  );
}

The actual AI-chat screen is a regular CometChatMessageHeader + MessageList + Composer composition targeted at the AI agent's UID.

5c — AI features beyond the basic agent

See ai-assistant-chat-history.mdx and guide-ai-agent.mdx in the docs for:

Multi-tool agents (tools registered via setAIAssistantTools())
Streaming responses (handled automatically via CometChatAIAssistantMessageBubble)
Agent memory and persona

These are advanced topics — query the docs MCP for the current API if the user wants any of them.

5d — Smart replies (custom chip UI)

Smart replies is a dashboard-toggle feature (Type 2). After enabling it (Extensions → Smart Replies → Toggle on), no code changes are required — CometChatMessageComposer automatically renders suggested replies as chips above the input.

For a custom UI — e.g. inline chips inside a custom bubble, only on certain conversation types, or styled to match your design system — read the extension data straight off the incoming message and render your own chips:

import { TouchableOpacity, View, Text } from "react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

interface SmartReply {
  reply_positive?: string;
  reply_neutral?: string;
  reply_negative?: string;
}

export function SmartReplyChips({
  message,
  onPick,
}: {
  message: CometChat.BaseMessage;
  onPick: (text: string) => void;
}) {
  const metadata = message.getMetadata() as Record<string, unknown> | undefined;
  const extensions = (metadata?.["@injected"] as Record<string, unknown>)?.["extensions"] as
    | Record<string, unknown>
    | undefined;
  const smartReply = extensions?.["smart-reply"] as SmartReply | undefined;
  if (!smartReply) return null;

  const replies = [
    smartReply.reply_positive,
    smartReply.reply_neutral,
    smartReply.reply_negative,
  ].filter(Boolean) as string[];

  return (
    <View style={{ flexDirection: "row", gap: 8, padding: 8 }}>
      {replies.map((r) => (
        <TouchableOpacity
          key={r}
          onPress={() => onPick(r)}
          style={{ paddingHorizontal: 12, paddingVertical: 6, borderRadius: 16, backgroundColor: "#EAEAEA" }}
        >
          <Text>{r}</Text>
        </TouchableOpacity>
      ))}
    </View>
  );
}

Smart replies are server-generated — the AI runs on CometChat's backend and attaches results to messages via the @injected.extensions.smart-reply metadata path. Your code just reads it.

Common gotchas:

Replies only appear on incoming messages (the recipient's view), not outgoing. The dashboard generates them when the message lands.
The metadata path is nested under @injected.extensions.smart-reply — not at the top level. Wrong path = undefined.
If the user disables smart replies in the dashboard later, your custom UI silently shows nothing (the metadata key is just absent). Add a fallback if "no chip" feels broken.

6. Core features (no new code, no new install)

The following are shipped by default in every CometChat integration — they work from day 1 without any feature-enabling step. Mention them to users who ask "what do I get out of the box?":

Instant messaging (text, with real-time delivery)
Media sharing (images, video, audio, files)
Read receipts (single tick = sent, double tick = delivered, blue = read)
Typing indicators
@mentions (requires CometChatMentionsFormatter in textFormatters, already in default config)
Reactions (long-press any message to add emoji reaction)
Replies (swipe or long-press → Reply)
Edit / delete own messages
Message info — sender sees delivery + read timestamps per-recipient
Mark as unread
Voice messages (record + send from composer)
Search (CometChatSearch component — scoped or global)
Group management (create, add members, leave, mute, transfer ownership)

If a user reports "X isn't working" for a core feature, it's likely a props issue (e.g., hideReceipts={true} accidentally set) or a dashboard setting, not a missing feature.

6a — Presence (online / offline) in custom UI

Presence indicators appear automatically on avatars in CometChatConversations, CometChatUsers, and CometChatGroupMembers — no setup. For custom UI that needs a specific user's status — e.g. a "Sold by Aria Chen · online now" label on a product screen — subscribe with the SDK directly:

import { useEffect, useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-react-native";

export function useUserPresence(uid: string): "online" | "offline" | "unknown" {
  const [status, setStatus] = useState<"online" | "offline" | "unknown">("unknown");

  useEffect(() => {
    let cancelled = false;

    // 1. Initial fetch
    CometChat.getUser(uid).then((u) => {
      if (cancelled) return;
      setStatus(u.getStatus() === "online" ? "online" : "offline");
    });

    // 2. Live updates
    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 () => {
      cancelled = true;
      CometChat.removeUserListener(listenerId);
    };
  }, [uid]);

  return status;
}

Use it: const status = useUserPresence(product.sellerUid);