Receive A Message

Receive real-time messages, fetch missed and unread messages, retrieve message history, search messages, and get unread counts using the CometChat JavaScript SDK.

Quick Reference for AI Agents & Developers

// Listen for real-time messages
CometChat.addMessageListener("LISTENER_ID", new CometChat.MessageListener({
  onTextMessageReceived: (msg) => {},
  onMediaMessageReceived: (msg) => {},
  onCustomMessageReceived: (msg) => {}
}));

// Fetch missed messages (while app was offline)
const latestId = await CometChat.getLastDeliveredMessageId();
const request = new CometChat.MessagesRequestBuilder()
  .setUID("UID").setMessageId(latestId).setLimit(30).build();
const messages = await request.fetchNext();

// Fetch message history
const request = new CometChat.MessagesRequestBuilder()
  .setUID("UID").setLimit(30).build();
const messages = await request.fetchPrevious();

// Get unread message count
const counts = await CometChat.getUnreadMessageCount();

Receiving messages with CometChat has two parts:

1. Adding a listener to receive real-time messages when your app is running
2. Calling a method to retrieve missed messages when your app was not running

Available via: SDK | REST API | UI Kits

Real-Time Messages

In other words, as a recipient, how do I receive messages when my app is running?

To receive real-time incoming messages, you need to register the MessageListener wherever you wish to receive the incoming messages. You can use the addMessageListener() method to do so.

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

Message Listener

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);
    },
  })
);

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);
    },
  })
);

Parameter	Description
listenerId	An ID that uniquely identifies that listener.

We recommend you remove the listener once you don’t want to receive a message for particular listener.

Remove Message Listener

let listenerID = "UNIQUE_LISTENER_ID";

CometChat.removeMessageListener(listenerID);

TypeScript

let listenerID: string = "UNIQUE_LISTENER_ID";

CometChat.removeMessageListener(listenerID);

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

Missed Messages

In other words, as a recipient, how do I receive messages that I missed when my app was not running?

For most use cases, you will need to add functionality to load missed messages. If you’re building an on-demand or live streaming app, you may choose to skip this and fetch message history instead.

Using the same MessagesRequest class and the filters provided by the MessagesRequestBuilder class, you can fetch the message that were sent to the logged-in user but were not delivered to him as he was offline. For this, you will require the id of the last message received. You can either maintain it at your end or use the getLastDeliveredMessageId() method provided by the CometChat class. This id needs to be passed to the setMessageId() method of the builder class.

Now using the fetchNext() method, you can fetch all the messages that were sent to the user when he/she was offline.

Calling the fetchNext() method on the same object repeatedly allows you to fetch all the offline messages for the logged in user.

Fetch Missed Messages of a particular one-on-one conversation

One-on-One Conversation

let UID = "UID";
let limit = 30;
let latestId = await CometChat.getLastDeliveredMessageId();

let messagesRequest = new CometChat.MessagesRequestBuilder()
  .setUID(UID)
  .setMessageId(latestId)
  .setLimit(limit)
  .build();

messagesRequest.fetchNext().then(
  (messages) => {
    console.log("Message list fetched:", messages);
  },
  (error) => {
    console.log("Message fetching failed with error:", error);
  }
);

TypeScript

let UID: string = "UID",
  limit: number = 30,
  latestId: number = await CometChat.getLastDeliveredMessageId(),
  messagesRequest: CometChat.MessagesRequest =
    new CometChat.MessagesRequestBuilder()
      .setUID(UID)
      .setMessageId(latestId)
      .setLimit(limit)
      .build();

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

Fetch Missed Messages of a particular group conversation

Group Conversation

let GUID = "GUID";
let limit = 30;
let latestId = await CometChat.getLastDeliveredMessageId();

let messagesRequest = new CometChat.MessagesRequestBuilder()
  .setGUID(GUID)
  .setMessageId(latestId)
  .setLimit(limit)
  .build();

messagesRequest.fetchNext().then(
  (messages) => {
    console.log("Message list fetched:", messages);
  },
  (error) => {
    console.log("Message fetching failed with error:", error);
  }
);

TypeScript

let GUID: string = "GUID",
  limit: number = 30,
  latestId: number = await CometChat.getLastDeliveredMessageId(),
  messagesRequest: CometChat.MessagesRequest =
    new CometChat.MessagesRequestBuilder()
      .setGUID(GUID)
      .setMessageId(latestId)
      .setLimit(limit)
      .build();

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

Unread Messages

In other words, as a logged-in user, how do I fetch the messages I’ve not read?

Using the MessagesRequest class described above, you can fetch the unread messages for the logged in user. In order to achieve this, you need to set the unread variable in the builder to true using the setUnread() method so that only the unread messages are fetched.

Fetch Unread Messages of a particular one-on-one conversation

One-on-One Conversation

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

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

TypeScript

let UID: string = "UID",
  limit: number = 30,
  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);
  }
);

Fetch Unread Messages of a particular group conversation

Group Conversation

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

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

TypeScript

let GUID: string = "GUID",
  limit: number = 30,
  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);
  }
);

Base Message

The list of messages received is in the form of objects of BaseMessage class. A BaseMessage can either be an object of the TextMessage, MediaMessage, CustomMessage, Action or Call class. You can use the instanceOf operator to check the type of object.

Message History

In other words, as a logged-in user, how do I fetch the complete message history?

Fetch Message History of a particular one-on-one conversation

Using the MessagesRequest class and the filters for the MessagesRequestBuilder class as shown in the below code snippet, you can fetch the entire conversation between the logged in user and any particular user. For this use case, it is mandatory to set the UID parameter using the setUID() method of the builder. This UID is the unique id of the user for which the conversation needs to be fetched.

One-on-One Conversation

let UID = "UID";
let limit = 30;
let messagesRequest = new CometChat.MessagesRequestBuilder()
  .setUID(UID)
  .setLimit(limit)
  .build();

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

TypeScript

let UID: string = "UID",
  limit: number = 30,
  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);
  }
);

Calling the fetchPrevious() method on the same object repeatedly allows you to fetch the entire conversation between the logged in user and the specified user. This can be implemented with upward scrolling to display the entire conversation.

Fetch Message History of a particular group conversation

Using the MessagesRequest class and the filters for the MessagesRequestBuilder class as shown in the below code snippet, you can fetch the entire conversation for any group provided you have joined the group. For this use case, it is mandatory to set the GUID parameter using the setGUID() method of the builder. This GUID is the unique identifier of the Group for which the messages are to be fetched.

Group Conversation

let GUID = "GUID";
let limit = 30;
let messagesRequest = new CometChat.MessagesRequestBuilder()
  .setGUID(GUID)
  .setLimit(limit)
  .build();

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

TypeScript

let GUID: string = "GUID",
  limit: number = 30,
  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);
  }
);

Calling the fetchPrevious() method on the same object repeatedly allows you to fetch the entire conversation for the group. This can be implemented with upward scrolling to display the entire conversation.

Search Messages

In other words, as a logged-in user, how do I search a message?

In order to do this, you can use the setSearchKeyword() method. This method accepts string as input. When set, the SDK will fetch messages which match the searchKeyword.

By default, the searchKey is searched only in message text. However, if you enable Conversation & Advanced Search, the searchKey will be searched in message text, file name, mentions & mime type of the file.

The Conversation & Advanced Search is only available in Advanced & Custom plans. If you’re already on one of these plans, please enable the Conversation & Advanced Search from CometChat Dashboard (Open your app, navigate to Chats -> Settings -> General Configuration)

Feature	Basic Search	Advance Search
Text search	✅	✅
File name search	❌	✅
Mentions search	❌	✅
Mime type search	❌	✅

Search Messages in a particular one-on-one conversation

One-on-One Conversation

let UID = "UID";
let limit = 30;
let searchKeyword = "Hello";
let messagesRequest = new CometChat.MessagesRequestBuilder()
  .setUID(UID)
  .setLimit(limit)
  .setSearchKeyword(searchKeyword)
  .build();

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

TypeScript

let UID: string = "UID",
  limit: number = 30,
  searchKeyword: string = "Hello",
  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);
  }
);

Search Messages in a particular group conversation

Group Conversation

let GUID = "GUID";
let limit = 30;
let searchKeyword = "Hello";
let messagesRequest = new CometChat.MessagesRequestBuilder()
  .setGUID(GUID)
  .setLimit(limit)
  .setSearchKeyword(searchKeyword)
  .build();

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

TypeScript

let GUID: string = "GUID",
  limit: number = 30,
  searchKeyword: string = "Hello",
  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);
  }
);

Unread Message Count

In other words, as a logged-in user, how do I find out the number of unread messages that I have?

Fetch Unread Message Count of a particular one-on-one conversation

In other words, how do I find out the number of unread messages I have from a particular user?

In order to get the unread message count for a particular user, you can use the getUnreadMessageCountForUser().

This method has the below two variants:

User

CometChat.getUnreadMessageCountForUser(UID);

TypeScript

let UID: string = "UID";
CometChat.getUnreadMessageCountForUser(UID);

If you wish to ignore the messages from blocked users you can use the below syntax setting the boolean parameter to true:

User

CometChat.getUnreadMessageCountForUser(UID, hideMessagesFromBlockedUsers);

TypeScript

let UID: string = "UID",
  hideMessagesFromBlockedUsers: boolean = true;
CometChat.getUnreadMessageCountForUser(UID, hideMessagesFromBlockedUsers);

Get Unread Count For User

let UID = "UID";

CometChat.getUnreadMessageCountForUser(UID).then(
  (unreadMessageCountObject) => {
    console.log("Unread message count fetched", unreadMessageCountObject);
  },
  (error) => {
    console.log("Error in getting unread message count", error);
  }
);

TypeScript

let UID: string = "UID";

CometChat.getUnreadMessageCountForUser(UID).then(
  (unreadMessageCount: Object) => {
    console.log("Unread message count fetched", unreadMessageCount);
  },
  (error: CometChat.CometChatException) => {
    console.log("Error in getting unread message count", error);
  }
);

It will return an object which will contain the UID as the key and the unread message count as the value.

Fetch Unread Message Count of a particular group conversation

In other words, how do I find out the number of unread messages I have in a single group?

In order to get the unread message count for a particular group, you can use the getUnreadMessageCountForGroup().

This method has the below two variants:

Group

CometChat.getUnreadMessageCountForGroup(GUID);

TypeScript

let GUID: string = "GUID";
CometChat.getUnreadMessageCountForGroup(GUID);

If you wish to ignore the messages from blocked users you can use the below syntax setting the boolean parameter to true:

Group

CometChat.getUnreadMessageCountForGroup(GUID, hideMessagesFromBlockedUsers);

TypeScript

let GUID: string = "GUID",
  hideMessagesFromBlockedUsers: boolean = true;
CometChat.getUnreadMessageCountForGroup(GUID, hideMessagesFromBlockedUsers);

Get Unread Count For Group

let GUID = "GUID";

CometChat.getUnreadMessageCountForGroup(GUID).then(
  (unreadMessageCountObject) => {
    console.log("Unread message count fetched", unreadMessageCountObject);
  },
  (error) => {
    console.log("Error in getting unread message count", error);
  }
);

TypeScript

let GUID: string = "GUID";

CometChat.getUnreadMessageCountForGroup(GUID).then(
  (unreadMessageCount: Object) => {
    console.log("Unread message count fetched", unreadMessageCount);
  },
  (error: CometChat.CometChatException) => {
    console.log("Error in getting unread message count", error);
  }
);

It will return an object which will contain the GUID as the key and the unread message count as the value.

Fetch Unread Message Count of all one-on-one & group conversations

In other words, how do I find out the number of unread messages for every one-on-one and group conversation?

In order to get all the unread message count combined i.e unread message counts for all the users and groups, you can use the getUnreadMessageCount() method.

This method has two variants:

All Conversation

CometChat.getUnreadMessageCount();

TypeScript

CometChat.getUnreadMessageCount();

If you wish to ignore the messages from blocked users you can use the below syntax setting the boolean parameter to true:

All Conversation

CometChat.getUnreadMessageCount(hideMessagesFromBlockedUsers);

TypeScript

let hideMessagesFromBlockedUsers: boolean = true;
CometChat.getUnreadMessageCount(hideMessagesFromBlockedUsers);

Get Unread Count For All Conversation

CometChat.getUnreadMessageCount().then(
  (unreadMessageCountObject) => {
    console.log("Unread message count fetched", unreadMessageCountObject);
  },
  (error) => {
    console.log("Error in getting unread message count", error);
  }
);

TypeScript

CometChat.getUnreadMessageCount().then(
  (unreadMessageCount: Object) => {
    console.log("Unread message count fetched", unreadMessageCount);
  },
  (error: CometChat.CometChatException) => {
    console.log("Error in getting unread message count", error);
  }
);

It returns an object having two keys:

1. users - The value for this key holds another object that holds the UID as key and their corresponding unread message count as value.
2. groups - The value for this key holds another object that holds the GUID as key and their corresponding unread message count as value.

Fetch Unread Message Count of all one-on-one conversations

In order to fetch the unread message counts for just the users, you can use the getUnreadMessageCountForAllUsers() method. This method just like others has two variants:

For All User Conversation

CometChat.getUnreadMessageCountForAllUsers();

TypeScript

CometChat.getUnreadMessageCountForAllUsers();

If you wish to ignore the messages from blocked users you can use the below syntax setting the boolean parameter to true:

For All User Conversation

CometChat.getUnreadMessageCountForAllUsers(hideMessagesFromBlockedUsers);

TypeScript

let hideMessagesFromBlockedUsers: boolean = true;
CometChat.getUnreadMessageCountForAllUsers(hideMessagesFromBlockedUsers);

Get Unread Count For All User Conversation

CometChat.getUnreadMessageCountForAllUsers().then(
  (unreadMessageCountObject) => {
    console.log("Unread message count fetched", unreadMessageCountObject);
  },
  (error) => {
    console.log("Error in getting unread message count", error);
  }
);

TypeScript

CometChat.getUnreadMessageCountForAllUsers().then(
  (unreadMessageCount: Object) => {
    console.log("Unread message count fetched", unreadMessageCount);
  },
  (error: CometChat.CometChatException) => {
    console.log("Error in getting unread message count", error);
  }
);

It returns an object which will contain the UID as the key and the unread message count as the value.

Fetch Unread Message Count of all group conversations

In order to fetch the unread message counts for just the groups, you can use the getUnreadMessageCountForAllGroups() method. This method just like others has two variants:

For All Group Conversation

CometChat.getUnreadMessageCountForAllGroups();

TypeScript

CometChat.getUnreadMessageCountForAllGroups();

If you wish to ignore the messages from blocked users you can use the below syntax setting the boolean parameter to true:

For All Group Conversation

CometChat.getUnreadMessageCountForAllGroups(hideMessagesFromBlockedUsers);

TypeScript

let hideMessagesFromBlockedUsers: boolean = true;
CometChat.getUnreadMessageCountForAllGroups(hideMessagesFromBlockedUsers);

Get Unread Count For All Group Conversation

CometChat.getUnreadMessageCountForAllGroups().then(
  (unreadMessageCountObject) => {
    console.log("Unread message count fetched", unreadMessageCountObject);
  },
  (error) => {
    console.log("Error in getting unread message count", error);
  }
);

TypeScript

CometChat.getUnreadMessageCountForAllGroups().then(
  (unreadMessageCount: Object) => {
    console.log("Unread message count fetched", unreadMessageCount);
  },
  (error: CometChat.CometChatException) => {
    console.log("Error in getting unread message count", error);
  }
);

It returns an object which will contain the GUID as the key and the unread message count as the value.

Best Practices

• Remove listeners on cleanup: Always call removeMessageListener() when components unmount to prevent memory leaks
• Use unique listener IDs: Generate unique IDs per component/screen to avoid conflicts
• Handle all message types: Implement handlers for text, media, and custom messages
• Fetch missed messages on app resume: Call getLastDeliveredMessageId() and fetch messages since that ID
• Paginate message history: Use setLimit() with reasonable values (30-50) and call fetchPrevious() for more
• Filter by category/type: Use setCategories() and setTypes() to fetch only relevant messages

Troubleshooting

Issue	Cause	Solution
Not receiving messages	Listener not added	Verify addMessageListener() was called with correct ID
Duplicate messages	Multiple listeners	Ensure only one listener per ID; remove on unmount
Missing messages	App was offline	Use getLastDeliveredMessageId() + fetchNext() for missed messages
Wrong message count	Blocked users included	Use hideMessagesFromBlockedUsers parameter
History not loading	Wrong method	Use fetchPrevious() for history, fetchNext() for missed messages

---

Next Steps

Delivery & Read Receipts

Track when messages are delivered and read by recipients

Typing Indicators

Show real-time typing status in conversations