setChatPermissions

Returns: TrueOfficial docs ↗

Use this method to set default chat permissions for all members. The bot must be an administrator in the group or a supergroup for this to work and must have the can_restrict_members administrator rights. Returns True on success.

Parameters

chat_idIntegerStringRequired

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

permissionsChatPermissionsRequired

A JSON-serialized object for new default chat permissions

use_independent_chat_permissionsBooleanOptional

Pass True if chat permissions are set independently. Otherwise, the can\send\other\messages and can\add\web\page\previews permissions will imply the can\send\messages, can\send\audios, can\send\documents, can\send\photos, can\send\videos, can\send\video\notes, and can\send\voice\notes permissions; the can\send\polls permission will imply the can\send\_messages permission.

Returns

On success, True is returned.

GramIO Usage

// Lock down a group: only allow reading, no messages allowed
await bot.api.setChatPermissions({
  chat_id: -1001234567890,
  permissions: {
    can_send_messages: false,
    can_send_polls: false,
    can_send_other_messages: false,
    can_add_web_page_previews: false,
    can_change_info: false,
    can_invite_users: false,
    can_pin_messages: false,
  },
});

// Open up all standard permissions (typical group configuration)
await bot.api.setChatPermissions({
  chat_id: -1001234567890,
  permissions: {
    can_send_messages: true,
    can_send_audios: true,
    can_send_documents: true,
    can_send_photos: true,
    can_send_videos: true,
    can_send_voice_notes: true,
    can_send_video_notes: true,
    can_send_polls: true,
    can_send_other_messages: true,
    can_add_web_page_previews: true,
  },
});

// Use independent permissions — set each flag individually
// Without this flag, some permissions cascade from others
await bot.api.setChatPermissions({
  chat_id: "@mysupergroup",
  permissions: {
    can_send_messages: true,
    can_send_polls: false,
    can_send_other_messages: true,
  },
  use_independent_chat_permissions: true,
});

// From a message context — update the current chat's permissions
bot.command("lockdown", async (ctx) => {
  await ctx.setChatDefaultPermissions({ can_send_messages: false });
  await ctx.send("Chat is now in read-only mode.");
});

Errors

Code	Error	Cause
400	Bad Request: chat not found	Invalid or inaccessible chat_id
400	Bad Request: can't change chat permissions	Method called on a channel or private chat — groups/supergroups only
403	Forbidden: not enough rights to restrict/unrestrict chat member	Bot lacks the can_restrict_members admin right
403	Forbidden: bot is not a member of the supergroup chat	Bot was removed from the chat

TIP

To restrict or un-restrict a specific user rather than the whole group, use restrictChatMember instead.

Tips & Gotchas

• can_restrict_members right is required. This is separate from can_change_info — make sure the bot's admin role has both if you manage general chat settings.
• Groups and supergroups only. Channels don't have member-level permissions; calling this on a channel returns an error.
• use_independent_chat_permissions changes cascading behavior. Without it (legacy mode), setting can_send_other_messages: true automatically implies can_send_messages, can_send_audios, can_send_documents, can_send_photos, can_send_videos, can_send_video_notes, and can_send_voice_notes. With it set to true, every permission is evaluated independently.
• Omitted flags default to false. Any ChatPermissions field you don't include in the object is treated as false. Always explicitly set every permission you want enabled.
• Context shorthand is ctx.setChatDefaultPermissions(permissions). Available in MessageContext and other contexts with ChatControlMixin.
• Per-user overrides via restrictChatMember. Default chat permissions apply to all members, but individual users can still have stricter (or looser, for supergroups) restrictions set via restrictChatMember.

See Also

• restrictChatMember — restrict a specific user's permissions
• promoteChatMember — grant admin rights to a user
• ChatPermissions — the permissions object type with all boolean fields
• getChat — read current default permissions via ChatFullInfo.permissions