Configuration
All configuration is done through environment variables, typically set in a .env file at the project root. The bot uses Pydantic Settings to load and validate these values at startup.
Core Settings
| Variable | Description | Default |
|---|---|---|
TELEGRAM_BOT_TOKEN | Bot token from BotFather. | required |
ADMIN_USER_IDS | Comma-separated Telegram user IDs for admin access. | [] |
API_KEY | Secret key for authenticating HTTP API requests (sent as Authorization: Bearer <key>). | changeme |
DATABASE_PATH | Path to the SQLite database file. Created automatically if it does not exist. | data/esm_bot.db |
API_HOST | Host address the FastAPI server binds to. | 0.0.0.0 |
API_PORT | Port the FastAPI server listens on. | 8000 |
SURVEYS_DIR | Directory containing survey YAML definition files. | src/surveys |
SURVEY_TIMEOUT_MINUTES | Number of minutes before an unanswered survey session expires. | 30 |
BASE_URL | Public URL of the API server, used for cognitive assessment callbacks and wearable webhooks. When using ./start.sh, this is set automatically via localtunnel. | http://localhost:8000 |
ASSESSMENT_BASE_URL | URL path or base URL where m2c2kit cognitive assessments are hosted. | /webapp/m2c2/ |
ACCESS_PASSWORD | Password participants must enter during enrollment. | ssrc |
TUTORIAL_MODE | Controls tutorial behavior for cognitive assessments. Options: opt_in, always, or disabled. | opt_in |
Wearable Device Integration
These variables are only required if you enable wearable device integrations. Each provider needs its own OAuth client credentials.
Withings
| Variable | Description |
|---|---|
WITHINGS_CLIENT_ID | OAuth client ID from the Withings Developer Portal. |
WITHINGS_CLIENT_SECRET | OAuth client secret for Withings. |
Fitbit
| Variable | Description |
|---|---|
FITBIT_CLIENT_ID | OAuth client ID from the Fitbit Developer Portal. |
FITBIT_CLIENT_SECRET | OAuth client secret for Fitbit. |
FITBIT_SUBSCRIPTION_VERIFICATION_CODE | Verification code used by Fitbit to confirm your webhook endpoint. |
Oura
| Variable | Description |
|---|---|
OURA_CLIENT_ID | OAuth client ID from the Oura Developer Portal. |
OURA_CLIENT_SECRET | OAuth client secret for Oura. |
Token Encryption
| Variable | Description |
|---|---|
DEVICE_TOKEN_ENCRYPTION_KEY | A Fernet symmetric encryption key used to encrypt OAuth tokens at rest in the database. Generate one with python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())". |
Web Push Notifications (VAPID)
These variables are required to send push notifications to PWA participants. Generate a VAPID key pair with:
npx web-push generate-vapid-keys
| Variable | Description |
|---|---|
VAPID_PRIVATE_KEY | VAPID private key (base64-encoded). |
VAPID_PUBLIC_KEY | VAPID public key (base64-encoded). Shared with the PWA frontend for push subscription. |
VAPID_CLAIMS_EMAIL | Contact email included in VAPID claims (e.g., mailto:you@example.com). |
Example .env File
# Required
TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
# Admin
ADMIN_USER_IDS=123456789,987654321
# API
API_KEY=your-secret-api-key
BASE_URL=https://your-domain.com
# Enrollment
ACCESS_PASSWORD=your-study-password
# Wearables (optional)
WITHINGS_CLIENT_ID=...
WITHINGS_CLIENT_SECRET=...
DEVICE_TOKEN_ENCRYPTION_KEY=...
# Web Push (optional)
VAPID_PRIVATE_KEY=...
VAPID_PUBLIC_KEY=...
VAPID_CLAIMS_EMAIL=mailto:researcher@university.edu