Campaigns - CometChat Docs

CometChat Campaigns lets you deliver targeted, rich notifications to users via an in-app notification feed. Each notification is a Card Schema JSON — a structured layout rendered natively by the CometChat Cards library. The SDK provides APIs to fetch feed items, listen for real-time delivery, mark items as read/delivered, report engagement, and retrieve unread counts.

Before using the SDK, set up your channels, categories, templates, and campaigns in the CometChat Dashboard. See the Dashboard Setup Guide for step-by-step instructions.

Key Concepts

Concept	Description
NotificationFeedItem	A single notification in the feed. Contains Card Schema JSON in its `content` field, a `category` for filtering, timestamps, and metadata.
NotificationCategory	A category label used for filter chips (e.g., “Promotions”, “Updates”).
Card Schema JSON	The fully rendered card layout (images, text, buttons) inside `NotificationFeedItem.getContent()`. Passed directly to the CometChat Cards renderer.
PushNotification	Represents a campaign push notification payload received via FCM/APNs.

How Cards Render in the Notification Feed

Each NotificationFeedItem has a content field containing an object — this is the Card Schema JSON. This JSON is passed directly to the CometChat Cards renderer library (@cometchat/cards-react-native). The rendering flow:

Fetch feed items via NotificationFeedRequestBuilder
For each item, extract item.getContent() — this is the Card Schema JSON
Convert to string: JSON.stringify(item.getContent())
Pass to the Cards renderer (CometChatCardView)
The renderer produces a native React Native view from the JSON

Card Schema JSON Structure

{
  "version": "1.0",
  "body": [
    { "type": "image", "id": "img_1", "url": "https://...", "height": 200 },
    { "type": "text", "id": "txt_1", "content": "Flash Sale!", "variant": "heading2" },
    { "type": "button", "id": "btn_1", "label": "Shop Now", "action": { "type": "openUrl", "url": "https://..." } }
  ],
  "style": { "background": {"light": "#FFFFFF", "dark": "#1E1E1E"}, "borderRadius": 12, "padding": 16 },
  "fallbackText": "Flash Sale! Shop Now: https://..."
}

The body array contains elements (text, image, button, row, column, etc.) rendered top-to-bottom. Interactive elements like buttons emit actions via a callback — the consumer handles navigation, deep links, or API calls.

Retrieve Notification Feed Items

Use NotificationFeedRequestBuilder to fetch a paginated list of feed items. Uses cursor-based pagination internally.

Build the Request

JavaScript
TypeScript

const request = new CometChat.NotificationFeedRequestBuilder()
  .setLimit(20)
  .build();

const request: CometChat.NotificationFeedRequest = new CometChat.NotificationFeedRequestBuilder()
  .setLimit(20)
  .build();

Builder Parameters

Method	Type	Default	Description
`setLimit(limit)`	number	20	Items per page (max 100)
`setReadState(state)`	FeedReadState	`FeedReadState.ALL`	Filter by `READ`, `UNREAD`, or `ALL`
`setCategory(category)`	string	null	Filter by category label
`setChannelId(channelId)`	string	null	Filter by channel
`setTags(tags)`	string[]	null	Filter by tags
`setDateFrom(date)`	string	null	ISO 8601 date — items sent on or after
`setDateTo(date)`	string	null	ISO 8601 date — items sent on or before

Fetch Items

JavaScript
TypeScript

request.fetchNext().then(
  (items) => {
    for (const item of items) {
      const cardJson = JSON.stringify(item.getContent());
      // Pass cardJson to CometChatCardView
    }
  },
  (error) => {
    console.error("Feed fetch error:", error.message);
  }
);

request.fetchNext().then(
  (items: CometChat.NotificationFeedItem[]) => {
    for (const item of items) {
      const cardJson: string = JSON.stringify(item.getContent());
      // Pass cardJson to CometChatCardView
    }
  },
  (error: CometChat.CometChatException) => {
    console.error("Feed fetch error:", error.message);
  }
);

Call fetchNext() repeatedly for pagination. When the server has no more items, subsequent calls return an empty array.

NotificationFeedItem Fields

Field	Type	Description
`getId()`	string	Unique item identifier
`getCategory()`	string	Notification category (e.g., “promotions”)
`getContent()`	object	Card Schema JSON — pass to CometChat Cards renderer
`getReadAt()`	number \| null	Unix timestamp when read, or null if unread
`getDeliveredAt()`	number \| null	Unix timestamp when delivered, or null
`getSentAt()`	number	Unix timestamp when sent
`getMetadata()`	`Record<string, any>`	Custom key-value metadata
`getTags()`	string[]	Tags for filtering
`getSender()`	string	Sender identifier
`getReceiver()`	string	Receiver identifier
`getReceiverType()`	string	Receiver type
`getIsRead()`	boolean	Whether the item has been read

Retrieve Notification Categories

Use NotificationCategoriesRequestBuilder to fetch available categories for filter chips.

JavaScript
TypeScript

const categoriesRequest = new CometChat.NotificationCategoriesRequestBuilder()
  .setLimit(50)
  .build();

categoriesRequest.fetchNext().then(
  (categories) => {
    for (const category of categories) {
      console.log("Category:", category.getLabel());
    }
  },
  (error) => {
    console.error("Categories fetch error:", error.message);
  }
);

const categoriesRequest: CometChat.NotificationCategoriesRequest =
  new CometChat.NotificationCategoriesRequestBuilder()
    .setLimit(50)
    .build();

categoriesRequest.fetchNext().then(
  (categories: CometChat.NotificationCategory[]) => {
    for (const category of categories) {
      console.log("Category:", category.getLabel());
    }
  },
  (error: CometChat.CometChatException) => {
    console.error("Categories fetch error:", error.message);
  }
);

NotificationCategory Fields

Field	Type	Description
`getId()`	string	Category identifier
`getLabel()`	string	Display name for filter UI

Real-Time Notification Feed Listener

Listen for new feed items arriving via WebSocket. This listener is independent from MessageListener, GroupListener, and CallListener.

JavaScript
TypeScript

CometChat.addNotificationFeedListener("feedListener", {
  onFeedItemReceived: (feedItem) => {
    console.log("New item:", feedItem.getId());
    const cardJson = JSON.stringify(feedItem.getContent());
    // Insert at top of feed and render
  },
});

CometChat.addNotificationFeedListener("feedListener", {
  onFeedItemReceived: (feedItem: CometChat.NotificationFeedItem) => {
    console.log("New item:", feedItem.getId());
    const cardJson: string = JSON.stringify(feedItem.getContent());
    // Insert at top of feed and render
  },
});

Remove the listener when no longer needed:

CometChat.removeNotificationFeedListener("feedListener");

Mark Feed Item as Read

Mark a single item as read. Idempotent — safe to call multiple times.

JavaScript
TypeScript

CometChat.markFeedItemAsRead(feedItem).then(
  () => { console.log("Marked as read"); },
  (error) => { console.error("Error:", error.message); }
);

CometChat.markFeedItemAsRead(feedItem).then(
  () => { console.log("Marked as read"); },
  (error: CometChat.CometChatException) => { console.error("Error:", error.message); }
);

Mark Feed Item as Delivered

Mark a single item as delivered. Idempotent.

JavaScript
TypeScript

CometChat.markFeedItemAsDelivered(feedItem).then(
  () => { /* Success */ },
  (error) => { console.error("Error:", error.message); }
);

CometChat.markFeedItemAsDelivered(feedItem).then(
  () => { /* Success */ },
  (error: CometChat.CometChatException) => { console.error("Error:", error.message); }
);

Mark Multiple Items as Delivered (Batch)

CometChat.markFeedItemsAsDelivered(feedItems).then(
  () => { /* Success */ },
  (error) => { console.error("Error:", error.message); }
);

Report Engagement

Report that a user engaged with a feed item (e.g., viewed, clicked, interacted). Idempotent.

JavaScript
TypeScript

CometChat.reportFeedEngagement(feedItem, "clicked").then(
  () => { /* Success */ },
  (error) => { console.error("Error:", error.message); }
);

CometChat.reportFeedEngagement(feedItem, "clicked").then(
  () => { /* Success */ },
  (error: CometChat.CometChatException) => { console.error("Error:", error.message); }
);

The interactionString parameter is a free-form string describing the engagement (e.g., "viewed", "clicked", "interacted").

Get Unread Count

Fetch the total number of unread notification feed items.

JavaScript
TypeScript

CometChat.getNotificationFeedUnreadCount().then(
  (result) => { console.log("Unread:", result.count); },
  (error) => { console.error("Error:", error.message); }
);

CometChat.getNotificationFeedUnreadCount().then(
  (result: { count: number }) => { console.log("Unread:", result.count); },
  (error: CometChat.CometChatException) => { console.error("Error:", error.message); }
);

Fetch Single Feed Item

Fetch a specific item by ID — useful for deep linking from push notifications.

JavaScript
TypeScript

CometChat.getNotificationFeedItem("item-id-123").then(
  (item) => {
    const cardJson = JSON.stringify(item.getContent());
    // Render the card
  },
  (error) => { console.error("Error:", error.message); }
);

CometChat.getNotificationFeedItem("item-id-123").then(
  (item: CometChat.NotificationFeedItem) => {
    const cardJson: string = JSON.stringify(item.getContent());
    // Render the card
  },
  (error: CometChat.CometChatException) => { console.error("Error:", error.message); }
);

Push Notification Tracking

When a campaign push notification arrives via FCM/APNs, use these methods to report delivery and click engagement.

Mark Push Notification as Delivered

Call this when the push notification is received:

JavaScript
TypeScript

const pushNotification = new CometChat.PushNotification(pushPayloadJson);

CometChat.markPushNotificationDelivered(pushNotification).then(
  () => { /* Success */ },
  (error) => { console.error("Error:", error.message); }
);

const pushNotification = new CometChat.PushNotification(pushPayloadJson);

CometChat.markPushNotificationDelivered(pushNotification).then(
  () => { /* Success */ },
  (error: CometChat.CometChatException) => { console.error("Error:", error.message); }
);

Mark Push Notification as Clicked

Call this when the user taps the push notification:

JavaScript
TypeScript

CometChat.markPushNotificationClicked(pushNotification).then(
  () => { /* Success */ },
  (error) => { console.error("Error:", error.message); }
);

CometChat.markPushNotificationClicked(pushNotification).then(
  () => { /* Success */ },
  (error: CometChat.CometChatException) => { console.error("Error:", error.message); }
);

PushNotification Fields

Field	Type	Description
`getId()`	string	Announcement ID from the push payload
`getAnnouncementId()`	string	Same as id (for clarity)
`getCampaignId()`	string \| null	Campaign ID if from a campaign
`getSource()`	string	Always `"campaign"` for notification feed pushes

FeedReadState Enum

Value	Description
`FeedReadState.READ`	Only read items
`FeedReadState.UNREAD`	Only unread items
`FeedReadState.ALL`	All items (default)

Rendering Cards

The content field of each NotificationFeedItem is a Card Schema JSON object. To render it natively, use the CometChat Cards library.

Add the Cards Dependency

npm install @cometchat/cards-react-native

If you’re using @cometchat/chat-uikit-react-native v5.3.6+, the cards library is included automatically as a dependency.

Render a Card from a Feed Item

import { CometChatCardView } from "@cometchat/cards-react-native";

function NotificationCard({ item }) {
  const cardJson = JSON.stringify(item.getContent());

  return (
    <CometChatCardView
      cardJson={cardJson}
      themeMode="auto"
      onAction={(event) => {
        switch (event.type) {
          case "openUrl":
            // Open URL in browser
            break;
          case "chatWithUser":
            // Navigate to chat with event.params.uid
            break;
          case "chatWithGroup":
            // Navigate to group chat with event.params.guid
            break;
        }
      }}
    />
  );
}

The Cards library is a pure renderer — it does not execute actions. Your code must handle action callbacks (opening URLs, navigating to chats, making API calls, etc.).

Supported Card Actions

When a user taps a button or link inside a card, the action callback receives one of these action types:

Action Type	Parameters	Description
`openUrl`	url, openIn	Open a URL in browser or webview
`chatWithUser`	uid	Navigate to 1:1 chat
`chatWithGroup`	guid	Navigate to group chat
`sendMessage`	text, receiverUid, receiverGuid	Send a text message
`copyToClipboard`	value	Copy text to clipboard
`downloadFile`	url, filename	Download a file
`initiateCall`	callType (audio/video), uid, guid	Start a call
`apiCall`	url, method, headers, body	Make an HTTP request
`customCallback`	callbackId, payload	App-specific logic

Card Messages

Besides the notification feed, the same Card Schema JSON can arrive as a chat message. A CardMessage is a message with category: "card" — created and sent via the Platform (REST) API or the Dashboard Bubble Builder. The SDK only receives card messages; it does not send them. Card messages are delivered through the onCardMessageReceived callback of the MessageListener, not through the notification feed listener. The payload from getCard() is the same Card Schema JSON described above, so you render it with the same CometChatCardView and handle the same card actions.

CardMessage Fields

Method	Return Type	Description
`getCard()`	object	The raw Card Schema JSON payload. Pass directly to the Cards renderer.
`getText()`	string	Preview text for push notifications and the conversation list.
`getFallbackText()`	string	Fallback text from inside the card (`card.fallbackText`), used for accessibility or when the renderer fails.
`getTags()`	`Array<string>`	Tags associated with this message.

TypeScript
JavaScript

CometChat.addMessageListener("unique_listener_id", {
  onCardMessageReceived: (cardMessage: CometChat.CardMessage) => {
    console.log("Card message received:", cardMessage.getId());
    const cardJson: string = JSON.stringify(cardMessage.getCard()); // same schema as feed cards
    const fallback: string = cardMessage.getFallbackText();
    const previewText: string = cardMessage.getText();
    // Pass cardJson to CometChatCardView
  },
});

CometChat.addMessageListener("unique_listener_id", {
  onCardMessageReceived: (cardMessage) => {
    console.log("Card message received:", cardMessage.getId());
    const cardJson = JSON.stringify(cardMessage.getCard()); // same schema as feed cards
    const fallback = cardMessage.getFallbackText();
    const previewText = cardMessage.getText();
    // Pass cardJson to CometChatCardView
  },
});

Card messages are receive-only. They are created and sent exclusively via the Platform (REST) API and Dashboard Bubble Builder. The SDK exposes the raw payload via getCard() — the CometChat Cards library is responsible for drawing the card UI.

​Key Concepts

​How Cards Render in the Notification Feed

​Card Schema JSON Structure

​Retrieve Notification Feed Items

​Build the Request

​Builder Parameters

​Fetch Items

​NotificationFeedItem Fields

​Retrieve Notification Categories

​NotificationCategory Fields

​Real-Time Notification Feed Listener

​Mark Feed Item as Read

​Mark Feed Item as Delivered

​Mark Multiple Items as Delivered (Batch)

​Report Engagement

​Get Unread Count

​Fetch Single Feed Item

​Push Notification Tracking

​Mark Push Notification as Delivered

​Mark Push Notification as Clicked

​PushNotification Fields

​FeedReadState Enum

​Rendering Cards

​Add the Cards Dependency

​Render a Card from a Feed Item

​Supported Card Actions

​Card Messages

​CardMessage Fields

Key Concepts

How Cards Render in the Notification Feed

Card Schema JSON Structure

Retrieve Notification Feed Items

Build the Request

Builder Parameters

Fetch Items

NotificationFeedItem Fields

Retrieve Notification Categories

NotificationCategory Fields

Real-Time Notification Feed Listener

Mark Feed Item as Read

Mark Feed Item as Delivered

Mark Multiple Items as Delivered (Batch)

Report Engagement

Get Unread Count

Fetch Single Feed Item

Push Notification Tracking

Mark Push Notification as Delivered

Mark Push Notification as Clicked

PushNotification Fields

FeedReadState Enum

Rendering Cards

Add the Cards Dependency

Render a Card from a Feed Item

Supported Card Actions

Card Messages

CardMessage Fields