fdaa-tg-ai

Open beta CLI/TUI for Telegram Chat Automation, Guest Mode, and OpenRouter.

The target user is someone who wants to run their own Telegram AI operator without a hosted dashboard. The CLI creates local config, reads secrets from env, can run locally with polling, and can be deployed as a hosted process with Telegram HTTPS webhooks.

Quickstart

npm install -g fdaa-tg-ai
fdaa-tg-ai setup
fdaa-tg-ai run

The setup wizard asks for:

• BOT TOKEN
• OPENROUTER API KEY
• product mode: responder or summarizer
• allowlist ID for Guest Mode
• deploy mode: local or host
• prompts and summary chat IDs

Secrets are written to .env.local. Product settings are written to .fdaa/tg-ai.json.

Deploy Modes

local uses Telegram getUpdates polling. It is good for testing and personal development. When fdaa-tg-ai run starts in local mode, it disables any existing Telegram webhook without dropping pending updates, then prints bot, webhook, store, and offset diagnostics.

host is more stable for real usage. Deploy the process to Railway/Fly/Render/VPS, set PUBLIC_BASE_URL to the HTTPS URL, then run:

fdaa-tg-ai set-webhook

Commands

fdaa-tg-ai                 # open TUI
fdaa-tg-ai setup           # setup wizard
fdaa-tg-ai status          # bot, webhook, chats
fdaa-tg-ai set-webhook     # set Telegram HTTPS webhook
fdaa-tg-ai run             # local polling operator
fdaa-tg-ai reset-state     # clear local Telegram offset/store, keep secrets
fdaa-tg-ai summary         # send daily summary now

For a clean video/test run: run fdaa-tg-ai setup, start fdaa-tg-ai run, then connect the bot in Telegram Chat Automation and send a fresh message. If you disconnect/reconnect the bot while testing, run fdaa-tg-ai reset-state before the next run so old offsets and stale business_connection_id values are cleared.

macOS background run

Use caffeinate as the command wrapper. Do not run caffeinate && fdaa-tg-ai run; that waits for caffeinate to exit first.

mkdir -p ~/.fdaa
nohup caffeinate -dimsu fdaa-tg-ai run >> ~/.fdaa/tg-ai.log 2>&1 &
tail -f ~/.fdaa/tg-ai.log

Runtime behavior

The polling worker is fault-tolerant by default:

• one failed Telegram update is logged and skipped without stopping the process;
• Telegram and OpenRouter network calls retry transient failures;
• OpenRouter falls back through OPENROUTER_FALLBACK_MODELS or the built-in fallback list;
• several updates can be processed concurrently with FDAA_TG_AI_CONCURRENCY;
• expired Guest Mode queries are skipped instead of crashing after Telegram's short answer window closes;
• stale/invalid Chat Automation business connections are removed and logged so reconnecting the bot recovers cleanly;
• media-only messages do not hit the model yet; the bot replies that text/caption input is supported.

Responder mode sends only the current message to the model. It does not include other chats in the prompt. Stored chat messages are kept per chat and are used by summarizer mode only for selected chat IDs.

Telegram Bot API updates are incremental. The bot receives new updates delivered through polling/webhooks; Guest Mode does not provide chat history, and Chat Automation does not dump the full existing chat history into the model.

Modes

responder replies in connected 1-to-1 Telegram chats through business_connection_id and answers allowlisted Guest Mode mentions.

Guest Mode is allowlist-only. Add Telegram numeric user IDs during setup; mentions from everyone else are ignored.

summarizer stores visible chats, lets the user choose chat IDs, and sends a daily Telegram DM summary to the owner.

Required Env

TELEGRAM_BOT_TOKEN=
OPENROUTER_API_KEY=
OPENROUTER_MODEL=google/gemini-3.1-flash-lite
OPENROUTER_FALLBACK_MODELS=google/gemini-2.5-flash-lite,openai/gpt-4o-mini
OPENROUTER_TIMEOUT_MS=12000
FDAA_TG_AI_CONCURRENCY=4
PUBLIC_BASE_URL=https://your-host.example
TELEGRAM_WEBHOOK_SECRET=