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 @channelusername)

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.

unpinChatMessage ​

Parameters ​

Returns ​

GramIO Usage ​

Errors ​

Tips & Gotchas ​

See Also ​