promoteChatMember

Returns: TrueOfficial docs ↗

Use this method to promote or demote a user in a supergroup or a channel. The bot must be an administrator in the chat for this to work and must have the appropriate administrator rights. Pass False for all boolean parameters to demote a user. Returns True on success.

Parameters

chat_idIntegerStringRequired

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

user_idIntegerRequired

Unique identifier of the target user

is_anonymousBooleanOptional

Pass True if the administrator's presence in the chat is hidden

can_manage_chatBooleanOptional

Pass True if the administrator can access the chat event log, get boost list, see hidden supergroup and channel members, report spam messages, ignore slow mode, and send messages to the chat without paying Telegram Stars. Implied by any other administrator privilege.

can_delete_messagesBooleanOptional

Pass True if the administrator can delete messages of other users

can_manage_video_chatsBooleanOptional

Pass True if the administrator can manage video chats

can_restrict_membersBooleanOptional

Pass True if the administrator can restrict, ban or unban chat members, or access supergroup statistics. For backward compatibility, defaults to True for promotions of channel administrators

can_promote_membersBooleanOptional

Pass True if the administrator can add new administrators with a subset of their own privileges or demote administrators that they have promoted, directly or indirectly (promoted by administrators that were appointed by him)

can_change_infoBooleanOptional

Pass True if the administrator can change chat title, photo and other settings

can_invite_usersBooleanOptional

Pass True if the administrator can invite new users to the chat

can_post_storiesBooleanOptional

Pass True if the administrator can post stories to the chat

can_edit_storiesBooleanOptional

Pass True if the administrator can edit stories posted by other users, post stories to the chat page, pin chat stories, and access the chat's story archive

can_delete_storiesBooleanOptional

Pass True if the administrator can delete stories posted by other users

can_post_messagesBooleanOptional

Pass True if the administrator can post messages in the channel, approve suggested posts, or access channel statistics; for channels only

can_edit_messagesBooleanOptional

Pass True if the administrator can edit messages of other users and can pin messages; for channels only

can_pin_messagesBooleanOptional

Pass True if the administrator can pin messages; for supergroups only

can_manage_topicsBooleanOptional

Pass True if the user is allowed to create, rename, close, and reopen forum topics; for supergroups only

can_manage_direct_messagesBooleanOptional

Pass True if the administrator can manage direct messages within the channel and decline suggested posts; for channels only

can_manage_tagsBooleanOptional

Pass True if the administrator can edit the tags of regular members; for groups and supergroups only

Returns

On success, True is returned.

GramIO Usage

Promote a user to a full supergroup admin (all common rights):

bot.command("promote", async (ctx) => {
  const targetId = ctx.update.message?.reply_to_message?.from?.id;
  if (!targetId) return ctx.send("Reply to a message to promote its author.");

  await bot.api.promoteChatMember({
    chat_id: ctx.chat.id,
    user_id: targetId,
    can_manage_chat: true,
    can_delete_messages: true,
    can_restrict_members: true,
    can_invite_users: true,
    can_pin_messages: true,
    can_change_info: true,
  });

  await ctx.send(`User ${targetId} has been promoted to admin.`);
});

Grant a moderator only the right to delete messages and restrict members:

async function makeModerator(chatId: number, userId: number) {
  await bot.api.promoteChatMember({
    chat_id: chatId,
    user_id: userId,
    can_manage_chat: true,
    can_delete_messages: true,
    can_restrict_members: true,
  });
}

Demote a user (remove all admin rights) by passing false for every boolean:

async function demoteUser(chatId: number, userId: number) {
  await bot.api.promoteChatMember({
    chat_id: chatId,
    user_id: userId,
    is_anonymous: false,
    can_manage_chat: false,
    can_delete_messages: false,
    can_manage_video_chats: false,
    can_restrict_members: false,
    can_promote_members: false,
    can_change_info: false,
    can_invite_users: false,
    can_pin_messages: false,
  });
}

Promote a channel admin with channel-specific rights:

async function promoteChannelEditor(channelId: string, userId: number) {
  await bot.api.promoteChatMember({
    chat_id: channelId,
    user_id: userId,
    can_post_messages: true,
    can_edit_messages: true,  // also allows pinning in channels
    can_delete_messages: true,
    can_manage_direct_messages: true,
  });
}

Errors

Code	Error	Cause
400	Bad Request: chat not found	The chat_id is invalid, the chat does not exist, or the bot is not a member.
400	Bad Request: user not found	The user_id does not correspond to a known Telegram user.
400	Bad Request: participant not found	The target user is not a member of the specified chat. They must join first.
400	Bad Request: can't promote self	A bot cannot promote itself — only other members.
400	Bad Request: method is available for supergroup and channel chats only	promoteChatMember works only in supergroups and channels, not basic groups or private chats.
403	Forbidden: not enough rights	The bot is not an administrator or lacks can_promote_members. A bot can only grant rights that it itself possesses.
403	Forbidden: bot was blocked by the user	The target user has blocked the bot.
429	Too Many Requests: retry after N	Flood control triggered. Wait N seconds before retrying.

Tips & Gotchas

• Demoting = passing false for everything. There is no separate "demote" method. To remove admin rights, call promoteChatMember with all boolean flags set to false. Omitting a flag does NOT reset it — only an explicit false removes that right.
• A bot can only grant rights it already has. If the bot's own can_promote_members right is missing or if you try to grant a right the bot itself does not hold, the call will fail with a 403 error.
• can_post_messages, can_edit_messages, can_manage_direct_messages are channels-only. Passing them for a supergroup is silently ignored. Conversely, can_pin_messages and can_manage_topics are supergroup-only.
• can_manage_chat is implied by every other right. You don't need to set it explicitly when granting any other privilege, but setting it alone grants basic management access without full admin powers.
• can_restrict_members defaults to true for channel promotions (backward compatibility). If you promote someone in a channel without specifying can_restrict_members, it will be granted automatically.
• Anonymous admins. Setting is_anonymous: true hides the admin's identity from regular members. Only other admins can see who the anonymous admin is.

See Also

• restrictChatMember — Restrict a user's permissions (not admin-level)
• banChatMember — Ban a user from the chat
• getChatMember — Inspect a user's current rights before promoting
• setChatPhoto — Change chat photo (requires can_change_info)
• pinChatMessage — Pin messages (requires can_pin_messages or can_edit_messages)
• ChatAdministratorRights — The type describing the full set of admin rights