Permission System

Complete reference of permission checking functions

🔐 Permission System

This page documents all permission checking functions in Alita Robot.

Overview

• Total Functions: 26
• Location: alita/utils/chat_status/ (chat_status.go, access.go, permission_responder.go)

Function Summary

Functions by Category

🤖 Bot Permission Checks

CanBotDelete

func CanBotDelete(b *gotgbot.Bot, ctx *ext.Context, chat *gotgbot.Chat) bool

CanBotDelete checks if the bot has permission to delete messages in the chat. Validates the bot’s CanDeleteMessages permission.

Parameters:

• b
• ctx
• chat

CanBotPin

func CanBotPin(b *gotgbot.Bot, ctx *ext.Context, chat *gotgbot.Chat) bool

CanBotPin checks if the bot has permission to pin messages in the chat. Validates the bot’s CanPinMessages permission.

Parameters:

• b
• ctx
• chat

CanBotPromote

func CanBotPromote(b *gotgbot.Bot, ctx *ext.Context, chat *gotgbot.Chat) bool

CanBotPromote checks if the bot has permission to promote/demote members in the chat. Validates the bot’s CanPromoteMembers permission.

Parameters:

• b
• ctx
• chat

CanBotRestrict

func CanBotRestrict(b *gotgbot.Bot, ctx *ext.Context, chat *gotgbot.Chat) bool

CanBotRestrict checks if the bot has permission to restrict members in the chat. Validates the bot’s CanRestrictMembers permission.

Parameters:

• b
• ctx
• chat

IsBotAdmin

func IsBotAdmin(b *gotgbot.Bot, ctx *ext.Context, chat *gotgbot.Chat) bool

IsBotAdmin checks if the bot has administrator privileges in the specified chat. Returns true for private chats (bot is always “admin” in private). For groups, verifies the bot’s actual admin status.

Parameters:

• b
• ctx
• chat

PermissionResponder

Located in alita/utils/chat_status/permission_responder.go.

Centralizes permission-failure messaging with support for callback-query answers and chat replies.

// Create a responder
responder := chat_status.NewPermissionResponder(b, ctx)

// Respond with default message
responder.Respond()

// Respond with a reply to the original message
responder.WithReply()

// Respond with fallback if reply fails
responder.WithReplyFallback()

Functions:

🔢 ID Validation

IsChannelId

func IsChannelId(id int64) bool

IsChannelId checks if an ID represents a Telegram channel. Channel IDs have the format -100XXXXXXXXXX (-100 prefix followed by 10+ digits).

Parameters:

• id

IsValidUserId

func IsValidUserId(id int64) bool

IsValidUserId checks if an ID represents a valid Telegram user. User IDs are always positive (> 0). Channel IDs are negative with format -100XXXXXXXXXX (< -1000000000000). Regular chat/group IDs are negative but in a different range.

Parameters:

• id

📋 Other

IsApproved

func IsApproved(b *gotgbot.Bot, chatID, userID int64) bool

IsApproved checks if a user is in the approved whitelist for a chat. Approved users are immune to anti-spam measures (antiflood, blacklists, locks, captcha, antispam). This is a simple delegation to the DB layer for consistent usage in watcher handlers.

Parameters:

• b
• chatID
• userID

✅ Requirement Checks

RequireBotAdmin

func RequireBotAdmin(b *gotgbot.Bot, ctx *ext.Context, chat *gotgbot.Chat) bool

RequireBotAdmin ensures the bot has administrator privileges in the chat. Uses IsBotAdmin internally to perform the check.

Parameters:

• b
• ctx
• chat

RequireGroup

func RequireGroup(b *gotgbot.Bot, ctx *ext.Context, chat *gotgbot.Chat) bool

RequireGroup ensures the command is being used in a group chat. Returns false for private chats. nolint:dupl // RequirePrivate/RequireGroup have symmetric logic

Parameters:

• b
• ctx
• chat

RequirePrivate

func RequirePrivate(b *gotgbot.Bot, ctx *ext.Context, chat *gotgbot.Chat) bool

RequirePrivate ensures the command is being used in a private chat. Returns false for group chats and supergroups. nolint:dupl // RequirePrivate/RequireGroup have symmetric logic

Parameters:

• b
• ctx
• chat

RequireUserAdmin

func RequireUserAdmin(b *gotgbot.Bot, ctx *ext.Context, chat *gotgbot.Chat, userId int64) bool

RequireUserAdmin ensures a user has administrator privileges in the chat. Uses IsUserAdmin internally to perform the check.

Parameters:

• b
• ctx
• chat
• userId

RequireUserOwner

func RequireUserOwner(b *gotgbot.Bot, ctx *ext.Context, chat *gotgbot.Chat, userId int64) bool

RequireUserOwner ensures a user is the chat creator/owner. Checks for “creator” status specifically, not just administrator.

Parameters:

• b
• ctx
• chat
• userId

RequireUser

func RequireUser(b *gotgbot.Bot, ctx *ext.Context) *gotgbot.User

RequireUser extracts the effective user from the update context. Returns nil for channel messages where ctx.EffectiveSender is nil. Always check the return value before accessing fields.

Parameters:

• b
• ctx

👮 User Permission Checks

CanInvite

func CanInvite(b *gotgbot.Bot, ctx *ext.Context, chat *gotgbot.Chat, msg *gotgbot.Message) bool

CanInvite checks if the bot and user have permissions to generate invite links. Returns true immediately if the chat has a public username. Validates both bot and user permissions for invite link generation.

Parameters:

• b
• ctx
• chat
• msg

CanUserChangeInfo

func CanUserChangeInfo(b *gotgbot.Bot, ctx *ext.Context, chat *gotgbot.Chat, userId int64) bool

CanUserChangeInfo checks if a user has permission to change chat information. Handles anonymous admins and validates the CanChangeInfo permission.

Parameters:

• b
• ctx
• chat
• userId

CanUserDelete

func CanUserDelete(b *gotgbot.Bot, ctx *ext.Context, chat *gotgbot.Chat, userId int64) bool

CanUserDelete checks if a user has permission to delete messages in the chat. Handles anonymous admins and validates the CanDeleteMessages permission.

Parameters:

• b
• ctx
• chat
• userId

CanUserPin

func CanUserPin(b *gotgbot.Bot, ctx *ext.Context, chat *gotgbot.Chat, userId int64) bool

CanUserPin checks if a user has permission to pin messages in the chat. Handles anonymous admins and validates the CanPinMessages permission.

Parameters:

• b
• ctx
• chat
• userId

CanUserPromote

func CanUserPromote(b *gotgbot.Bot, ctx *ext.Context, chat *gotgbot.Chat, userId int64) bool

CanUserPromote checks if a user has permission to promote/demote other members. Handles anonymous admins and validates the CanPromoteMembers permission.

Parameters:

• b
• ctx
• chat
• userId

CanUserRestrict

func CanUserRestrict(b *gotgbot.Bot, ctx *ext.Context, chat *gotgbot.Chat, userId int64) bool

CanUserRestrict checks if a user has permission to restrict other members. Handles anonymous admins and validates the CanRestrictMembers permission.

Parameters:

• b
• ctx
• chat
• userId

👤 User Status Checks

IsUserAdmin

func IsUserAdmin(b *gotgbot.Bot, chatID, userId int64) bool

IsUserAdmin checks if a user has administrator privileges in a chat. Uses caching system to avoid repeated API calls and handles special Telegram admin accounts. Returns true if the user is an admin, creator, or special Telegram account.

Parameters:

• b
• chatID
• userId

IsUserBanProtected

func IsUserBanProtected(b *gotgbot.Bot, ctx *ext.Context, chat *gotgbot.Chat, userId int64) bool

IsUserBanProtected checks if a user is protected from being banned. Returns true for private chats, admins, and special Telegram accounts. Used to prevent banning of administrators and system accounts.

Parameters:

• b
• ctx
• chat
• userId

IsUserInChat

func IsUserInChat(b *gotgbot.Bot, chat *gotgbot.Chat, userId int64) bool

IsUserInChat checks if a user is currently a member of the specified chat. Returns false for special Telegram accounts and users with “left” or “kicked” status.

Parameters:

• b
• chat
• userId

GetEffectiveUser

func GetEffectiveUser(ctx *ext.Context) *gotgbot.User

GetEffectiveUser safely extracts the user from the context without nil panics. Returns nil for channel messages where ctx.EffectiveSender is nil. Use this instead of direct ctx.EffectiveSender.User access to avoid nil pointer dereferences.

Parameters:

• ctx

🔧 Utility Functions

CheckDisabledCmd

func CheckDisabledCmd(bot *gotgbot.Bot, msg *gotgbot.Message, cmd string) bool

CheckDisabledCmd checks if a command is disabled in the chat and handles deletion if configured. Returns true if the command should be blocked, false if it should proceed. Skips checks for private chats and admin users. If command is disabled for non-admin users, optionally deletes the message based on chat settings.

Parameters:

• bot
• msg
• cmd

Special Telegram IDs

Usage Example

func (m moduleStruct) myCommand(b *gotgbot.Bot, ctx *ext.Context) error {
    chat := ctx.EffectiveChat
    user := ctx.EffectiveSender.User
    
    // Check if user is admin
    if !chat_status.RequireUserAdmin(b, ctx, chat, user.Id) {
        return ext.EndGroups
    }
    
    // Check if bot can restrict
    if !chat_status.CanBotRestrict(b, ctx, chat) {
        return ext.EndGroups
    }
    
    // Proceed with action...
    return ext.EndGroups
}