unpinChatMessage

Returns: TrueOfficial docs ↗

Use this method to remove a message from the list of pinned messages in a chat. In private chats and channel direct messages chats, all messages can be unpinned. Conversely, the bot must be an administrator with the 'can_pin_messages' right or the 'can_edit_messages' right to unpin messages in groups and channels respectively. Returns True on success.

Parameters

business_connection_idStringOptional

Unique identifier of the business connection on behalf of which the message will be unpinned

chat_idIntegerStringRequired

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

message_idIntegerOptional

Identifier of the message to unpin. Required if business\connection\id is specified. If not specified, the most recent pinned message (by sending date) will be unpinned.

Returns

On success, True is returned.

GramIO Usage

Unpin the most recently pinned message (no message_id needed):

bot.command("unpin", async (ctx) => {
    // Unpins the most recently pinned message in this chat
    await bot.api.unpinChatMessage({
        chat_id: ctx.chat.id,
    });

    await ctx.send("Most recent pinned message has been unpinned.");
});

Unpin a specific message by its ID:

bot.command("unpin", async (ctx) => {
    const targetMessageId = ctx.replyMessage?.id;
    if (!targetMessageId) {
        return ctx.reply("Reply to the pinned message you want to unpin.");
    }

    await bot.api.unpinChatMessage({
        chat_id: ctx.chat.id,
        message_id: targetMessageId,
    });

    await ctx.send("Message unpinned.");
});

Unpin a message in a channel by username:

async function unpinChannelMessage(messageId: number) {
    await bot.api.unpinChatMessage({
        chat_id: "@mychannel",
        message_id: messageId,
    });
}

Unpin via a business connection (requires message_id):

bot.on("business_message", async (ctx) => {
    // When acting via a business connection, message_id is required
    await bot.api.unpinChatMessage({
        business_connection_id: ctx.businessConnectionId,
        chat_id: ctx.chat.id,
        message_id: ctx.id,
    });
});

Errors

Code	Error	Cause
400	Bad Request: chat not found	chat_id is invalid, the bot is not in the chat, or the chat no longer exists
400	Bad Request: message to unpin not found	message_id does not correspond to a currently pinned message or does not exist
400	Bad Request: not enough rights to unpin messages	Bot lacks can_pin_messages (groups/supergroups) or can_edit_messages (channels)
400	Bad Request: MESSAGE_ID_REQUIRED	business_connection_id was provided but message_id was omitted — business unpins require a specific message
403	Forbidden: bot is not an administrator	The bot has no admin status in the chat
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

• Omitting message_id unpins the most recently pinned message by sending date. This is useful for a simple /unpin command, but be careful in chats with multiple pins — you may unpin the wrong one.
• message_id is required when using business_connection_id. Business connection unpins always need an explicit target message.
• Required rights differ by chat type. Groups/supergroups need can_pin_messages; channels need can_edit_messages; private chats and channel direct messages need no special rights.
• To remove all pins at once, use unpinAllChatMessages. For forum topics, use unpinAllForumTopicMessages.
• message_id should be the pinned message's own ID. If you pass the ID of a message that is not currently pinned, you'll receive a message to unpin not found error.
• Business bots must pass the business_connection_id. When operating under a business connection, all admin-level actions require identifying the connection via this parameter.

See Also

• pinChatMessage — Pin a message in a chat
• unpinAllChatMessages — Clear all pinned messages in a chat at once
• unpinAllForumTopicMessages — Clear all pins inside a forum topic
• getChatMember — Verify the bot's admin rights before unpinning
• getBusinessConnection — Retrieve business connection details for business bots