Pin A Message

Pinning highlights an important message in a conversation. A pin is conversation-wide and visible to everyone in that conversation, so it is the right tool for announcements, rules or a link everyone keeps asking for.

Pinning is a moderation action. Only an Admin or Moderator — a group owner included — may pin or unpin. The server is the authority: a member’s call is rejected with ERR_ACTION_NOT_ALLOWED.

Call pinMessage() with the message’s ID. It resolves with the full updated message, with pinnedAt and pinnedBy set.

TypeScript
JavaScript

let messageId: number = 100;

CometChat.pinMessage(messageId).then(
  (message: CometChat.BaseMessage) => {
    console.log("Message pinned:", message);
  },
  (error: CometChat.CometChatException) => {
    console.log("Failed to pin message:", error);
  }
);

let messageId = 100;

CometChat.pinMessage(messageId).then(
  (message) => {
    console.log("Message pinned:", message);
  },
  (error) => {
    console.log("Failed to pin message:", error);
  }
);

Pinning is idempotent, and a message has a single pinner: re-pinning an already pinned message updates pinnedBy and pinnedAt to the most recent pinner rather than failing.

Unpin a Message

TypeScript
JavaScript

CometChat.unpinMessage(100).then(
  (message: CometChat.BaseMessage) => {
    console.log("Message unpinned:", message);
  },
  (error: CometChat.CometChatException) => {
    console.log("Failed to unpin message:", error);
  }
);

CometChat.unpinMessage(100).then(
  (message) => {
    console.log("Message unpinned:", message);
  },
  (error) => {
    console.log("Failed to unpin message:", error);
  }
);

The resolved message comes back with its pin attributes cleared, so you can swap the rendered message straight into your list.

Fetch Pinned Messages

Build a MessagesRequest with setPinned(true). A pinned list belongs to one conversation, so pair it with setUID() for a one-on-one conversation or setGUID() for a group — exactly one of the two is required.

TypeScript
JavaScript

let messagesRequest: CometChat.MessagesRequest =
  new CometChat.MessagesRequestBuilder()
    .setUID("cometchat-uid-1")
    .setPinned(true)
    .setLimit(50)
    .build();

messagesRequest.fetchPrevious().then(
  (messages: CometChat.BaseMessage[]) => {
    console.log("Pinned messages:", messages);
  },
  (error: CometChat.CometChatException) => {
    console.log("Failed to fetch pinned messages:", error);
  }
);

let messagesRequest = new CometChat.MessagesRequestBuilder()
  .setGUID("cometchat-guid-1")
  .setPinned(true)
  .setLimit(50)
  .build();

messagesRequest.fetchPrevious().then(
  (messages) => {
    console.log("Pinned messages:", messages);
  },
  (error) => {
    console.log("Failed to fetch pinned messages:", error);
  }
);

The list is ordered by pin time, most recently pinned first — not by when the messages were sent. Render it in the order the SDK returns it.

A conversation can hold at most 100 pinned messages, so setLimit(100) fetches the whole list in a single call — which is what you want when showing a pinned count in a header.

Check if a Message is Pinned

Every BaseMessage carries its pin state. The presence of pinnedAt is the boolean — an unpinned message simply has no pin attributes.

TypeScript
JavaScript

if (message.isPinned()) {
  console.log("Pinned at:", message.getPinnedAt());
  console.log("Pinned by:", message.getPinnedBy());

  if (message.isSystemPinned()) {
    // Pinned globally by an admin from the Dashboard,
    // not by a member of the conversation
  }
}

if (message.isPinned()) {
  console.log("Pinned at:", message.getPinnedAt());
  console.log("Pinned by:", message.getPinnedBy());

  if (message.isSystemPinned()) {
    // Pinned globally by an admin from the Dashboard,
    // not by a member of the conversation
  }
}

Method	Returns
`isPinned()`	`true` when the message is pinned.
`getPinnedAt()`	The pin timestamp, or `undefined`.
`getPinnedBy()`	The UID of the most recent pinner, or `undefined`.
`isSystemPinned()`	`true` for an admin/global pin. Render it as a system pin, not as a user.

Real-time Pin Events

Pin and unpin are broadcast to everyone in the conversation. Add the callbacks to your existing MessageListener.

TypeScript
JavaScript

CometChat.addMessageListener(
  "UNIQUE_LISTENER_ID",
  new CometChat.MessageListener({
    onMessagePinned: (message: CometChat.BaseMessage) => {
      console.log("Message pinned:", message);
    },
    onMessageUnpinned: (message: CometChat.BaseMessage) => {
      console.log("Message unpinned:", message);
    },
  })
);

CometChat.addMessageListener(
  "UNIQUE_LISTENER_ID",
  new CometChat.MessageListener({
    onMessagePinned: (message) => {
      console.log("Message pinned:", message);
    },
    onMessageUnpinned: (message) => {
      console.log("Message unpinned:", message);
    },
  })
);

Each callback receives the full updated message, so you can replace the message in your list without a follow-up fetch.

Pin Limit

A conversation holds a capped number of pins, configurable per app. Read the cap rather than hard-coding it — it is tenant-overridable and will drift.

TypeScript
JavaScript

let limit: number | null = await CometChat.getPinnedMessagesLimit();
let systemLimit: number | null =
  await CometChat.getSystemPinnedMessagesLimit();

if (limit !== null && pinnedCount >= limit) {
  // Disable the pin control instead of letting the user hit the error
}

CometChat.getPinnedMessagesLimit().then((limit) => {
  if (limit !== null && pinnedCount >= limit) {
    // Disable the pin control instead of letting the user hit the error
  }
});

Both resolve to null when the app settings carry no value — show generic copy in that case rather than guessing a number. getSystemPinnedMessagesLimit() is the separate cap for admin/global pins, enforced independently of the per-user one.

Feature Availability

Check whether Pin Message is enabled for your app before showing pin actions.

TypeScript
JavaScript

let enabled: boolean = await CometChat.isPinMessageEnabled();

if (enabled) {
  // Show the Pin option
}

CometChat.isPinMessageEnabled().then((enabled) => {
  if (enabled) {
    // Show the Pin option
  }
});

This resolves false rather than rejecting when the flag is missing or settings are unavailable, so an unavailable setting degrades to “hidden” instead of an unhandled rejection.

Next Steps

Save A Message

Bookmark a message privately, across conversations

Pin A Conversation

Pin a conversation to the top of the list

All Real Time Listeners

Every listener the SDK exposes, in one place

Additional Message Filtering

Filter messages by pinned, saved, type, tags and more

​Pin a Message

​Unpin a Message

​Fetch Pinned Messages

​Check if a Message is Pinned

​Real-time Pin Events

​Pin Limit

​Feature Availability

​Next Steps

Save A Message

Pin A Conversation

All Real Time Listeners

Additional Message Filtering

Pin a Message

Unpin a Message

Fetch Pinned Messages

Check if a Message is Pinned

Real-time Pin Events

Pin Limit

Feature Availability

Next Steps