Moderation

A bot can help look after a chat: delete spam, kick or ban people who cause trouble. It can do this only when the chat’s owner gives it the right.

The bot’s rights in a chat

Right	What it allows
delete_messages	Delete other people’s messages in that chat
kick	Kick people out of the chat
ban	Ban people and lift bans

• A bot that has just joined a chat has none of them.
• Only the chat’s owner can give rights, with the switches in that chat’s bot settings in the Sukson app or website. The chat’s admins can’t give rights, but they can take them away.
• Rights belong to one chat. A right in one chat says nothing about another.
• If the bot leaves and is added back, or the chat gets a new owner, its rights start from nothing again.
• See the current rights in bot.rights of GET /v1/chats/{chat_id}.

The bot must be active in that chat. If its owner paused it there, you get 403 FORBIDDEN with reason paused, as when sending.

People a bot can’t act on

Even with the right, a bot can’t do any of this to the following people, and gets 403 FORBIDDEN with reason protected_member:

• The chat’s owner and its admins
• The Sukson team
• Any bot, the bot itself included

Delete other people’s messages

DELETE /v1/messages/{message_id}

The same endpoint the bot uses for its own messages (messages). For someone else’s message in a chat the bot is in, it needs delete_messages.

curl -s -X DELETE https://api.sukson.dev/v1/messages/812345 -H "Authorization: Bearer $SUKSON_BOT_TOKEN"

{ "message_id": 812345, "chat_id": "0b6c3a52-5d0e-4c8e-9a51-6f1e7f6f2b10" }

Files and pictures attached to the message are deleted with it. System lines (such as “Somchai joined”) can’t be deleted.

Kick

DELETE /v1/chats/{chat_id}/members/{user_id}

Needs kick. No body. user_id is the person’s member id.

curl -s -X DELETE https://api.sukson.dev/v1/chats/0b6c3a52-5d0e-4c8e-9a51-6f1e7f6f2b10/members/9f2c4e7a1b3d5f60718293a4b5c6d7e8 \
  -H "Authorization: Bearer $SUKSON_BOT_TOKEN"

{ "kicked": true }

• Groups and channels: the person is removed, as when an admin removes them. A system line appears in the chat and the bots there get member_left. Someone who isn’t in the chat any more gets 404 NOT_FOUND. A kicked person can come back if they’re invited again.
• Public rooms: the person is dropped from the room at once but can come back in. To keep them out, ban them instead. Works on visitors too (use the sender.id from the event). A kick doesn’t end their membership, so the bot gets no member_left and they stay in the members list. The person must be a member of the room or have posted there recently, otherwise you get 404 NOT_FOUND.

Ban

POST /v1/chats/{chat_id}/bans

Needs ban.

Field	Type	Rules
user_id	string	Required. The person’s member id (32 lowercase hex characters).
reason	string	Optional, at most 280 characters (an emoji counts as 2)
duration_minutes	integer	Optional, 1–525,600 (one year), public rooms only. Leave it out to ban until lifted.

curl -s -X POST https://api.sukson.dev/v1/chats/7d2e9f10-3c4b-4a5d-8e6f-1a2b3c4d5e6f/bans \
  -H "Authorization: Bearer $SUKSON_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"9f2c4e7a1b3d5f60718293a4b5c6d7e8","reason":"Posting spam links","duration_minutes":1440}'

{ "banned": true, "expires_at": "2026-11-08T03:15:00.000Z" }

• Groups and channels: the person is removed and can’t come back through an invite link until the ban is lifted. Timed bans aren’t available here: duration_minutes gets 422 INVALID with reason rooms_only. reason isn’t kept.
• Public rooms: the ban lasts for the time you give, or until lifted. Works on visitors too. A ban doesn’t end their membership, so the bot gets no member_left and they stay in the members list. expires_at is when the ban ends (null for no end).

Lift a ban

DELETE /v1/chats/{chat_id}/bans/{user_id}

Needs ban. No body.

{ "unbanned": true }

unbanned is false when the person wasn’t banned. Lifting a ban lifts that person’s bans in the chat, including bans the owner or an admin placed, not only the bot’s own. In public rooms, a bot can’t lift a ban the Sukson team placed; that ban stays.

Limit

One bot can delete other people’s messages, kick, ban and lift bans 30 times a minute in total, across all its chats. Beyond that you get 429 RATE_LIMITED with details.retry_after (seconds). This is separate from the general API rate limit.

Errors

HTTP	code	When
403	FORBIDDEN	details.reason is missing_right (the bot lacks the right; details.right says which), protected_member (someone a bot can’t act on), system_message (deleting a system line), or paused, banned, attacher_lost_rights as when sending
403	CHAT_INACTIVE	The chat is closed
404	NOT_FOUND	The bot isn’t in this chat, no such message, no such user_id in this chat, or a malformed user_id in the path
422	INVALID	Malformed user_id in the body, reason too long, duration_minutes out of range, or rooms_only
429	RATE_LIMITED	Moderating too fast; see details.retry_after

{ "message": "The chat's owner hasn't given this bot this right here", "code": "FORBIDDEN", "details": { "reason": "missing_right", "right": "kick" } }