getChatMember

Returns: ChatMemberOfficial docs ↗

Use this method to get information about a member of a chat. The method is only guaranteed to work for other users if the bot is an administrator in the chat. Returns a ChatMember object on success.

Parameters

chat_idIntegerStringRequired

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

user_idIntegerRequired

Unique identifier of the target user

Returns

On success, the ChatMember object is returned.

GramIO Usage

// Check the membership status of the message sender
bot.command("status", async (ctx) => {
    if (!ctx.from) return;
    const member = await bot.api.getChatMember({
        chat_id: ctx.chat.id,
        user_id: ctx.from.id,
    });
    await ctx.send(`Your status: ${member.status}`);
});

// Utility: check if a user is an active (non-banned/non-left) member
async function isMember(chatId: number | string, userId: number) {
    const member = await bot.api.getChatMember({
        chat_id: chatId,
        user_id: userId,
    });
    return (["member", "administrator", "creator"] as const).includes(
        member.status as "member" | "administrator" | "creator",
    );
}

// Gate a command to admins only
bot.command("admin_only", async (ctx) => {
    if (!ctx.from) return;
    const member = await bot.api.getChatMember({
        chat_id: ctx.chat.id,
        user_id: ctx.from.id,
    });
    if (member.status !== "administrator" && member.status !== "creator") {
        return ctx.send("This command is for admins only.");
    }
    await ctx.send("Welcome, admin!");
});

// Verify channel subscription before granting bot access
bot.command("verify", async (ctx) => {
    if (!ctx.from) return;
    const member = await bot.api.getChatMember({
        chat_id: "@myprivatechannel",
        user_id: ctx.from.id,
    });
    const isSubscribed = ["member", "administrator", "creator"].includes(
        member.status,
    );
    await ctx.send(isSubscribed ? "Access granted!" : "Please subscribe first.");
});

Errors

Code	Error	Cause
400	Bad Request: chat not found	Invalid or inaccessible chat_id — bot must be a member
400	Bad Request: user not found	Invalid user_id or user has never interacted with the bot
400	Bad Request: USER_ID_INVALID	Malformed user ID
403	Forbidden: bot is not a member of the chat	Bot was removed from 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

• Only guaranteed for other users if the bot is an admin. For non-admin bots in groups, Telegram may return left for a user who is actually a member — always make the bot an admin for reliable membership checks.
• status is a discriminant for the ChatMember union. Possible values are "creator", "administrator", "member", "restricted", "left", and "kicked". Use it to narrow the type.
• restricted members have custom permission overrides. The ChatMemberRestricted subtype exposes individual permission flags like can_send_messages, can_send_media_messages, etc.
• Useful for subscription-gating. Combine with join request handling to verify a user is subscribed to a private channel before granting access to a bot feature.
• left vs kicked. A user who left voluntarily has status: "left", while a banned user has status: "kicked". Both mean the user is no longer in the chat.

See Also

• getChatAdministrators — list all admins at once
• getChatMemberCount — total member count
• banChatMember — ban a member
• restrictChatMember — restrict a member's permissions
• promoteChatMember — grant admin rights
• ChatMember — the returned union type