A private Telegram bot for your self-hosted AdventureLog instance. Browse trips, view location details, manage checklists, discover nearby places, and get daily reminders β all from Telegram.
- Features
- How It Works
- Requirements
- Installation
- Configuration
- Usage
- Screenshots
- Schedulers
- Project Structure
- AdventureLog Compatibility
- Security Notes
- Troubleshooting
- Development
- Contributing
- License
- My Trips β list all collections (with their date ranges) and drill into any trip for locations, transportation, calendar, and checklists
- Locations β step through a trip's itinerary stop by stop (visits sorted by start date), browse a paged list of its locations (8 per page), or search them by name
- Transportation β step through a trip's flights, trains, drives, and other transport legs
- Calendar β view a trip's events (locations plus transportation) sorted by date
- Location detail β name, rating, description, coordinates, and one-tap buttons for Apple Maps / Google Maps and turn-by-turn navigation
- Documents β download a location's attachments straight into the chat
- Checklists β browse, tick off, remove, and add items in any checklist of a trip
- Recommendations nearby β up to 10 Google Places results around a saved location (from its location card) or around your current position (from a trip, by sharing your Telegram location); filter by Food, Lodging, or Tourism; choose a radius of 5, 10, 20, or 50 km
- Search β keyword search across all locations and collections (trips)
- Where was I onβ¦ β look up which location you were visiting on a given date
- Schedulers β a daily checklist reminder and an evening digest of tomorrow's plans, each with its own time and timezone
- Private access β restrict the bot to an allowlist of Telegram chat IDs (
ALLOWED_IDS); without it, anyone can use the bot - Clear sign-in errors β AdventureLog login failures are logged and reported in the chat instead of showing up as empty results
flowchart LR
U[Telegram user] <--> T[Telegram Bot API]
T <-- long polling --> B[Adventurebot]
B -- "session login + REST (/api/...)" --> A[AdventureLog]
A -- "recommendations (sources=google)" --> G[Google Places]
B <--> S[(data/schedulers.json)]
- The bot uses long polling (no webhook, no inbound port needed) via python-telegram-bot.
- It signs in to AdventureLog with a username and password (
POST /login), keeps thesessionidcookie, and re-authenticates automatically when the session expires. - Data is read from the AdventureLog REST API (
/api/collections,/api/locations,/api/visits,/api/transportations,/api/checklists,/api/search,/api/recommendations/query). Checklist changes are written back withPATCH /api/checklists/{id}/. - Nearby recommendations are served by AdventureLog's own recommendations endpoint, which the bot queries with
sources=google. - Scheduler settings are stored in a small JSON file (
data/schedulers.jsonby default) and run on the python-telegram-bot job queue.
- Python 3.12+ (when not using Docker)
- A running AdventureLog instance (v0.11 or newer ) β see the official installation guide
- An AdventureLog user account that owns the trips you want to see
- A Telegram bot token from @BotFather
- For Recommendations nearby: Google-backed recommendations must work on your AdventureLog instance
-
Clone the repo:
git clone https://github.com/t0mer/Adventurebot.git cd Adventurebot -
Install dependencies:
pip install -r requirements.txt
-
Configure the environment β copy the example file and fill in your values (see Configuration):
cp env.example .env
-
Run the bot:
python3 -m bot.main
To keep it running in the background with tmux:
tmux new-session -d -s adventurebot 'python3 -m bot.main'To attach and check logs:
tmux attach -t adventurebot
Images are published to Docker Hub as techblog/adventurebot (linux/amd64, linux/arm64).
-
Create a
.envfile next todocker-compose.yml(see Configuration). -
Pull the image and start the container:
docker compose up -d
The compose file reads TELEGRAM_TOKEN, AL_URL, AL_USERNAME, AL_PASSWORD, and ALLOWED_IDS from your .env file. It does not pass TZ or SCHEDULER_CONFIG; add them under environment: if you need them. Scheduler settings are persisted in a local data/ directory mounted at /app/data (see Troubleshooting for permissions).
View the logs:
docker compose logs -fdocker run -d \
--name adventurebot \
--restart unless-stopped \
-e TELEGRAM_TOKEN=your_token \
-e AL_URL=https://adventure.example.com \
-e AL_USERNAME=admin \
-e AL_PASSWORD=secret \
-e ALLOWED_IDS=123456789 \
-v "$(pwd)/data:/app/data" \
techblog/adventurebot:latestView the logs:
docker logs -f adventurebotA manual workflow (publish-ghcr.yml) can also publish the image to the GitHub Container Registry as ghcr.io/t0mer/adventurebot (including linux/arm/v7).
All configuration is done through environment variables. When running with Python, a .env file in the working directory is loaded automatically (via python-dotenv); variables already set in the environment take precedence over .env.
| Variable | Required | Default | Description |
|---|---|---|---|
TELEGRAM_TOKEN |
β | β | Bot token from @BotFather. |
AL_URL |
β | β | Full URL of your AdventureLog instance, e.g. https://adventure.example.com (a trailing / is ignored). |
AL_USERNAME |
β | β | AdventureLog username. |
AL_PASSWORD |
β | β | AdventureLog password. Quote it in .env if it contains #, !, or $ (see Troubleshooting). |
ALLOWED_IDS |
(empty β everyone) | Comma-separated numeric Telegram chat IDs that may use the bot. Leave empty to allow everyone. Find your chat ID by messaging @userinfobot. | |
TZ |
UTC |
Fallback timezone for schedulers that have no timezone set. | |
SCHEDULER_CONFIG |
data/schedulers.json |
Path of the JSON file that stores scheduler settings (relative to the working directory; /app/data/schedulers.json in Docker). Must be a real environment variable β it is read at import time, before .env is loaded, so setting it in .env has no effect. |
The bot exits at startup with a KeyError if any required variable is missing.
Example .env:
TELEGRAM_TOKEN=123456:ABCdefGHIjklMNOpqrSTUvwxYZ
AL_URL=https://adventure.example.com
AL_USERNAME=admin
AL_PASSWORD='secret'
ALLOWED_IDS=367468362,112233445| Command | Description |
|---|---|
/start |
Open the main menu. Also registers this chat as the target for scheduler messages. |
/schedulers |
Open the scheduler settings directly. |
Everything else is driven by inline buttons.
- My Trips β pick a trip β π Locations,
βοΈ Transportation, π Calendar, π Checklists, or π Recommendations nearby. Locations, Transportation, and Checklists appear only when the trip has that kind of data; Calendar appears when it has locations or transportation; Recommendations nearby is always shown and asks you to share your current location (π β Location) to search around it. - Search by keyword β type a word; the bot lists up to 10 matching locations and 5 matching trips.
- Where was I onβ¦ β type a date. Accepted formats:
DD.MM.YYYY,DD/MM/YYYY,DD.MM.YY,DD/MM/YY, andYYYY-MM-DD. - β° Schedulers β enable/disable and configure the daily messages (see Schedulers).
Inside a trip, π Locations offers three ways to browse:
- π Page one by one β step through the trip's visits (itinerary stops, sorted by start date) with βΉ Prev / Next βΊ, and tap Details for the location card.
- π List all β a paged list of all the trip's locations.
- π Search by name β type part of a location name.
A location card always offers Download docs (sends the location's attachments as files). If the location has coordinates, it also shows Apple Maps / Google Maps links, navigation buttons, and Recommendations nearby.
Send /start to open the main menu. Four options: My Trips, Search by keyword, Where was I onβ¦, and Schedulers.
![]() |
![]() |
| All collections from AdventureLog, each showing its date range. | Tap a trip to choose what to browse: Locations, Transportation, Calendar, Checklists, or Recommendations nearby. |
![]() |
![]() |
| Step through each stop in a trip. Tap Details to see the full location card, or Next to advance. | Calendar view lists all events in the trip (locations and transport) sorted by date. |
Each location shows its name, rating, description, and GPS coordinates. Buttons open Apple Maps, Google Maps, or start turn-by-turn navigation. Tap Recommendations nearby to find places around this location. Starting from the trip screen instead, the bot asks you to share your current Telegram location and searches around it.
![]() |
![]() |
![]() |
| Choose a category: Food, Lodging, or Tourism. | Choose a search radius: 5, 10, 20, or 50 km. | Up to 10 Google Places results with ratings, review count, and distance. Names link directly to Google. |
![]() |
![]() |
| All checklists for a trip, with item counts. | Tap any item to toggle it done/undone. Tap the trash icon to remove it. Use + Add item to append a new one. |
![]() |
![]() |
| Two built-in schedulers: Checklist reminder and Evening digest. Each shows its current on/off state. | Configure the evening digest: enable/disable, set the firing time, and set your timezone. |
Two built-in daily jobs, both disabled by default:
| Scheduler | Default time | What it sends |
|---|---|---|
| π Checklist reminder | 09:00 |
All checklists that still have unchecked items, grouped by trip. Nothing is sent when everything is done. |
| π Evening digest | 20:00 |
Tomorrow's plan: locations you are visiting and transportation departing tomorrow. Nothing is sent when tomorrow is empty. |
- Each scheduler has its own time (
HH:MM, 24-hour) and IANA timezone (e.g.Asia/Jerusalem). Without a timezone it uses theTZenvironment variable, thenUTC. - Settings are global for the bot instance (not per chat) and are saved to
SCHEDULER_CONFIG, so they survive restarts. - Messages go to the chat that most recently sent
/start. This target is kept in memory only: after a restart, send/startonce again, otherwise the jobs logno chat_id set, skippingand send nothing.
bot/
main.py # Entry point; wires all handlers
client.py # AdventureLog API client (httpx, session auth)
handlers.py # Core handlers: trips, locations, checklists, search
recommendations_handlers.py # Recommendations flow (ConversationHandler)
scheduler_handlers.py # Scheduler configuration handlers
scheduler_jobs.py # Scheduled job functions (checklist reminder, evening digest)
scheduler_store.py # Persist scheduler settings to data/schedulers.json
keyboards.py # Inline keyboard builders and date formatting
tests/ # pytest test suite
scripts/next-version.sh # Computes the next YYYY.M.PATCH release version
Requires AdventureLog v0.11 or newer β this version renamed "Adventures" to "Locations". Older instances use different API paths and are not supported.
- Set
ALLOWED_IDS. With it empty, anyone who finds your bot can browse and edit your AdventureLog data through the bot's account. - The bot holds your AdventureLog password in its environment. Keep
.envout of version control (it is already in.gitignore) and restrict who can read it. - Attachment downloads are only fetched from the same host as
AL_URL; links to other hosts are refused. - The Docker image runs as a non-root user (UID
10001). - Prefer an
https://AL_URL: the password is sent on eachPOST /login, and the session cookie on every later request.
The bot authenticates to AdventureLog with your username and password (a session login). Most "it's not working" reports come down to that sign-in failing. When it does, you'll see a clear line in the logs and a message in the chat instead of a silent empty result:
ERROR bot.client: AdventureLog login failed for user 'admin' (HTTP 400): ... β check AL_USERNAME/AL_PASSWORD.
A healthy start logs the opposite:
INFO bot.client: AdventureLog login succeeded for user 'admin'
This is almost always a sign-in failure, not missing data. Check the logs for the login failed line above, then work through the causes below.
If your password contains #, !, or $, an unquoted value in .env will be truncated or altered β # in particular is treated as the start of a comment, so AL_PASSWORD=My#Secret!Pass silently becomes My. Always quote it:
AL_PASSWORD='My#Secret!Pass'Then confirm the container actually received the full value (the definitive check):
docker compose exec adventurebot printenv AL_PASSWORD
# must print the complete password, not a truncated prefixIf printenv still shows a truncated value even when quoted, either move the variables into an env_file: (which parses quotes reliably) or change the AdventureLog password to one without #/!/$.
AdventureLog rate-limits repeated failed logins. After several bad attempts it will reject sign-in with an "invalid credentials" response for a cool-down window β even for the correct password. If you've been testing with a wrong password, wait a few minutes and try again, and avoid rapid retries.
The bot only sees data owned by the account it signs in as. AL_USERNAME must be the AdventureLog user that actually owns your collections/locations β a different or empty account will connect fine but show nothing. Verify by logging into the AdventureLog web UI with the same credentials and confirming your trips are there.
Scheduler messages are sent to the chat that last sent /start, and that chat is forgotten on restart. Send /start after every restart. Also check that the scheduler is enabled and that its timezone is what you expect (the detail screen shows the effective timezone).
The container runs as UID 10001. If the bind-mounted ./data directory is owned by another user, writing schedulers.json fails. Make it writable for that UID:
mkdir -p data && sudo chown 10001:10001 dataAdventureLog API keys are not used: on current instances /api/collections returns a 500 Internal Server Error under API-key authentication, so trips can't be listed. The bot therefore uses username/password session auth, which reads collections and locations correctly.
git clone https://github.com/t0mer/Adventurebot.git
cd Adventurebot
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt -r requirements-dev.txt
pytest-
Tests use
pytest,pytest-asyncio(asyncio_mode = "auto"inpyproject.toml), andrespxto mock AdventureLog HTTP calls β no live instance is needed. -
Build the image locally:
docker build -t adventurebot . -
Releases are built by the manually triggered Docker Build workflow (
.github/workflows/docker-image.yml), which computes aYYYY.M.PATCHversion withscripts/next-version.sh, tags the repo, and pushestechblog/adventurebot:latestandtechblog/adventurebot:<version>. A second manual workflow (.github/workflows/publish-ghcr.yml) publishes toghcr.io/t0mer/adventurebot.
Issues and pull requests are welcome. Please keep changes focused, add or update tests under tests/, and make sure pytest passes before opening a PR.
Licensed under the Apache License 2.0.












