Pin A Conversation

Pinning a conversation keeps it at the top of the logged-in user’s conversation list. The pin is private to that user — nobody else sees it — and it syncs to their other devices.

This is separate from an admin-global pin, which is managed from the CometChat Dashboard and shows for every user. Those cannot be created or removed from the SDK, only observed.

A conversation is addressed by its peer — the other user’s UID for a one-on-one conversation, or the GUID for a group — together with the conversation type.

TypeScript
JavaScript

CometChat.pinConversation("cometchat-uid-1", CometChat.RECEIVER_TYPE.USER).then(
  (conversation: CometChat.Conversation) => {
    console.log("Conversation pinned:", conversation);
  },
  (error: CometChat.CometChatException) => {
    console.log("Failed to pin conversation:", error);
  }
);

CometChat.pinConversation("cometchat-guid-1", CometChat.RECEIVER_TYPE.GROUP).then(
  (conversation) => {
    console.log("Conversation pinned:", conversation);
  },
  (error) => {
    console.log("Failed to pin conversation:", error);
  }
);

It resolves with the full updated Conversation, with pinnedAt and pinnedBy set. Pinning is idempotent.

Addressing by peer rather than by conversationId is deliberate: it lets you pin a conversation that has no messages yet.

Unpin a Conversation

TypeScript
JavaScript

CometChat.unpinConversation(
  "cometchat-uid-1",
  CometChat.RECEIVER_TYPE.USER
).then(
  (conversation: CometChat.Conversation) => {
    console.log("Conversation unpinned:", conversation);
  },
  (error: CometChat.CometChatException) => {
    console.log("Failed to unpin conversation:", error);
  }
);

CometChat.unpinConversation(
  "cometchat-uid-1",
  CometChat.RECEIVER_TYPE.USER
).then(
  (conversation) => {
    console.log("Conversation unpinned:", conversation);
  },
  (error) => {
    console.log("Failed to unpin conversation:", error);
  }
);

A user cannot unpin an admin-global pin — that call is rejected with ERR_ACTION_NOT_ALLOWED. Hide or disable the unpin control for conversations you know are system-pinned.

Fetch Pinned Conversations

The default conversation list is already pin-ordered by the server: admin-global pins first, then the user’s own pins, then everything else. Fetch it as you normally would and no extra filter is needed. To narrow the list to pins only, use setPinnedBy() with the tokens on CometChat.PINNED_BY.

TypeScript
JavaScript

let conversationsRequest: CometChat.ConversationsRequest =
  new CometChat.ConversationsRequestBuilder()
    .setPinnedBy([CometChat.PINNED_BY.SYSTEM, CometChat.PINNED_BY.ME])
    .setLimit(30)
    .build();

conversationsRequest.fetchNext().then(
  (conversations: CometChat.Conversation[]) => {
    console.log("Pinned conversations:", conversations);
  },
  (error: CometChat.CometChatException) => {
    console.log("Failed to fetch conversations:", error);
  }
);

let conversationsRequest = new CometChat.ConversationsRequestBuilder()
  .setPinnedBy([CometChat.PINNED_BY.ME])
  .setLimit(30)
  .build();

conversationsRequest.fetchNext().then(
  (conversations) => {
    console.log("Pinned conversations:", conversations);
  },
  (error) => {
    console.log("Failed to fetch conversations:", error);
  }
);

Token	Meaning
`CometChat.PINNED_BY.ME`	Conversations the logged-in user pinned themselves.
`CometChat.PINNED_BY.SYSTEM`	Conversations pinned globally by an admin.

Passing an empty array is the same as not calling setPinnedBy() at all — you get the default, pin-ordered list.

Check if a Conversation is Pinned

TypeScript
JavaScript

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

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

As with messages, the presence of pinnedAt is the boolean — an unpinned conversation has no pin attributes at all.

Real-time Conversation Pin Events

Conversation pins arrive on a dedicated ConversationListener, not on MessageListener — the payload is a Conversation, not a message.

TypeScript
JavaScript

CometChat.addConversationListener(
  "UNIQUE_LISTENER_ID",
  new CometChat.ConversationListener({
    onConversationPinned: (conversation: CometChat.Conversation) => {
      console.log("Conversation pinned:", conversation);
    },
    onConversationUnpinned: (conversation: CometChat.Conversation) => {
      console.log("Conversation unpinned:", conversation);
    },
  })
);

CometChat.addConversationListener(
  "UNIQUE_LISTENER_ID",
  new CometChat.ConversationListener({
    onConversationPinned: (conversation) => {
      console.log("Conversation pinned:", conversation);
    },
    onConversationUnpinned: (conversation) => {
      console.log("Conversation unpinned:", conversation);
    },
  })
);

These fire both when the logged-in user pins from another device and when an admin pins globally. Remove the listener when you are done:

TypeScript
JavaScript

CometChat.removeConversationListener("UNIQUE_LISTENER_ID");

CometChat.removeConversationListener("UNIQUE_LISTENER_ID");

Pin Limit

TypeScript
JavaScript

let limit: number | null = await CometChat.getPinnedConversationsLimit();
let systemLimit: number | null =
  await CometChat.getSystemPinnedConversationsLimit();

CometChat.getPinnedConversationsLimit().then((limit) => {
  console.log("Pinned conversations limit:", limit);
});

Both resolve to null when the app settings carry no value. getSystemPinnedConversationsLimit() is the separate admin/global cap, enforced independently.

Feature Availability

TypeScript
JavaScript

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

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

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

Next Steps

Retrieve Conversations

Fetch and order the conversation list

Pin A Message

Highlight a message for everyone in a conversation

Save A Message

Bookmark a message privately, across conversations

All Real Time Listeners

Every listener the SDK exposes, in one place