Frequently Asked Questions¶

This document answers common questions about aiogram-cmds.

🤔 General Questions¶

What is aiogram-cmds?¶

aiogram-cmds is a command management library for aiogram v3 that helps you manage Telegram bot commands with i18n support, user profiles, and dynamic scopes.

Why should I use aiogram-cmds?¶

Simplified Command Management: No need to manually manage command scopes
i18n Support: Built-in support for multiple languages
User Profiles: Dynamic command sets based on user status
Production Ready: Comprehensive testing and documentation
Type Safe: Full type hints and validation

Is aiogram-cmds compatible with aiogram v2?¶

No, aiogram-cmds is designed specifically for aiogram v3. For aiogram v2, you'll need to use the built-in command management features.

What Python versions are supported?¶

aiogram-cmds supports Python 3.10+ (3.10, 3.11, 3.12, 3.13).

🚀 Getting Started¶

How do I install aiogram-cmds?¶

pip install aiogram-cmds

For Redis support:

pip install aiogram-cmds[redis]

What's the quickest way to get started?¶

Use auto-setup:

from aiogram_cmds.auto_setup import setup_commands_auto

manager = await setup_commands_auto(bot)

Do I need to configure anything?¶

No! aiogram-cmds works out of the box with sensible defaults. You can customize later as needed.

⚙️ Configuration¶

How do I add multiple languages?¶

config = CmdsConfig(
    languages=["en", "ru", "es"],
    fallback_language="en",
    # ... rest of configuration
)

How do I create user-specific commands?¶

Use profiles and profile resolvers:

profiles = {
    "guest": ProfileDef(include=["start", "help"]),
    "user": ProfileDef(include=["start", "help", "profile"]),
    "admin": ProfileDef(include=["start", "help", "profile", "admin"]),
}

def profile_resolver(flags: Flags) -> str:
    if flags.is_admin:
        return "admin"
    elif flags.is_registered:
        return "user"
    return "guest"

How do I update commands dynamically?¶

await manager.update_user_commands(
    user_id=12345,
    is_registered=True,
    has_vehicle=False,
    user_language="en"
)

Can I use configuration files?¶

Yes! Create pyproject.toml:

[tool.aiogram_cmds]
languages = ["en", "ru"]
fallback_language = "en"
i18n_key_prefix = "cmd"

Then load it:

from aiogram_cmds import load_settings
settings = load_settings()

🌍 i18n and Translations¶

How do I integrate with aiogram i18n?¶

from aiogram_cmds import build_translator_from_i18n

translator = build_translator_from_i18n(i18n_instance)
manager = CommandScopeManager(bot, translator=translator)

What translation key pattern should I use?¶

The default pattern is {prefix}.{command}.desc:

cmd.start.desc → "Start the bot"
cmd.help.desc → "Show help information"

How do I handle missing translations?¶

aiogram-cmds automatically falls back to: 1. Fallback language translation 2. Title Case of command name 3. "Command" as final fallback

Can I use custom translation keys?¶

Yes! Set the i18n_key in CommandDef:

commands = {
    "start": CommandDef(i18n_key="commands.start.description"),
    "help": CommandDef(i18n_key="menu.help.tooltip"),
}

🎯 Profiles and Scopes¶

What are profiles?¶

Profiles are named sets of commands that can be applied to users based on their status or permissions.

How do scopes work?¶

Scopes define where and how commands are applied. They follow Telegram's command scope hierarchy:

chat_member - Most specific
chat_admins
chat
all_chat_admins
all_group_chats
all_private_chats
default - Least specific

Can I have different commands for different chats?¶

Yes! Use chat-specific scopes:

scopes = [
    ScopeDef(scope="all_private_chats", profile="user"),
    ScopeDef(scope="chat", chat_id=12345, profile="admin"),
]

How do I create admin-only commands?¶

Create an admin profile and apply it to specific users or chats:

profiles = {
    "user": ProfileDef(include=["start", "help"]),
    "admin": ProfileDef(include=["start", "help", "admin", "ban"]),
}

scopes = [
    ScopeDef(scope="chat_member", chat_id=12345, user_id=67890, profile="admin"),
]

🔧 Troubleshooting¶

Commands don't appear in Telegram¶

Make sure you call await manager.setup_all()
Check that your bot token is valid
Verify command names are valid (lowercase, letters, numbers, underscores only)
Check the logs for error messages

i18n translations don't work¶

Ensure your i18n instance is properly configured
Check that translation keys exist in your locale files
Verify the i18n_key_prefix matches your translation key structure
Test with a simple translator first

Profile resolver not working¶

Make sure your profile resolver returns valid profile names
Check that profiles are defined in your configuration
Verify that the profile includes/excludes valid command names
Add logging to debug profile resolution

Commands not updating dynamically¶

Make sure to call update_user_commands() after state changes
Check that your profile resolver is working correctly
Verify that the new profile has the expected commands
Check the logs for any errors

Import errors¶

# Make sure aiogram-cmds is installed
pip install aiogram-cmds

# Check installation
python -c "import aiogram_cmds; print(aiogram_cmds.__version__)"

Bot not responding¶

Check your bot token
Make sure the bot is running
Check logs for error messages
Verify your message handlers are registered

🚀 Performance¶

Is aiogram-cmds fast?¶

Yes! aiogram-cmds is optimized for performance: - Efficient command building - Minimal API calls to Telegram - Cached profile resolutions - Batch operations where possible

How do I optimize for large user bases?¶

Use Redis for multi-worker deployments
Cache profile resolutions
Batch command updates
Use appropriate scope hierarchy
Monitor performance metrics

Can I use it with multiple workers?¶

Yes! Use Redis for shared state:

pip install aiogram-cmds[redis]

🔒 Security¶

Is aiogram-cmds secure?¶

Yes! aiogram-cmds follows security best practices: - Input validation with Pydantic - No sensitive data in logs - Graceful error handling - Type safety with strict type checking

How do I handle user permissions securely?¶

Validate user permissions in your profile resolver
Use proper scope hierarchy
Don't expose sensitive commands to unauthorized users
Implement proper authentication

🧪 Testing¶

How do I test my configuration?¶

def test_configuration():
    config = CmdsConfig(...)
    # Configuration is validated automatically
    assert config.languages == ["en", "ru"]

How do I test profile resolution?¶

def test_profile_resolver():
    resolver = my_profile_resolver
    flags = Flags(is_registered=True, has_vehicle=False)
    profile = resolver(flags)
    assert profile == "user"

How do I test command updates?¶

async def test_command_updates():
    manager = CommandScopeManager(bot)
    await manager.update_user_commands(
        user_id=12345,
        is_registered=True,
        has_vehicle=False
    )
    # Commands should be updated

🤝 Contributing¶

How do I contribute?¶

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

What are the coding standards?¶

Follow PEP 8
Use type hints
Write docstrings
Add tests for new features
Update documentation

How do I run the tests?¶

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=src/aiogram_cmds

📚 Documentation¶

Where can I find more documentation?¶

Quickstart Guide - Get started in 5 minutes
API Reference - Complete API documentation
Tutorials - Step-by-step guides
Examples - Working bot examples

How do I report documentation issues?¶

Create an issue on GitHub or submit a pull request with improvements.

🆘 Getting Help¶

Where can I get help?¶

GitHub Discussions - Community help
GitHub Issues - Bug reports
Documentation - Complete guides

How do I report bugs?¶

Check existing issues first
Create a new issue with:
Clear description
Steps to reproduce
Expected vs actual behavior
Environment details

How do I request features?¶

Check existing feature requests
Create a new issue with:
Clear description of the feature
Use case and benefits
Implementation suggestions (if any)

Still have questions? Check out our GitHub Discussions or create an issue!