Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/OPENNOVA2026/telegram-connector/llms.txt

Use this file to discover all available pages before exploring further.

Telegram Connector is configured entirely through environment variables. At startup, pydantic-settings reads values from the process environment or a .env file in the working directory and populates the Settings class defined in src/settings.py. The resulting singleton — settings — is imported throughout the codebase wherever configuration values are needed. No configuration files beyond .env are required.

​
Sample .env file

Copy the block below as a starting point. Required fields are marked in the comments; everything else has a sensible default. 
# Telegram API credentials (required)
API_ID=12345678
API_HASH=your_api_hash_here

# Application settings
ENVIRONMENT=production
SESSION=teleapp

# AWS S3 session persistence
AWS_REGION=us-east-1
AWS_S3_ENDPOINT=https://s3.amazonaws.com
AWS_ACCESS_KEY=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_S3_SESSION_BUCKET=my-telegram-sessions-bucket

# Sentry error monitoring (optional)
SENTRY_DSN=https://example@sentry.io/123
SENTRY_TSR=1.0

​
Variable reference

​
Application

​
NAME
string
default:"Telegram connector"
Human-readable application name surfaced in the auto-generated FastAPI /docs and /redoc pages. Override to distinguish multiple deployments in the Swagger UI title.
​
DESCRIPTION
string
Short description shown beneath the title in FastAPI’s interactive documentation. Populated directly from settings.description when the FastAPI() instance is created.
​
ENVIRONMENT
string
default:"local"
Deployment environment label (e.g. local, staging, production). Passed to Sentry as the environment tag so errors are grouped by environment in the Sentry dashboard. Has no effect on runtime behaviour beyond that.
​
SESSION
string
default:"teleapp"
Session name used as the S3 key prefix when persisting Telethon session data. The full S3 object key becomes telegram/{SESSION}/session.txt. Running multiple connectors pointing at the same bucket with distinct SESSION values keeps their authentication state isolated. See Session Persistence for details.

​
Telegram API credentials

​
API_ID
integer
default:"0"
Telegram API ID issued by my.telegram.org. Required for any real Telegram operations — channel listing, message retrieval, and authentication all depend on this value being set to a non-zero integer.
​
API_HASH
string
default:"\"\""
Telegram API hash paired with API_ID, also obtained from my.telegram.org. Must be set alongside API_ID to authenticate with Telegram’s MTProto API.
When API_ID is 0 (the default), channel listing and message retrieval endpoints automatically fall back to FakeClient, which returns synthetic data without touching the Telegram network. This is the recommended setup for local development when you do not yet have API credentials.

​
AWS S3 session storage

​
AWS_REGION
string
default:"\"\""
AWS region passed to the boto3 S3 client (e.g. us-east-1). Can be omitted when using a region-agnostic S3-compatible endpoint such as MinIO.
​
AWS_S3_ENDPOINT
string
default:"\"\""
Full endpoint URL passed directly to boto3.client() via endpoint_url (e.g. https://s3.amazonaws.com or http://localhost:9000 for MinIO). This value is always forwarded to the boto3 S3 client — when left empty, boto3 falls back to its default AWS endpoint resolution using AWS_REGION.
​
AWS_ACCESS_KEY
string
default:"\"\""
AWS access key ID used to authenticate S3 requests. If left empty, boto3 falls back to its standard credential chain (environment variables, IAM role, ~/.aws/credentials, etc.).
​
AWS_SECRET_KEY
string
default:"\"\""
AWS secret access key paired with AWS_ACCESS_KEY. Same fallback behaviour applies when left empty.
​
AWS_S3_SESSION_BUCKET
string
default:"nova-persistent-sessions-bucket"
Name of the S3 bucket where serialized Telethon session files are stored. The bucket must exist and the configured credentials must have s3:GetObject and s3:PutObject permissions on it before the service starts.

​
Sentry error monitoring

​
SENTRY_DSN
string
default:"\"\""
Data Source Name (DSN) for your Sentry project. When this variable is empty or unset, Sentry is completely disabled — no SDK initialization occurs and no data is sent. Set this to activate error and performance monitoring in non-local environments.
​
SENTRY_TSR
float
default:"1.0"
Sentry traces sample rate, expressed as a fraction between 0.0 and 1.0. 1.0 means every transaction is captured; 0.1 means 10 % are sampled. Lower this in high-traffic production deployments to control Sentry quota usage.

​
Sentry integration

Sentry is initialized by initialize_sentry() in src/settings.py, which is called once during application startup. The function is a no-op when SENTRY_DSN is empty, so there is no penalty for leaving it unset in development. When a DSN is provided, the SDK is configured with both the Starlette and FastAPI integrations, enabling automatic breadcrumb and transaction capture for every HTTP request handled by the application: 
sentry_sdk.init(
    dsn=settings.sentry_dsn,
    environment=settings.environment,
    traces_sample_rate=settings.sentry_tsr,
    integrations=[
        StarletteIntegration(),
        FastApiIntegration(),
    ],
)
The ENVIRONMENT variable is forwarded as the Sentry environment tag, making it straightforward to filter issues by deployment stage in the Sentry UI.

Build docs developers (and LLMs) love

Get started for freeTalk to us