Quickstart#

Install library:

pip install aiogram_dialog

Let’s assume that you have created your aiogram bot with dispatcher and states storage as you normally do. When we setup our DialogRegistry to use that dispatcher. It is important you have proper storage because aiogram_dialog uses FSMContext internally to store it state:

from aiogram import Bot, Dispatcher
from aiogram.fsm.storage.memory import MemoryStorage

storage = MemoryStorage()
bot = Bot(token='BOT TOKEN HERE')
dp = Dispatcher(storage=storage)

Create states group for your dialog:

from aiogram.filters.state import StatesGroup, State

class MySG(StatesGroup):
    main = State()

Create at least one window with text and add buttons if needed:

from aiogram.filters.state import State, StatesGroup

from aiogram_dialog import Window
from aiogram_dialog.widgets.kbd import Button
from aiogram_dialog.widgets.text import Const


class MySG(StatesGroup):
    main = State()


main_window = Window(
    Const("Hello, unknown person"),  # just a constant text
    Button(Const("Useless button"), id="nothing"),  # button with text and id
    state=MySG.main,  # state is used to identify window between dialogs
)

Create dialog with your windows:

from aiogram_dialog import Dialog

dialog = Dialog(main_window)

Each Dialog must be attached to some Router or Dispatcher.

dp.include_router(dialog)

At this point we have configured everything. But dialog won’t start itself. We will create simple command handler to deal with it. To start dialog we need DialogManager which is automatically injected by library. Also mind the reset_stack argument. The library can start multiple dialogs stacking one above other. Currently we do not want this feature, so we will reset stack on each start:

from aiogram.filters import Command
from aiogram.types import Message

from aiogram_dialog import DialogManager, StartMode


@dp.message(Command("start"))
async def start(message: Message, dialog_manager: DialogManager):
    # Important: always set `mode=StartMode.RESET_STACK` you don't want to stack dialogs
    await dialog_manager.start(MySG.main, mode=StartMode.RESET_STACK)

Before starting your bot you need to setup aiogram-dialogs middlewares and core handlers. To do it use setup_dialogs function passing your Router or Dispatcher instance

from aiogram_dialog import setup_dialogs

setup_dialogs(dp)

Last step, you need to start your bot as usual:

if __name__ == '__main__':
    dp.run_polling(bot)

Summary:

from aiogram import Bot, Dispatcher
from aiogram.filters import Command
from aiogram.filters.state import State, StatesGroup
from aiogram.fsm.storage.memory import MemoryStorage
from aiogram.types import Message

from aiogram_dialog import (
    Dialog, DialogManager, setup_dialogs, StartMode, Window,
)
from aiogram_dialog.widgets.kbd import Button
from aiogram_dialog.widgets.text import Const


class MySG(StatesGroup):
    main = State()


main_window = Window(
    Const("Hello, unknown person"),
    Button(Const("Useless button"), id="nothing"),
    state=MySG.main,
)
dialog = Dialog(main_window)

storage = MemoryStorage()
bot = Bot(token='BOT TOKEN HERE')
dp = Dispatcher(storage=storage)
dp.include_router(dialog)
setup_dialogs(dp)


@dp.message(Command("start"))
async def start(message: Message, dialog_manager: DialogManager):
    await dialog_manager.start(MySG.main, mode=StartMode.RESET_STACK)


if __name__ == '__main__':
    dp.run_polling(bot, skip_updates=True)

The result will look like:

../_images/quickstart.png