Telegram + Lark Base Conversational Bot

This backend runs a Telegram webhook bot that can:

• Reply to updates commands with status-count summaries (all-time by default; use last Nh for time filtering)
• Answer free-form questions using your configured Lark Base table as the knowledge source
• Stay grounded to Lark data (no general fallback answers)

Conversation behavior

• In group/supergroup chats, the bot replies only when mentioned (for example @GRID_TASK_UPDATES_BOT).
• In private chats, any non-empty message is processed.
• If a question cannot be answered from Lark Base, the bot replies with a strict not-found message and asks the user to rephrase.

Architecture

backend/app is organized as:

• api/v1/endpoints/: HTTP routes (/api/v1/health, /api/v1/telegram/webhook)
• api/dependencies.py: FastAPI dependency providers
• core/: typed settings, DI container, logging, app lifecycle
• services/: application business logic (intent, updates, KB answers, orchestration)
• repositories/: data access adapters
• clients/: Telegram, Lark, and OpenAI-compatible integrations
• models/: domain and DTO models
• utils/: parsing, formatting, and retrieval helpers

Quick start

cd backend
cp .env.example .env
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Required environment variables

Telegram:

• TELEGRAM_BOT_USERNAME
• TELEGRAM_BOT_TOKEN
• TELEGRAM_WEBHOOK_SECRET

Optional access control:

• ALLOWED_CHAT_IDS (leave empty to allow all chats)
• ALLOWED_USER_IDS (leave empty to allow all users)

Lark:

• LARK_API_BASE (default https://open.larksuite.com)
• LARK_APP_ID
• LARK_APP_SECRET
• LARK_BASE_APP_TOKEN
• LARK_BASE_TABLE_ID
• LARK_BASE_VIEW_ID (optional)

Core behavior defaults:

• DEFAULT_WINDOW_HOURS (default 24)
• MAX_ITEMS (default 10)
• REQUEST_TIMEOUT_SECONDS (default 15)

Conversational QA controls:

• ENABLE_CONVERSATIONAL_QA (default true)
• QA_TOP_K (default 5)
• QA_MIN_RELEVANCE_SCORE (default 0.5)
• QA_MAX_CONTEXT_CHARS (default 5000)
• QA_NOT_FOUND_MESSAGE (custom fallback text)

Optional OpenAI-compatible LLM (Groq-compatible):

• GROQ_API_BASE (default https://api.groq.com/openai)
• GROQ_API_KEY
• GROQ_MODEL (default openai/gpt-oss-20b)
• ENABLE_LLM_RESPONSE_POLISH (false by default)

Optional alias names also supported:

• LLM_API_BASE
• LLM_API_KEY
• LLM_MODEL

Deploy

1. Deploy backend/ as your web service.
2. Fill required environment variables.
3. Set Telegram webhook URL to https://<your-service>/api/v1/telegram/webhook.
4. Set webhook secret to match TELEGRAM_WEBHOOK_SECRET.

Smoke test your deployment

python3 backend/scripts/production_smoke.py \
  --base-url https://<your-service>.onrender.com \
  --webhook-secret <TELEGRAM_WEBHOOK_SECRET> \
  --bot-username <TELEGRAM_BOT_USERNAME> \
  --authorized-chat-id <ALLOWLISTED_CHAT_ID> \
  --authorized-user-id <ALLOWLISTED_USER_ID>

Manual checks in Telegram:

• @<TELEGRAM_BOT_USERNAME> updates
• @<TELEGRAM_BOT_USERNAME> how many done tickets for stefano?
• @<TELEGRAM_BOT_USERNAME> what is blocking grid release?

Lark field assumptions

The backend expects these Base columns:

• Text (or equivalent title field)
• Status
• Date Created (used as update time when UpdatedAt is unavailable)
• Assigned to (for assignee filtering)

Also supported when present:

• Numbering
• Ticket Type
• Estimated Deadline
• TicketURL (or Ticket URL, URL, Link)

If your table differs, adjust normalization in backend/app/clients/lark_client.py.