Pin A Message

AI Integration Quick Reference

// Pin / unpin a message
const pinned = await CometChat.pinMessage(messageId);
const unpinned = await CometChat.unpinMessage(messageId);

// Fetch the pinned list for one conversation
const request = new CometChat.MessagesRequestBuilder()
  .setUID("UID")          // or .setGUID("GUID")
  .setPinnedOnly(true)
  .setLimit(50)
  .build();
const messages = await request.fetchPrevious();

// Read pin state off a message — there is no isPinned()
const isPinned = message.getPinnedAt() !== undefined;

// Caps and availability
const limit = await CometChat.getPinMessageLimit();          // number | null
const enabled = await CometChat.isPinMessageEnabled();       // boolean

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, Moderator or group Owner 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.

A just-sent message may not be pinnable or savable yet. On an app with moderation enabled, the server stamps a new message moderation.status: "pending" and clears it to "approved" a moment later. While it is pending, pinMessage() rejects with 403 ERR_MESSAGE_NO_ACCESS — the same code it returns for a genuine permission refusal, so you cannot tell the two apart from the error alone.Measured on a moderated app, the window runs from send, not from the user’s tap, and clears within a few seconds. Do not disable the control on this error: by the time someone opens a menu and taps, moderation has usually finished. Prefer a retry or a transient “not ready yet” message over telling the user they lack permission. Moderation is configured per app, so this never reproduces on an app that has it switched off.

On a cap breach the rejection carries the server-owned ceiling in errorParams.limit, so you can tell the user the actual number without a second call.

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

Any Admin, Moderator or Owner may unpin — not only whoever pinned it. 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 setPinnedOnly(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 (User)
JavaScript (User)
TypeScript (Group)
JavaScript (Group)

let messagesRequest: CometChat.MessagesRequest =
  new CometChat.MessagesRequestBuilder()
    .setUID("cometchat-uid-1")
    .setPinnedOnly(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()
  .setUID("cometchat-uid-1")
  .setPinnedOnly(true)
  .setLimit(50)
  .build();

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

let messagesRequest: CometChat.MessagesRequest =
  new CometChat.MessagesRequestBuilder()
    .setGUID("cometchat-guid-1")
    .setPinnedOnly(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")
  .setPinnedOnly(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. The default value for setLimit is 30 and the max value is 100. Page it like any other message list: fetchPrevious() for older rows, fetchNext() for newer, stopping when a call resolves []. The one difference is invisible to you — the cursor rides on pinnedAt instead of sentAt, and the SDK swaps it for you.

Check if a Message is Pinned

Every BaseMessage carries its pin state as attributes. The React Native SDK has no isPinned() helper — the presence of pinnedAt is the boolean, and an unpinned message simply has no pin attributes.

TypeScript
JavaScript

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

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

  // An admin/global pin is stamped with the reserved "app_system" pinner
  // rather than a real UID — render it as a system pin, not as a user.
  const isSystemPinned: boolean = message.getPinnedBy() === "app_system";
}

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

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

  // An admin/global pin is stamped with the reserved "app_system" pinner
  // rather than a real UID — render it as a system pin, not as a user.
  const isSystemPinned = message.getPinnedBy() === "app_system";
}

Method	Returns
`getPinnedAt()`	The pin timestamp, or `undefined` when the message is not pinned.
`getPinnedBy()`	The UID of the most recent pinner, or `undefined`.

Do not port isPinned() or isSystemPinned() from the JavaScript SDK — they do not exist in the React Native SDK. Derive both from getPinnedAt() and getPinnedBy() as shown above.

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 getPinnedAt() and getPinnedBy() are readable without a follow-up fetch — replace the message in your list directly. Remove the listener when the screen unmounts:

TypeScript
JavaScript

CometChat.removeMessageListener("UNIQUE_LISTENER_ID");

CometChat.removeMessageListener("UNIQUE_LISTENER_ID");

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.getPinMessageLimit();
let systemLimit: number | null = await CometChat.getSystemPinMessageLimit();

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

CometChat.getPinMessageLimit().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. getSystemPinMessageLimit() is the separate cap for admin/global pins: system pins do not consume a user’s allowance, so the two budgets are enforced independently.

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