telegram-notification-tool

name	telegram-notification-tool
description	Use when configuring, testing, or explaining Qingcheng AI Telegram binding, AI-assistant chat bridging, proactive notification candidates, LLM send/skip decisions, cooldowns, quiet hours, or Telegram delivery failures.

Telegram Notification Tool

Tool Contract

Telegram is an AI assistant channel, not an interview channel. A web user generates a one-time bind code, sends /bind CODE in Telegram, and then Telegram messages reuse the same ChatService pipeline as /chat, including simple/agentic routing and AI assistant file memory.

Telegram must not create interview sessions or read interview agent_state. Telegram can create and manage AI-assistant scheduled tasks through the same database-backed scheduler as the web chat.

Proactive notifications are event-driven. Current candidates include resume parse completion/failure and stale application follow-up. Do not send daily onboarding or generic check-in messages. Delivery must respect TELEGRAM_ALLOWED_CHAT_IDS; test or stale accounts outside the allowlist are skipped.

Frontend Entry

The web entry is on /chat via TelegramBindCard in the session sidebar:

• Calls GET /api/v1/telegram/status first.
• Shows bound status, masked chat id, and enabled/disabled state when the user is already bound.
• Calls POST /api/v1/telegram/bind-code.
• Displays /bind CODE.
• Shows expiration time and copy action.
• Keeps copy short; no complex setup panel.

Script Usage

This skill has no application-data Python script. Use worker functions, API checks, and backend tests for validation.

Use the worker functions from the API container:

docker compose exec api python -c "from app.tasks.telegram_tasks import poll_telegram_updates_once; print(poll_telegram_updates_once())"
docker compose exec api python -c "from app.tasks.telegram_tasks import run_proactive_notifications_once; print(run_proactive_notifications_once(force=True))"
curl http://localhost:8000/api/v1/telegram/status -H "Authorization: Bearer <access_token>"
curl -X POST http://localhost:8000/api/v1/telegram/bind-code -H "Authorization: Bearer <access_token>"

Required .env values:

TELEGRAM_ENABLED=true
TELEGRAM_BOT_TOKEN=
TELEGRAM_ALLOWED_CHAT_IDS=123456789,@username
TELEGRAM_DEFAULT_USER_EMAIL=[e-mail]
TELEGRAM_BIND_CODE_TTL_MINUTES=10

Scheduled Task Commands

Telegram task commands:

• /tasks: list active scheduled tasks.
• /cancel_task <id-prefix>: cancel a task.
• /pause_task <id-prefix>: pause a task.
• /resume_task <id-prefix>: resume a task.

Natural language messages such as 每天早上 9 点提醒我看投递状态 also go through ChatService and can create tasks. Telegram-created task results are written to the task inbox and sent back to the same Telegram chat.

Output Contract

The bind-code API returns code, command, expires_at, and ttl_minutes; the database stores only code_hash. Polling returns processed updates. Proactive notification tick returns sent messages. Do not print bot tokens or raw Telegram payloads.

Answer Synthesis

Explain chat as: web bind code -> Telegram /bind CODE -> sticky chat_session_id -> ChatService -> Telegram reply. Mention phone commands when useful: /new, /new <message>, /current, /sessions, /use <session-prefix>, /tasks, /cancel_task, /pause_task, /resume_task, /stop. Explain proactive notifications as candidate event -> allowlist filter -> rule gate -> LLM send/skip -> Telegram delivery -> notification_events audit record.

Validation

python -m pytest backend/tests/telegram -q
python -m compileall -q backend/app
docker compose exec api python -c "from app.tasks.telegram_tasks import run_proactive_notifications_once; print(run_proactive_notifications_once(force=True))"
cd frontend
npm test