banChatMember

Bans a member from a group or channel.

💡 A ban is a blacklist, not just a removal — the user cannot rejoin the chat until you lift it with unbanChatMember.

Request

method is "banChatMember".

Field	Type	Required	Description
`chat_id`	String	Yes	The group or channel to ban them from.
`user_id`	String	Yes	The member to ban.
`app_id`	String	Yes	The app the chat belongs to.
`reference`	String	Optional	Your id for this request. Echoed back in the response.

Preconditions

Requirement	Why
`"Manage Chats"` permission	Needed to manage chats in the app.
`"Ban/unBan Chat Members"` permission	Needed specifically to ban and unban.
Moderator or admin in the chat	Bans require a privileged role in that chat.

Response

chatMember

The member record comes back with "status": "Banned".

Field	Type	Returned	Description
`method`	String	Yes	`"chatMember"`
`chatMember`	Chat Member	Yes	The member record, now showing `"status": "Banned"`.
`app_id`	String	Yes	Echoed from the request.
`reference`	String	Optional	Echoed from the request.

SDKs

SDK	Call	Callback
Java	`api.banChatMember(chatId, userId, appId, reference);`	`onChatMember(ChatMember chatMember)`
JavaScript	`api.banChatMember(chatId, userId, appId, reference);`	`onChatMember(chatMember)`
Python	`napi.ban_chat_member(chat_id=chat_id, user_id=user_id, app_id=app_id, reference=reference)`	`on_chat_member(self, chat_member)`

Example

Request

json
{
  "method": "banChatMember",
  "chat_id": "90090684438172188",
  "user_id": "90089584789572153",
  "app_id": "90090684293000559",
  "reference": "123456789"
}

java
api.banChatMember("90090684438172188", "90089584789572153", "90090684293000559", "123456789");

javascript
api.banChatMember("90090684438172188", "90089584789572153", "90090684293000559", "123456789");

python
napi.ban_chat_member(chat_id="90090684438172188", user_id="90089584789572153", app_id="90090684293000559", reference="123456789")

Response

json
{
  "method": "chatMember",
  "app_id": "90090684293000559",
  "reference": "123456789",
  "chatMember": {
    "user": {
      "id": "90089584789572153"
    },
    "chat": {
      "id": "90090684438172188"
    },
    "type": null,
    "status": "Banned",
    "view": null
  }
}