AI Telegram bot with conversation memory & tool use

Resume bullet (when finished)

“Shipped a production AI Telegram bot with multi-turn conversation memory, tool use (web search + calculator), Redis persistence, webhook deployment, and a small eval suite. 99.9% uptime over the first month.”

Locked tech stack

No "choose your language" — analysis paralysis kills completion. Follow the stack to the letter on your first build.

Milestones (7 · ~29h)

1. M1~3h

   Local echo bot — Telegram webhook reaches FastAPI

   Set up a bot via @BotFather. ngrok tunnels localhost. /api/telegram/webhook receives Update payloads and echoes the text back.

   CHECK BEFORE MOVING ON:

   • What's the difference between long-polling and webhooks for a Telegram bot?
   • Why must your webhook always respond <5s, even if the LLM call takes longer?
   $ git commit -m "feat: telegram webhook receiver + echo behaviour"
2. M2~3h

   Single-turn Claude call

   Replace the echo with a Claude API call (claude-opus-4-6, streaming off for simplicity). Reply text comes back to Telegram via the bot API.

   CHECK BEFORE MOVING ON:

   • Why call the API server-side instead of from the user's device?
   • What's `max_tokens` for and what happens if you set it too high?
   $ git commit -m "feat(ai): single-turn Claude response"
3. M3~5h

   Multi-turn memory via Redis

   Store conversation history keyed by `chat_id` in Redis. Pass last 10 messages (or last 4000 tokens — whichever is smaller) on each turn.

   CHECK BEFORE MOVING ON:

   • Why does the system message live OUTSIDE the rolling history?
   • What's the failure mode if you forget to truncate history?
   $ git commit -m "feat(memory): redis-backed multi-turn conversation context"
4. M4~6h

   Tool use — calculator + web search

   Declare two tools (`calculator(expression: str)`, `web_search(query: str)`). On `tool_use` stop reason, execute, append `tool_result`, loop until the model emits text.

   CHECK BEFORE MOVING ON:

   • Why does the spec require you to send tool_result back in the SAME ordering as tool_use blocks?
   • What's the safety risk of letting Claude call a calculator that uses `eval()` directly?
   $ git commit -m "feat(tools): calculator + web_search tool use loop"
5. M5~3h

   Rate limit + cost cap per chat_id

   5 messages/min per chat. 200 messages/day per chat. Friendly throttle message when hit. Each chat capped at $0.20/day in API spend (rough token counting).

   CHECK BEFORE MOVING ON:

   • Why per-chat rate limits matter even for an internal bot — what's the abuse vector?
   • What's a cheap way to estimate Claude input/output tokens without a tokenizer dep?
   $ git commit -m "feat: per-chat rate limit + daily cost cap"
6. M6~5h

   Eval suite — 30 golden conversations

   Build a `golden.jsonl` of 30 hand-crafted prompts with `must_include` / `must_not_include` checks. CI runs the eval; merge blocked on regression.

   CHECK BEFORE MOVING ON:

   • Why eval BEFORE you optimize the prompt, not after?
   • What's a good mix of happy-path / edge / adversarial in a 30-item eval set?
   $ git commit -m "test: 30-item golden eval suite + CI gate"
7. M7~4h

   Deploy to Fly.io with secrets + uptime probe

   Multi-stage Dockerfile, fly.toml with health check on /health, Telegram webhook re-registered to the public URL. UptimeRobot pings /health every 5 min.

   CHECK BEFORE MOVING ON:

   • Why store the Anthropic key in `fly secrets set` instead of fly.toml env?
   • What's a good action when /health flaps but uptime says 99.9%?
   $ git commit -m "ops: fly.io deploy with secrets + uptime probe"

60-second demo storyboard

What you say in the recruiter screen when they ask "tell me about your latest project." Practice it out loud.

1. 0-5s: 'I built an AI Telegram bot — conversation memory, tools, evals, the works.'
2. 5-15s: Send it 3 messages in a Telegram clip — it remembers context from message 1 in message 3.
3. 15-30s: 'Calculate 27 * 31 + sqrt(144).' — show tool_use roundtrip, the bot returns 849.
4. 30-45s: Show the eval suite running in CI — 28/30 passing, the 2 failing are flagged for review.
5. 45-55s: One architectural decision (e.g. 'I cap each chat at $0.20/day because…') in plain English.
6. 55-60s: 'Repo + deployment URL. Would love your feedback on the tool-loop error handling.'

STAR talking points for behavioral round

Production references — how grown-up systems do this

Self-review rubric (before you claim done)