Deep Linking#

Telegram bots have a deep linking mechanism, that allows for passing additional parameters to the bot on startup. It could be a command that launches the bot — or an auth token to connect the user’s Telegram account to their account on some external service.

You can read detailed description in the source: https://core.telegram.org/bots/features#deep-linking

We have added some utils to get deep links more handy.

Examples#

Decode it back#

from aiogram.utils.deep_linking import decode_payload
from aiogram.filters import CommandStart, CommandObject
from aiogram.types import Message

@router.message(CommandStart(deep_link=True))
async def handler(message: Message, command: CommandObject):
    args = command.args
    payload = decode_payload(args)
    await message.answer(f"Your payload: {payload}")

References#

Create ‘start’ deep link with your payload.

If you need to encode payload or pass special characters -

set encode as True

Parameters:
  • bot – bot instance

  • payload – args passed with /start

  • encode – encode payload with base64url or custom encoder

  • encoder – custom encoder callable

Returns:

link

aiogram.utils.deep_linking.decode_payload(payload: str, decoder: Callable[[bytes], bytes] | None = None) str[source]#

Decode URL-safe base64url payload with decoder.