Skip to main content

Telegram Setup

This guide walks you through setting up the Telegram bot frontend. Make sure you have completed the Installation steps first.

1. Create a Telegram Bot​

  1. Open Telegram and search for @BotFather.
  2. Send /newbot and follow the prompts to choose a name and username for your bot.
  3. Copy the bot token that BotFather gives you (it looks like 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11).

2. Configure Telegram Variables​

Add these to your .env file:

# Required: paste your BotFather token
TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

# Your Telegram user ID(s) for admin access (comma-separated)
# To find your ID, message @userinfobot on Telegram
ADMIN_USER_IDS=123456789

ADMIN_USER_IDS controls who can receive participant contact messages and manage the study. You can add multiple IDs separated by commas.

3. Run the Bot​

With localtunnel (recommended for local development):

./start.sh

This starts a localtunnel on port 8000 and passes the public URL as BASE_URL to the bot. This is required for cognitive assessment callbacks and wearable webhooks to reach your local machine. Press Ctrl+C to stop.

Without tunnel:

uv run python -m src.main

Use this when BASE_URL is already set in your .env (e.g., in production or when using your own tunnel).

A single process starts three services:

ServiceRole
Telegram botLong-polling for participant messages and survey responses
APSchedulerTimed survey delivery based on configured schedules
FastAPIHTTP API on port 8000 for REST endpoints and webhooks

4. Enroll Your First Participant​

Open Telegram and send /start to your bot. The enrollment flow has three steps:

  1. Password — Enter the study access password (default: ssrc, configurable via ACCESS_PASSWORD in .env).
  2. Consent — Read the study information and tap I Consent.
  3. Confirm — Tap Confirm to complete enrollment.

After enrollment, depending on your TUTORIAL_MODE setting (opt_in by default), the bot may offer a tutorial walkthrough of example surveys.

5. Verify Everything Works​

Once enrolled, try these commands in the bot:

  • /status — Shows your participant ID, enrollment date, and response counts.
  • /contact — Sends a message to the research team (forwarded to ADMIN_USER_IDS).
  • /check_in — Launches an on-demand survey (if configured).

Check the terminal running the bot — you should see log output confirming the enrollment and any survey activity.

Next Steps​