.env.example

# Telegram API Credentials (Required - get from https://my.telegram.org/apps)
TELEGRAM_API_ID=123456
TELEGRAM_API_HASH=0123456789abcdef0123456789abcdef

# --- Incoming event feed (optional, Claude Code callback mode; see README) ---
# TELEGRAM_EVENT_FEED=1
# TELEGRAM_EVENT_FEED_FILE=/path/to/incoming_feed.jsonl

# --- Single account (backward-compatible) ---
# Option 1: File-based session (a .session file will be created)
TELEGRAM_SESSION_NAME=telegram_session
# Option 2: String-based session
# TELEGRAM_SESSION_STRING=1231231232erfdfdffd

# --- Multiple accounts ---
# Add _<LABEL> suffix to session variables. Labels become account identifiers.
# Shared API_ID and API_HASH are used for all accounts.
# TELEGRAM_SESSION_STRING_WORK=<session string for work account>
# TELEGRAM_SESSION_STRING_PERSONAL=<session string for personal account>

# --- Session pool (same account, concurrent clients) ---
# Run several MCP clients (e.g. the desktop app AND a terminal CLI) against ONE
# Telegram account without hitting AuthKeyDuplicatedError. Telegram forbids a
# single session (auth key) being used from two IPs at once; on a VPN/dual-stack
# host two local clients can collide. List several interchangeable session
# strings (whitespace, comma or semicolon separated) and each process claims a
# free one via an advisory file lock. Generate extra sessions with
# `uv run session_string_generator.py`. Takes precedence over
# TELEGRAM_SESSION_STRING for the default account.
# TELEGRAM_SESSION_STRINGS=<session A> <session B> <session C>

# --- Device identity (optional) ---
# Controls how this client appears in Telegram > Settings > Devices. If unset,
# Telethon falls back to the host platform (e.g. "arm64"). Set these so the
# session keeps a stable, recognisable name across reconnects. Applied both
# when generating a session string and when the server connects.
# TELEGRAM_DEVICE_MODEL=Telegram MCP
# TELEGRAM_SYSTEM_VERSION=1.0
# TELEGRAM_APP_VERSION=1.0

# --- MCP tool exposure (optional) ---
# Default is all. Set to read-only to expose only tools annotated with
# readOnlyHint=True through MCP. This does not reduce Telegram session authority
# inside the server process.
# TELEGRAM_EXPOSED_TOOLS=read-only
#
# Append '+name,name' to read-only to also expose specific write tools. Every
# other write tool stays unregistered. Unknown names abort startup.
# TELEGRAM_EXPOSED_TOOLS=read-only+send_message,reply_to_message

# --- File-path tools / allowed roots (optional) ---
# When the MCP client implements Roots but advertises an empty list — or when
# list_roots fails unexpectedly and no client paths can be recovered —
# file-path tools (download_media, send_file, ...) are disabled (deny-all) even
# if server CLI roots are configured. Set this to 1/true to fall back to the
# server CLI roots in those cases. Default is deny-all.
# TELEGRAM_ALLOW_SERVER_ROOTS_FALLBACK=1

# --- HTTP/SSE transport security (optional) ---
# Only relevant when MCP_TRANSPORT=http or sse. If the server is reachable via
# a domain (e.g. behind a reverse proxy) rather than only 127.0.0.1/localhost,
# set MCP_ALLOWED_HOSTS to enable DNS-rebinding protection and allow that Host
# header. Comma-separated; supports a ":*" suffix to allow any port.
# MCP_ALLOWED_HOSTS=mcp.example.com
# MCP_ALLOWED_ORIGINS=https://mcp.example.com

# --- Proxy (optional) ---
# Route Telegram traffic through a proxy. Set TELEGRAM_PROXY_TYPE to enable.
# Supported types: socks5, socks4, http, mtproxy.
# SOCKS/HTTP proxies require the 'python-socks' package (install via
# `uv sync --extra proxy` or `pip install python-socks`).
# Per-account overrides use the same _<LABEL> suffix as session variables.
# TELEGRAM_PROXY_TYPE=socks5
# TELEGRAM_PROXY_HOST=127.0.0.1
# TELEGRAM_PROXY_PORT=1080
# TELEGRAM_PROXY_USERNAME=<optional>
# TELEGRAM_PROXY_PASSWORD=<optional>
# TELEGRAM_PROXY_RDNS=true
# For MTProxy, set TELEGRAM_PROXY_TYPE=mtproxy and provide the secret:
# TELEGRAM_PROXY_SECRET=<hex secret>
# Per-account override example:
# TELEGRAM_PROXY_TYPE_WORK=http
# TELEGRAM_PROXY_HOST_WORK=proxy.work.example
# TELEGRAM_PROXY_PORT_WORK=3128

# --- Remembered contacts (optional) ---
# TELEGRAM_ALIASES_FILE=/path/to/aliases.json
# TELEGRAM_CONTACT_FUZZY=0   # exact-match aliases only

# --- Voice/video-note transcription (optional) ---
# off: transcribe_voice tool disabled, listings never show transcripts.
# on-demand (default): transcribe_voice works; get_history/get_messages/
#   list_messages fill in already-cached transcripts but never spend an API
#   call fetching a new one during a listing.
# auto: also prefetches missing transcripts during a listing, bounded by
#   TELEGRAM_TRANSCRIBE_MAX_VOICES / _MAX_SECONDS per call.
# TELEGRAM_TRANSCRIBE=on-demand
#
# Which engine transcribe_voice and auto-mode prefetch use by default (the
# per-call engine= argument always overrides this):
# - groq (default): Groq-hosted whisper-large-v3-turbo. Requires GROQ_API_KEY.
#   Downloads the voice note and sends it to Groq - leaves the server, not
#   free, but does not drop the recording's last words the way native
#   Telegram transcription does (proven 2026-08-20, see docs).
# - telegram: native Telegram Premium transcription. Free, audio never
#   leaves Telegram, but empirically drops the last speech segment in
#   roughly 2 of 3 recordings. Requires Telegram Premium on the account.
#   Use for chats that should never be sent to a third party.
# TELEGRAM_TRANSCRIBE_ENGINE=groq
# GROQ_API_KEY=<groq api key, required when engine=groq is ever used>
#
# Per-call budget for TELEGRAM_TRANSCRIBE=auto prefetch (ignored otherwise;
# transcribe_voice itself is never budget-limited since it's an explicit call).
# TELEGRAM_TRANSCRIBE_MAX_VOICES=5
# TELEGRAM_TRANSCRIBE_MAX_SECONDS=300
#
# Where the SQLite transcript cache lives. This is personal-chat text in
# plaintext on disk - keep it on a mounted volume (see docker-compose.yml) and
# in its own directory, not shared with backups of anything else. The file
# gets mode 600; the directory 700.
# TELEGRAM_TRANSCRIPT_CACHE_DIR=data/transcripts