Quickstart

This guide will help you set up the VBB Telegram Bot and walk you through planning your first journey on the Berlin-Brandenburg public transport network.

Prerequisites

Before you begin, you’ll need:

A Telegram account
Python 3.8 or higher (for self-hosting)
PostgreSQL database (for self-hosting)
A Telegram Bot Token from @BotFather

Installation

Choose your preferred installation method:

Docker (Recommended)
Manual Installation

The easiest way to run the bot is with Docker Compose:

Clone the repository

git clone https://github.com/timur-me/VBB-Project.git
cd VBB-Project

Configure the bot

Create a config.toml file with your bot token and settings:

[bot]
token = "7167777777:AaBbCcDdEeFfGgHh"  # Replace with your actual bot token

[settings]
owner_id = 123456789  # Your Telegram user ID
throttling_rate = 0.5
drop_pending_updates = true

[db]
database_url = "postgresql+asyncpg://user:password@db:5432/vbb_bot"

[api]
bot_api_url = "https://api.telegram.org"

Get your Telegram user ID by messaging @userinfobot on Telegram.

Start the services

docker-compose up --build

The bot will start automatically along with the PostgreSQL database.

For manual installation without Docker:

Clone the repository

git clone https://github.com/timur-me/VBB-Project.git
cd VBB-Project

Create virtual environment

python -m venv .venv

Activate virtual environment

source .venv/bin/activate

Install dependencies

pip install -r requirements.txt

Configure the bot

Create a config.toml file with your settings (see Docker tab for configuration example).

Make sure your PostgreSQL database is running and accessible at the URL specified in config.toml.

Run the bot

python -m app

First steps with the bot

Once the bot is running, follow these steps to plan your first journey:

Start a conversation

Open Telegram and search for your bot, then send the /start command:

/start

The bot will register you automatically and display a welcome message:

Welcome in [Bot Name]!
Press /menu for starting the dialog.
Press /help for more information and usage help.

Open the main menu

Send the /menu command to open the interactive menu:

/menu

You’ll see several options:

🏚️ Addresses menu
👋 Registration menu
🚌 Get nearby stops
🗺 Get journeys
⚙️ Settings

Set your home address

Before planning journeys, you need to configure your addresses:

Select 🏚️ Addresses menu
Click Add address
Enter your home address (e.g., “Alexanderplatz, Berlin”)
Confirm the address from the search results
Mark it as 🔘 Home address

The bot uses geocoding to find exact coordinates for your address, ensuring accurate journey planning.

Add a destination address

Repeat the process to add a destination address:

In the Addresses menu, click Add address again
Enter your destination (e.g., “Berlin Hauptbahnhof”)
Confirm the location
Mark it as 🔘 DefaultDestination

Plan your first journey

Now you’re ready to get route information:

Return to the main menu
Select 🗺 Get journeys
The bot will display journey options from your home to destination

Each journey shows:

Departure and arrival times
Total duration
All legs (segments) of the journey
Transport lines and directions
Walking times between stops

Use the ← → buttons to browse through different route options.

Customize your settings (Optional)

Fine-tune the bot to your preferences:

Select ⚙️ Settings from the main menu
Adjust settings like:
- Walking speed (slow/normal/fast)
- Min. transfer time (default: based on your settings)
- Max. transfers (maximum number of connections)
- Max. journeys (how many route alternatives to show)
- Transport modes (enable/disable bus, tram, subway, etc.)
- Arrival time (for daily notifications)
- Check time (when to receive daily updates)

Settings are saved per user and persist across bot restarts.

Using geolocation

The bot can find nearby stops using your current location:

Share your location

In the Telegram chat with your bot, tap the attachment icon (📎) and select Location.

Send live or static location

Choose Send My Current Location to share your position.The bot will automatically detect the location and show nearby stops.

View departures

The bot displays:

Nearby stops within 500 meters
Stop names and distances
Next departures from each stop
Line numbers and destinations

You can also plan journeys from your current location by sending your geolocation before selecting “Get journeys.”

Available commands

Here are the main commands you can use:

Command	Description
`/start`	Initialize or reload the bot
`/menu`	Open the main interactive menu
`/help`	Display all available commands

Owner commands

If you’re the bot owner (configured in config.toml), you also have access to:

Command	Description
`/ping`	Check bot ping and response time
`/stats`	Show bot statistics

Most interactions happen through the interactive menu system powered by aiogram-dialog, providing a smooth button-based interface.

Setting up daily notifications

Get automated journey updates every morning:

Configure your commute times

Go to ⚙️ Settings
Click Change arrival time
Enter your desired arrival time (format: HH:MM, e.g., 09:00)
Click Change check time
Enter when you want to receive the notification (e.g., 07:00)

Verify your addresses

Make sure you have both a home and destination address configured. The bot uses these for daily route calculations.

Receive your first notification

At your configured check time, the bot will automatically send you journey options that arrive at your destination by your specified arrival time.

The background service checks every 15 seconds for users who need notifications. Each user receives only one notification per day, which resets at midnight.

Code reference

The bot’s main functionality is implemented in several key modules:

Journey planning: app/vbb/func.py:116 - get_journeys() function
Address management: app/dialogs/addresses.py - Address dialog system
Geolocation handling: app/handlers/user/geolocation.py:11 - Location message handler
Daily notifications: app/vbb/service/checker.py:18 - Background journey checker
Settings configuration: app/dialogs/settings.py - User preferences dialog

Troubleshooting

Bot doesn't respond to commands

Verify the bot is running (docker-compose ps or check your terminal)
Check your bot token in config.toml is correct
Ensure you’ve sent /start to initialize your user account

Can't find my address

Try using more specific address details (street number, city name)
Use well-known landmarks or station names
The VBB API uses OpenStreetMap data for geocoding

No journeys found

Verify both home and destination addresses are set
Check your transport mode filters in settings (at least one must be enabled)
Ensure your addresses are within the VBB service area (Berlin-Brandenburg region)

Daily notifications not working

Confirm both arrival time and check time are configured in settings
Verify the background service is running (check logs for “checking user” messages)
Notifications are sent only once per day and reset at midnight

Next steps

Now that you have the bot set up:

Explore different journey options by changing your walking speed
Add multiple destination addresses for different commute routes
Experiment with transport mode filters to prefer buses over trains
Try the nearby stops feature when you’re exploring new areas

View source code

Check out the full source code on GitHub

Get Started

User Guide

Deployment

Prerequisites

Installation

First steps with the bot

Using geolocation

Available commands

Owner commands

Setting up daily notifications

Code reference

Troubleshooting

Next steps

View source code

Build docs developers (and LLMs) love

Get Started

User Guide

Deployment

​Prerequisites

​Installation

​First steps with the bot

​Using geolocation

​Available commands

​Owner commands

​Setting up daily notifications

​Code reference

​Troubleshooting

​Next steps

View source code

Build docs developers (and LLMs) love

Prerequisites

Installation

First steps with the bot

Using geolocation

Available commands

Owner commands

Setting up daily notifications

Code reference

Troubleshooting

Next steps