Pin A Conversation

AI Integration Quick Reference

// Pin / unpin — addressed by peer + type, not by conversationId
await CometChat.pinConversation("UID", CometChat.RECEIVER_TYPE.USER);
await CometChat.unpinConversation("GUID", CometChat.RECEIVER_TYPE.GROUP);

// The DEFAULT list is already pin-ordered — no filter needed.
// To narrow to pins only, pass the raw string tokens:
const request = new CometChat.ConversationsRequestBuilder()
  .setPinnedBy(["system", "me"])
  .setLimit(30)
  .build();

// Read pin state — there is no isPinned()
const isPinned = conversation.getPinnedAt() !== undefined;
const isSystemPinned = conversation.getPinnedBy() === "app_system";

// Cap and availability (off by default — must be mapped per app)
const limit = await CometChat.getPinConversationLimit();
const enabled = await CometChat.isPinConversationEnabled();

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.

Pin Conversation requires the features.ux.conversations.pinned.enabled flag, which is not seeded in any plan and must be mapped per app. Until it is, every call rejects with ERR_FEATURE_NOT_ACCESSIBLE. Gate your UI on isPinConversationEnabled() before showing the control.

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 (User)
JavaScript (User)
TypeScript (Group)
JavaScript (Group)

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-uid-1",
  CometChat.RECEIVER_TYPE.USER
).then(
  (conversation) => {
    console.log("Conversation pinned:", conversation);
  },
  (error) => {
    console.log("Failed to pin conversation:", error);
  }
);

CometChat.pinConversation(
  "cometchat-guid-1",
  CometChat.RECEIVER_TYPE.GROUP
).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.

A conversation that has never been messaged, or that is hidden, cannot be newly pinned — the call rejects with ERR_CONVERSATION_NOT_ACCESSIBLE. Pin from a conversation that already exists in the list.

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

Unpinning returns the conversation to its recency position. A user cannot unpin an admin-global pin — hide or disable the unpin control for conversations where getPinnedBy() is "app_system".

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. Each row already carries pinnedAt and pinnedBy, so a pinned strip usually needs no separate call. When you do want the pinned set standalone, use setPinnedBy().

TypeScript
JavaScript

let conversationsRequest: CometChat.ConversationsRequest =
  new CometChat.ConversationsRequestBuilder()
    .setPinnedBy(["system", "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(["system", "me"])
  .setLimit(30)
  .build();

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

Token	Meaning
`"me"`	Conversations the logged-in user pinned themselves.
`"system"`	Conversations pinned globally by an admin.

The match is exact and case-sensitive, and an unrecognised value is dropped silently rather than raising. setPinnedBy(["Me"]) leaves nothing behind, the pinnedBy parameter is omitted entirely, and you get the full conversation list back — not an error, and not a pinned-only list. Passing an empty array does the same thing. Use the lowercase tokens exactly as written above.

These are plain strings in the React Native SDK — there is no CometChat.PINNED_BY constant to import. The server rejects any other value with ERR_BAD_REQUEST — end users cannot query another user’s pins — so the builder drops unrecognised entries before the request is sent.

Check if a Conversation is Pinned

As with messages, the React Native SDK has no isPinned() helper — the presence of pinnedAt is the boolean.

TypeScript
JavaScript

const isPinned: boolean = conversation.getPinnedAt() !== undefined;

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

  // A user may not unpin an admin/global pin
  const isSystemPinned: boolean = conversation.getPinnedBy() === "app_system";
}

const isPinned = conversation.getPinnedAt() !== undefined;

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

  // A user may not unpin an admin/global pin
  const isSystemPinned = conversation.getPinnedBy() === "app_system";
}

Method	Returns
`getPinnedAt()`	The pin timestamp, or `undefined` when the conversation is not pinned.
`getPinnedBy()`	The pinner’s UID, or `"app_system"` for an admin/global pin, or `undefined`.

Keeping the List in Sync

On the device that performed the action, update your list from the Promise. Your own pin or unpin does not fire onConversationPinned / onConversationUnpinned on that device. Those callbacks fire on the user’s other devices when a pin arrives there, so register a ConversationListener to reorder the list without a refetch.

TypeScript
JavaScript

const conversation: CometChat.Conversation = await CometChat.pinConversation(
  "cometchat-uid-1",
  CometChat.RECEIVER_TYPE.USER
);

// The server accepted it — move the row yourself.
setConversations((prev) => reorderWithPinnedFirst(prev, conversation));

CometChat.pinConversation("cometchat-uid-1", CometChat.RECEIVER_TYPE.USER).then(
  (conversation) => {
    // The server accepted it — move the row yourself.
    setConversations((prev) => reorderWithPinnedFirst(prev, conversation));
  }
);

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.removeConversationListener("UNIQUE_LISTENER_ID");

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

CometChat.removeConversationListener("UNIQUE_LISTENER_ID");

Pin Limit

TypeScript
JavaScript

let limit: number | null = await CometChat.getPinConversationLimit();
let systemLimit: number | null = await CometChat.getSystemPinConversationLimit();

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

Both resolve to null when the app settings carry no value. getSystemPinConversationLimit() is the separate admin/global cap, enforced independently — system pins do not consume a user’s allowance.

The conversation pin cap and the message pin cap are separate quotas with different values, and both are server-owned and tenant-overridable. Read each one at runtime rather than assuming a number or reusing the other.

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

Unlike the two message-level flags, this one is not seeded anywhere and is off by default — treat a false as the normal case for a new app, not as an error.

Offline Behaviour

With offline support enabled, passing a ConversationFetchListener to fetchNext() on a setPinnedBy() request calls onCachedConversations first (even when the page is empty) and then onServerConversations with the live list. Offline, the read ends with onError (FAILED_TO_FETCH) after the cached page, and the Promise rejects. onCachedConversations holds the pinned conversations the cache already knows about, in the same order.

Builder method	Offline
`setPinnedBy`	Cached

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

Delete A Conversation

Remove a conversation from the list