unbanChatMember

Returns: TrueOfficial docs ↗

Use this method to unban a previously banned user in a supergroup or channel. The user will not return to the group or channel automatically, but will be able to join via link, etc. The bot must be an administrator for this to work. By default, this method guarantees that after the call the user is not a member of the chat, but will be able to join it. So if the user is a member of the chat they will also be removed from the chat. If you don't want this, use the parameter only_if_banned. Returns True on success.

Parameters

chat_idIntegerStringRequired

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

user_idIntegerRequired

Unique identifier of the target user

only_if_bannedBooleanOptional

Do nothing if the user is not banned

Returns

On success, True is returned.

GramIO Usage

Unban a user in response to a /unban command (reply to the target message):

bot.command("unban", async (ctx) => {
    const targetUserId = ctx.replyMessage?.from?.id;
    if (!targetUserId) {
        return ctx.reply("Reply to a message from the user you want to unban.");
    }

    await bot.api.unbanChatMember({
        chat_id: ctx.chat.id,
        user_id: targetUserId,
    });

    await ctx.reply("User has been unbanned and can rejoin via invite link.");
});

Use only_if_banned to safely unban without kicking active members:

bot.command("softunban", async (ctx) => {
    const targetUserId = ctx.replyMessage?.from?.id;
    if (!targetUserId) return;

    // only_if_banned: do nothing if the user is currently an active member
    await bot.api.unbanChatMember({
        chat_id: ctx.chat.id,
        user_id: targetUserId,
        only_if_banned: true,
    });

    await ctx.reply("Done — if the user was banned, they can now rejoin.");
});

Unban a user from a channel by username:

async function unbanFromChannel(userId: number) {
    await bot.api.unbanChatMember({
        chat_id: "@mychannel",
        user_id: userId,
        only_if_banned: true,
    });
}

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: user not found	user_id does not correspond to a known Telegram user
403	Forbidden: bot is not an administrator	The bot has no admin status in this chat — promote the bot first
403	Forbidden: not enough rights to restrict/ban chat member	The bot is an admin but lacks can_restrict_members — grant it in admin settings
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

• The user won't rejoin automatically. Unbanning only allows the user to rejoin via invite link or by being added by an admin — they are not re-added to the chat immediately.
• only_if_banned prevents accidental kicks. Without this flag, calling unbanChatMember on an active member will remove them from the chat. Always pass only_if_banned: true unless you explicitly intend to kick active members.
• Works only in supergroups and channels. Basic groups do not support persistent bans — user management there works differently.
• Bot must have can_restrict_members. Even for unbanning, the bot needs this administrator right. Verify with getChatMember if needed.
• Unbanning does not restore previous permissions. If the user had custom restrictions before being banned, those are cleared. They rejoin with default member permissions.

See Also

• banChatMember — Ban a user from a supergroup or channel
• unbanChatSenderChat — Unban a channel (sender chat) from posting
• banChatSenderChat — Ban a channel from posting in a supergroup
• restrictChatMember — Restrict specific member permissions without a full ban
• getChatMember — Check the current status of a member before taking action
• ChatMember — Union type for all member states including banned