Receive A Message

Receive real-time, unread, and historical messages with the CometChat JavaScript SDK.

AI Integration Quick Reference

Field	Value
Package	@cometchat/chat-sdk-javascript
Import	import { CometChat } from "@cometchat/chat-sdk-javascript";
Key methods	CometChat.addMessageListener(listenerID, new CometChat.MessageListener({...})) · new CometChat.MessagesRequestBuilder().setUID(UID).setLimit(limit).build() · messagesRequest.fetchPrevious() · CometChat.getUnreadMessageCount() · CometChat.getMessageDetails(messageId)
Key classes	CometChat.MessageListener · CometChat.MessagesRequestBuilder · CometChat.MessagesRequest · CometChat.BaseMessage (TextMessage · MediaMessage · CustomMessage)
Primary output	Real-time callbacks deliver the specific message subclass (TextMessage / MediaMessage / CustomMessage); fetchPrevious() resolves to Promise<CometChat.BaseMessage[]>; getMessageDetails() resolves to Promise<CometChat.BaseMessage>; unread-count methods resolve to a Promise of an ID→count object; all reject with CometChat.CometChatException
Listeners registered	MessageListener via CometChat.addMessageListener(listenerID, ...) / CometChat.removeMessageListener(listenerID) — callbacks shown: onTextMessageReceived, onMediaMessageReceived, onCustomMessageReceived
Prerequisites	SDK initialized via CometChat.init() and a logged-in user via CometChat.login()
Constraints	As a sender you do not receive your own message in a real-time event (though other devices of the same logged-in user do). Always remove listeners on unmount to avoid memory leaks and duplicate handling. Advanced search (file name, mentions, MIME type) requires the Conversation & Advanced Search feature
Related	Send a Message · Delivery & Read Receipts · All Real Time Listeners · Retrieve Conversations
Full reference	BaseMessage · TextMessage · MediaMessage · CustomMessage

Receiving messages with CometChat has two parts:

1. Adding a real-time listener to receive messages while your app is running
2. Fetching unread, or historical messages when your app starts up or the user scrolls back

The TypeScript and JavaScript APIs are identical — the only difference is type annotations (e.g., : string, : CometChat.BaseMessage[]). The Real-Time Messages section shows both for reference. The remaining sections use TypeScript only to keep things concise — just drop the type annotations for plain JavaScript.

​

Real-Time Messages

Register a MessageListener to receive incoming messages as they arrive. Each callback receives the specific message subclass — TextMessage, MediaMessage, or CustomMessage.

TypeScript

let listenerID: string = "UNIQUE_LISTENER_ID";

CometChat.addMessageListener(
listenerID,
new CometChat.MessageListener({
onTextMessageReceived: (textMessage: CometChat.TextMessage) => {
console.log("Text message received successfully", textMessage);
},
onMediaMessageReceived: (mediaMessage: CometChat.MediaMessage) => {
console.log("Media message received successfully", mediaMessage);
},
onCustomMessageReceived: (customMessage: CometChat.CustomMessage) => {
console.log("Custom message received successfully", customMessage);
},
})
);

JavaScript

let listenerID = "UNIQUE_LISTENER_ID";

CometChat.addMessageListener(
  listenerID,
  new CometChat.MessageListener({
    onTextMessageReceived: (textMessage) => {
      console.log("Text message received successfully", textMessage);
    },
    onMediaMessageReceived: (mediaMessage) => {
      console.log("Media message received successfully", mediaMessage);
    },
    onCustomMessageReceived: (customMessage) => {
      console.log("Custom message received successfully", customMessage);
    },
  })
);

Parameter	Description
listenerID	An ID that uniquely identifies that listener. Use the same ID to remove it later.

Remove the listener when you no longer need it:

CometChat.removeMessageListener("UNIQUE_LISTENER_ID");

Always remove listeners when they’re no longer needed (e.g., on component unmount). Failing to do so can cause memory leaks and duplicate event handling.

As a sender, you will not receive your own message in a real-time event. However, if a user is logged in on multiple devices, they will receive the event on the other devices.

With offline support enabled, a registered MessageListener also receives onMessagesSynced(messages) after the SDK catches up on reconnect. It carries updates to already-cached messages that changed while offline: reactions, edits, deletes and receipts. Messages that arrived while offline still come one at a time through the usual onTextMessageReceived, onMediaMessageReceived and other typed callbacks, with getSource() set to SYNC. See Stay in Sync.

​

Unread Messages

Fetch unread messages by adding setUnread(true) to the builder. Use fetchPrevious() to retrieve them.

One-on-One

let UID: string = "UID";
let limit: number = 30;

let messagesRequest: CometChat.MessagesRequest =
new CometChat.MessagesRequestBuilder()
.setUID(UID)
.setUnread(true)
.setLimit(limit)
.build();

messagesRequest.fetchPrevious().then(
(messages: CometChat.BaseMessage[]) => {
console.log("Message list fetched:", messages);
},
(error: CometChat.CometChatException) => {
console.log("Message fetching failed with error:", error);
}
);

Group

let GUID: string = "GUID";
let limit: number = 30;

let messagesRequest: CometChat.MessagesRequest =
  new CometChat.MessagesRequestBuilder()
    .setGUID(GUID)
    .setUnread(true)
    .setLimit(limit)
    .build();

messagesRequest.fetchPrevious().then(
  (messages: CometChat.BaseMessage[]) => {
    console.log("Message list fetched:", messages);
  },
  (error: CometChat.CometChatException) => {
    console.log("Message fetching failed with error:", error);
  }
);

Results are returned as BaseMessage objects, which may be instances of TextMessage, MediaMessage, CustomMessage, Action, or Call. Use the instanceof operator to check the type.

​

Message History

Fetch the full conversation history using fetchPrevious(). Call it repeatedly on the same request object to paginate — useful for implementing upward scrolling.

One-on-One

let UID: string = "UID";
let limit: number = 30;

let messagesRequest: CometChat.MessagesRequest =
new CometChat.MessagesRequestBuilder()
.setUID(UID)
.setLimit(limit)
.build();

messagesRequest.fetchPrevious().then(
(messages: CometChat.BaseMessage[]) => {
console.log("Message list fetched:", messages);
},
(error: CometChat.CometChatException) => {
console.log("Message fetching failed with error:", error);
}
);

Group

let GUID: string = "GUID";
let limit: number = 30;

let messagesRequest: CometChat.MessagesRequest =
  new CometChat.MessagesRequestBuilder()
    .setGUID(GUID)
    .setLimit(limit)
    .build();

messagesRequest.fetchPrevious().then(
  (messages: CometChat.BaseMessage[]) => {
    console.log("Message list fetched:", messages);
  },
  (error: CometChat.CometChatException) => {
    console.log("Message fetching failed with error:", error);
  }
);

The fetchPrevious() method returns an array of BaseMessage objects (which may be TextMessage, MediaMessage, or other subclasses).

​

Search Messages

With offline support on, this filter is answered by the server only; the cached page is empty.

Add setSearchKeyword() to the builder to filter messages by keyword.

One-on-One

let UID: string = "UID";
let limit: number = 30;
let searchKeyword: string = "Hello";

let messagesRequest: CometChat.MessagesRequest =
new CometChat.MessagesRequestBuilder()
.setUID(UID)
.setLimit(limit)
.setSearchKeyword(searchKeyword)
.build();

messagesRequest.fetchPrevious().then(
(messages: CometChat.BaseMessage[]) => {
console.log("Message list fetched:", messages);
},
(error: CometChat.CometChatException) => {
console.log("Message fetching failed with error:", error);
}
);

Group

let GUID: string = "GUID";
let limit: number = 30;
let searchKeyword: string = "Hello";

let messagesRequest: CometChat.MessagesRequest =
  new CometChat.MessagesRequestBuilder()
    .setGUID(GUID)
    .setLimit(limit)
    .setSearchKeyword(searchKeyword)
    .build();

messagesRequest.fetchPrevious().then(
  (messages: CometChat.BaseMessage[]) => {
    console.log("Message list fetched:", messages);
  },
  (error: CometChat.CometChatException) => {
    console.log("Message fetching failed with error:", error);
  }
);

​

Search Capabilities

By default, search only matches message text. With Conversation & Advanced Search enabled, it also matches file names, mentions, and MIME types.

Feature	Basic Search	Advanced Search
Text search	✅	✅
File name search	❌	✅
Mentions search	❌	✅
MIME type search	❌	✅

Conversation & Advanced Search is available on Advanced and Custom plans. Enable it from the CometChat Dashboard under Chats → Settings → General Configuration.

​

Unread Message Count

CometChat provides several methods to get unread counts at different scopes. All return a Promise that resolves with an object mapping IDs to counts.

Each method accepts an optional boolean parameter to exclude messages from blocked users.

Unread counts in large groups: Unread message counts are calculated only for groups with up to 300 members. See Properties and Constraints.

Method	Scope	Returns
getUnreadMessageCountForUser(UID)	Single user conversation	{ [UID]: count }
getUnreadMessageCountForGroup(GUID)	Single group conversation	{ [GUID]: count }
getUnreadMessageCountForAllUsers()	All user conversations	{ [UID]: count, ... }
getUnreadMessageCountForAllGroups()	All group conversations	{ [GUID]: count, ... }
getUnreadMessageCount()	Everything	{ users: { ... }, groups: { ... } }

​

Single Conversation

TypeScript

// One-on-one
let UID: string = "UID";
CometChat.getUnreadMessageCountForUser(UID).then(
  (count: Object) => console.log("Unread count:", count),
  (error: CometChat.CometChatException) => console.log("Error:", error)
);

// Group
let GUID: string = "GUID";
CometChat.getUnreadMessageCountForGroup(GUID).then(
(count: Object) => console.log("Unread count:", count),
(error: CometChat.CometChatException) => console.log("Error:", error)
);

JavaScript

// One-on-one
let UID = "UID";
CometChat.getUnreadMessageCountForUser(UID).then(
  (count) => console.log("Unread count:", count),
  (error) => console.log("Error:", error)
);

// Group
let GUID = "GUID";
CometChat.getUnreadMessageCountForGroup(GUID).then(
  (count) => console.log("Unread count:", count),
  (error) => console.log("Error:", error)
);

​

All Conversations

TypeScript

// All users and groups combined
CometChat.getUnreadMessageCount().then(
  (count: Object) => console.log("Unread count:", count),
  (error: CometChat.CometChatException) => console.log("Error:", error)
);

// All user conversations only
CometChat.getUnreadMessageCountForAllUsers().then(
(count: Object) => console.log("Unread count:", count),
(error: CometChat.CometChatException) => console.log("Error:", error)
);

// All group conversations only
CometChat.getUnreadMessageCountForAllGroups().then(
(count: Object) => console.log("Unread count:", count),
(error: CometChat.CometChatException) => console.log("Error:", error)
);

JavaScript

// All users and groups combined
CometChat.getUnreadMessageCount().then(
  (count) => console.log("Unread count:", count),
  (error) => console.log("Error:", error)
);

// All user conversations only
CometChat.getUnreadMessageCountForAllUsers().then(
  (count) => console.log("Unread count:", count),
  (error) => console.log("Error:", error)
);

// All group conversations only
CometChat.getUnreadMessageCountForAllGroups().then(
  (count) => console.log("Unread count:", count),
  (error) => console.log("Error:", error)
);

​

Excluding Blocked Users

Pass true as the last argument to any of the methods above:

TypeScript

CometChat.getUnreadMessageCountForUser(UID, true);

CometChat.getUnreadMessageCountForGroup(GUID, true);
CometChat.getUnreadMessageCount(true);
CometChat.getUnreadMessageCountForAllUsers(true);
CometChat.getUnreadMessageCountForAllGroups(true); ```
</Tab>
<Tab title="JavaScript">
```javascript CometChat.getUnreadMessageCountForUser(UID, true);
CometChat.getUnreadMessageCountForGroup(GUID, true);
CometChat.getUnreadMessageCount(true);
CometChat.getUnreadMessageCountForAllUsers(true);
CometChat.getUnreadMessageCountForAllGroups(true); ```
</Tab>
</Tabs>

## Get Message Details

Use `getMessageDetails()` to fetch a specific message by its ID. Returns the full message object ([`TextMessage`](/sdk/reference/messages#textmessage), [`MediaMessage`](/sdk/reference/messages#mediamessage), or [`CustomMessage`](/sdk/reference/messages#custommessage)).

<Tabs>
<Tab title="TypeScript">
```typescript
let messageId: string = "MESSAGE_ID";

CometChat.getMessageDetails(messageId).then(
(message: CometChat.BaseMessage) => {
console.log("Message details:", message);
},
(error: CometChat.CometChatException) => {
console.log("Error fetching message details:", error);
}
);

JavaScript

let messageId = "MESSAGE_ID";

CometChat.getMessageDetails(messageId).then(
  (message) => {
    console.log("Message details:", message);
  },
  (error) => {
    console.log("Error fetching message details:", error);
  }
);

Parameter	Type	Description
messageId	string	The ID of the message to fetch

Returns a BaseMessage object (which may be a TextMessage, MediaMessage, or CustomMessage).

​

Offline Behaviour

With offline support enabled, fetchPrevious() and fetchNext() accept a MessageFetchListener: onCachedMessages delivers a page from the on-device cache first (even when empty), then onServerMessages delivers the reconciled server copy. The cache answers a page only when every filter on the request is locally computable; a single server-only filter makes the cached page empty with no error, while the server phase still answers in full. Offline, the fetch ends with onError with code FAILED_TO_FETCH after the cached page. getMessageDetails() accepts a MessageDetailsListener and delivers a cached copy only when the message is cached. See Show Cached Data and the filter table.

---

​

Next Steps

Delivery & Read Receipts

Track when messages are delivered and read by recipients

Typing Indicators

Show real-time typing status in conversations