unpinAllChatMessages

Returns: TrueOfficial docs ↗

Use this method to clear the list of pinned messages in a chat. In private chats and channel direct messages chats, no additional rights are required to unpin all pinned messages. Conversely, the bot must be an administrator with the 'can_pin_messages' right or the 'can_edit_messages' right to unpin all pinned messages in groups and channels respectively. Returns True on success.

Parameters

chat_idIntegerStringRequired

Unique identifier for the target chat or username of the target channel (in the format @channelusername)

Returns

On success, True is returned.

GramIO Usage

Clear all pinned messages from a command handler:

bot.command("clearpin", async (ctx) => {
  await bot.api.unpinAllChatMessages({
    chat_id: ctx.chat.id,
  });

  await ctx.send("All pinned messages have been cleared.");
});

Unpin all messages in a channel by username:

async function clearChannelPins(channelUsername: string) {
  await bot.api.unpinAllChatMessages({
    chat_id: `@${channelUsername}`,
  });
}

Safely clear pins with error handling for missing rights:

bot.command("clearpin", async (ctx) => {
  try {
    await bot.api.unpinAllChatMessages({
      chat_id: ctx.chat.id,
    });
    await ctx.send("All pinned messages cleared.");
  } catch (error) {
    await ctx.send(
      "Could not clear pins — make sure I have the right admin permissions."
    );
  }
});

Errors

Code	Error	Cause
400	Bad Request: chat not found	chat_id is invalid or the bot is not a member of the chat
400	Bad Request: not enough rights to unpin messages	Bot lacks can_pin_messages (groups/supergroups) or can_edit_messages (channels)
403	Forbidden: bot is not an administrator	The bot has no admin status in the chat — promote it first
429	Too Many Requests: retry after N	Rate limit hit — check retry_after, use the auto-retry plugin

TIP

Use GramIO's auto-retry plugin to handle 429 errors automatically.

Tips & Gotchas

• Required rights differ by chat type. In groups and supergroups, the bot needs can_pin_messages. In channels it needs can_edit_messages. In private chats and channel direct messages chats, no rights are needed.
• This is irreversible. All pinned messages are removed at once with no undo. If you only want to remove one, use unpinChatMessage with a specific message_id.
• Messages themselves are not deleted. Unpinning removes messages from the pinned list but does not delete them from the chat history.
• Use unpinChatMessage for granular control. To remove a single pinned message without clearing the whole list, use unpinChatMessage and specify message_id.
• Forum topics have their own unpin methods. To unpin messages inside a specific forum topic, use unpinAllForumTopicMessages with the message_thread_id. For the General topic, use unpinAllGeneralForumTopicMessages.

See Also

• unpinChatMessage — Remove a single specific pinned message
• pinChatMessage — Pin a message in a chat
• unpinAllForumTopicMessages — Clear pins inside a forum topic
• unpinAllGeneralForumTopicMessages — Clear pins in the General forum topic
• getChatMember — Verify bot's admin rights before attempting