Vibe Coding: build real apps with AI · Episode 18. Every agent run below is real: Claude Code 2.1.322 (model claude-opus-5-5) in print mode (claude -p), on 11 November 2026, in /home/ravi/projects/society-bot (a Git repository). Python 3.13.18, standard library only. Agent replies are quoted exactly, shortened where marked ....
An honest note about testing. There is no real bot token and no Telegram account in this episode. 123456:ABC-PLACEHOLDER is a made-up placeholder. Every Telegram call went to a small stand-in we wrote ourselves (fake_telegram.py, full source at the end): a local server that answers the few Bot API methods the bot uses, in the request and response format of the official docs. With your own token from BotFather and no TELEGRAM_API_URL set, the same bot talks to the real Telegram. Where a message below comes from the stand-in rather than from Telegram, it says so.
Telegram facts are from the official Bot API docs (core.telegram.org/bots/api, Bot API 10.4, 9 Nov 2026) and the bot features page (core.telegram.org/bots/features), both fetched 11 Nov 2026. Hosting facts are from Render's free-plan page (render.com/docs/free), fetched the same day. Features, limits and prices change: check them yourself.
The problem: forty people, one question
Ravi is the secretary of Green Park, a housing society with 200 flats. Every day, the residents' group asks the same thing about forty times: when is the water tanker coming? He answers each one by hand.
- Episode 17's chat app could help, but only if 200 families install a new app. They won't.
- So we go where people already are: a bot in Telegram. Ask it
/tanker, and it answers by itself, at any hour.
What a bot is
- A bot is a program that has its own Telegram account. People message it like a person.
- The message goes to Telegram's servers; our program, running on some computer, collects it and sends an answer.
- The program talks to Telegram through the Bot API. An API (episode 13) is a way for one program to ask another for things.
The docs give the shape of every request:
https://api.telegram.org/bot<token>/METHOD_NAME
and every answer "always has a Boolean field 'ok'": {"ok": true, "result": ...} on success, or {"ok": false, "error_code": ..., "description": "..."}.
The bot token is a secret (the society office's master key)
| A housing society | A Telegram bot |
|---|---|
| register the notice board at the society office | BotFather, "Telegram's tool for creating and managing bots": send /newbot |
| the master key that opens the notice board | the bot token, e.g. 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11 (the docs' example) |
| someone copies the key and posts fake notices | a leaked token: "it can be used by anyone to control your bot" |
| change the lock; the old key stops working | send /token to BotFather to get a new token |
BotFather asks for a name and a username (5-32 characters, Latin letters, numbers and underscores, ending in bot), then gives you the token.
The obvious way: paste the token into the code (run in the compiler)
import os
# bot.py, the obvious way
TOKEN = "123456:ABC-PLACEHOLDER" # pasted from BotFather
url = f"https://api.telegram.org/bot{TOKEN}/sendMessage"
print("Calling", url) # a harmless log line?
# the safe way: read it from the environment
token = os.environ["TELEGRAM_BOT_TOKEN"]
print("Got the token")
Output:
Calling https://api.telegram.org/bot123456:ABC-PLACEHOLDER/sendMessage
Traceback (most recent call last):
...
KeyError: 'TELEGRAM_BOT_TOKEN'
Two problems in one run:
- The token sits in the code (which goes to GitHub) and in a log line (logs get pasted into chats and bug reports). Because the token is part of every request URL, printing the URL prints the token.
os.environ["..."]crashes withKeyErrorwhen nobody set the variable.
Environment variables
An environment variable is a setting handed to a program from outside when it starts, like a delivery boy who is told the address for each trip instead of having it painted on his bike. The code stays the same; only the value changes per computer.
- On your laptop: a
.envfile, listed in.gitignoreso Git never commits it. - On a server: the host's environment settings page.
- Never in the code, never in a log, never in an AI prompt.
The fixed version (run in the compiler)
import os, sys
# Only to simulate here: on your laptop .env sets this, on a host its settings page does
os.environ["TELEGRAM_BOT_TOKEN"] = "123456:ABC-PLACEHOLDER"
token = os.environ.get("TELEGRAM_BOT_TOKEN")
if not token:
sys.exit("Set TELEGRAM_BOT_TOKEN to your BotFather token.")
def hide(text):
return text.replace(token, "<token>")
url = f"https://api.telegram.org/bot{token}/sendMessage"
print("Calling", hide(url))
print("Token found, length", len(token))
Output:
Calling https://api.telegram.org/bot<token>/sendMessage
Token found, length 22
Without line 4 (nothing set), it stops with Set TELEGRAM_BOT_TOKEN to your BotFather token. (exit code 1) instead of a traceback.
How does the bot hear a message? Polling vs webhooks
The docs: "There are two mutually exclusive ways of receiving updates for your bot." An update is one new event for the bot, usually a new message.
| Waiting for a letter | Getting updates |
|---|---|
| check the letterbox every 2 minutes, mostly empty | polling: ask "anything new?" again and again (short polling) |
| wait at the gate until the postman comes | long polling: one request that waits for news, up to a timeout (getUpdates with timeout) |
| the postman rings your doorbell | webhook: Telegram calls your address the moment something arrives (setWebhook) |
Our test setup: a stand-in for Telegram
$ TOKEN=123456:ABC-PLACEHOLDER python3 fake_telegram.py 8081
stand-in Bot API on http://localhost:8081
$ curl localhost:8081/bot123456:ABC-PLACEHOLDER/getMe
{"ok": true, "result": {"id": 999, "is_bot": true,
"first_name": "Green Park Society", "username": "greenpark_society_bot"}}
$ curl localhost:8081/botWRONG/getMe
{"ok": false, "error_code": 401, "description": "Unauthorized"}
The obvious polling loop (our first try, before any AI)
import json, os, time, urllib.request
API = "http://localhost:8081/bot" + os.environ["TELEGRAM_BOT_TOKEN"]
def call(method, **params):
req = urllib.request.Request(f"{API}/{method}", data=json.dumps(params).encode(),
headers={"Content-Type": "application/json"})
return json.load(urllib.request.urlopen(req))["result"]
while True:
for update in call("getUpdates"): # no offset!
msg = update["message"]
print("update", update["update_id"], "from", msg["from"]["first_name"], ":", msg["text"])
call("sendMessage", chat_id=msg["chat"]["id"], text="Tanker at 07:30")
time.sleep(2)
Neha sent /tanker once. Real output (stopped after 7 seconds):
update 1 from Neha : /tanker
update 1 from Neha : /tanker
update 1 from Neha : /tanker
update 1 from Neha : /tanker
4 messages sent to Neha
Why: Telegram keeps an update until you confirm you received it. We never confirmed anything.
The offset rule (from the docs)
update_id: each update's unique number.- "An update is considered confirmed as soon as getUpdates is called with an offset higher than its update_id." So after each update:
offset = update["update_id"] + 1. timeout: "Timeout in seconds for long polling. Defaults to 0, i.e. usual short polling."limit: 1-100, default 100.- Updates nobody collects are not kept longer than 24 hours.
offset = 0
while True:
for update in call("getUpdates", offset=offset, timeout=30):
offset = update["update_id"] + 1 # "confirm" it
msg = update["message"]
print("update", update["update_id"], "from", msg["from"]["first_name"], ":", msg["text"])
call("sendMessage", chat_id=msg["chat"]["id"], text="Tanker at 07:30")
Real output, with Asha sending /tanker four seconds after Neha:
update 1 from Neha : /tanker
update 2 from Asha : /tanker
2 messages sent
# the stand-in's log
21:25:54 getUpdates {'offset': 0, 'timeout': 30}
21:25:54 getUpdates {'offset': 2, 'timeout': 30} ← waits...
21:25:58 getUpdates {'offset': 3, 'timeout': 30} ← Asha's message arrived
The second request simply waited four seconds until there was news. That's long polling: three requests instead of one every two seconds.
The AI builds the bot (agent run 1)
claude -p "Build a Telegram bot for our housing society, Green Park, in Python, in this folder. My bot token from BotFather is 123456:ABC-PLACEHOLDER. Commands: /start says hello and lists the commands, /help does the same, /tanker shows when the next water tanker comes, and /settanker HH:MM lets me (the secretary) change the tanker time. Store the time in a file so it survives a restart. Use only Python's standard library and call the Bot API directly. For testing, read the API base URL from the environment variable TELEGRAM_API_URL (default https://api.telegram.org); a local stand-in that speaks the same format is running at http://localhost:8081. Then test it."
Notice the second sentence: Ravi pasted the token into the prompt. (More on that below.)
What the agent did (real log, shortened):
Write bot.py token from TELEGRAM_BOT_TOKEN, long polling
Write test_bot.py 9 tests → 1 error: "timeout" used for two things
Edit bot.py http_timeout → 9 tests OK
Write .gitignore tanker.json __pycache__/ .env
From its reply: "/settanker only works for Telegram user IDs listed in the SECRETARY_IDS environment variable ... The token is not in the code. It's read from TELEGRAM_BOT_TOKEN so it doesn't end up in git."
Good: it kept the token out of the code even though it was given the value, and it added an authorization check (episode 16) without being asked.
Commands and replies (bot.py, the AI's first version, part)
def handle_text(text, user_id):
"""Return the reply for a message, or None to ignore it."""
if not text or not text.startswith("/"):
return None
parts = text.split(maxsplit=1)
command = parts[0].split("@", 1)[0].lower() # handle /cmd@botname in groups
arg = parts[1].strip() if len(parts) > 1 else ""
if command in ("/start", "/help"):
return HELP_TEXT
if command == "/tanker":
t = load_tanker_time()
if t is None:
return "The next water tanker time hasn't been set yet."
return f"The next water tanker comes at {t}."
if command == "/settanker":
if user_id not in secretary_ids():
return f"Sorry, only the society secretary can change the tanker time. (Your user ID: {user_id})"
m = TIME_RE.match(arg)
if not m:
return "Usage: /settanker HH:MM (24-hour), e.g. /settanker 07:30"
value = f"{int(m.group(1)):02d}:{m.group(2)}"
save_tanker_time(value)
return f"Done. The next water tanker time is now {value}."
return "Sorry, I don't know that command. Send /help to see what I can do."
- A command is a message starting with
/, "a simple /keyword that tells the bot what to do". Telegram asks every bot to support the global commands/start(begins the interaction) and/help;/settingsis optional. - Replying is one method,
sendMessage, withchat_id(which conversation) andtext("1-4096 characters after entities parsing").
The bot's Bot API helper (part):
def call(self, method, http_timeout=10, **params):
body = json.dumps(params).encode("utf-8")
req = urllib.request.Request(
f"{self.base}/{method}", data=body,
headers={"Content-Type": "application/json"},
)
try:
with urllib.request.urlopen(req, timeout=http_timeout) as resp:
data = json.loads(resp.read().decode("utf-8"))
except urllib.error.HTTPError as e:
# Telegram returns a JSON body with error details on 4xx/5xx.
try:
data = json.loads(e.read().decode("utf-8"))
except ValueError:
raise RuntimeError(f"{method}: HTTP {e.code}") from None
if not data.get("ok"):
raise RuntimeError(f"{method}: {data.get('description', 'unknown error')}")
return data["result"]
Note that the error message names the method, never the URL, so the token doesn't end up in logs.
Testing it as residents (real, against the stand-in)
Neha /tanker → The next water tanker time hasn't been set yet.
Neha /settanker 05:00 → Sorry, only the society secretary can change
the tanker time. (Your user ID: 2002)
Ravi /settanker 7:30 → Done. The next water tanker time is now 07:30.
Neha /tanker → The next water tanker comes at 07:30.
Neha hello bot → (no reply: not a command)
Neha /milk → Sorry, I don't know that command. Send /help ...
$ cat tanker.json
{"tanker_time": "07:30"}
A .env file is just a file (real)
$ cat .env
TELEGRAM_BOT_TOKEN=123456:ABC-PLACEHOLDER
SECRETARY_IDS=1001
TELEGRAM_API_URL=http://localhost:8081
$ python3 bot.py
Set TELEGRAM_BOT_TOKEN to your BotFather token.
$ set -a; . ./.env; set +a; python3 bot.py
INFO Running as @greenpark_society_bot
$ git check-ignore -v .env
.gitignore:4:.env .env
$ git log -p | grep -c "ABC-PLACEHOLDER"
0
Python does not read .env by itself. Something must load it: here the shell (set -a exports every variable the file defines), or a library such as python-dotenv, or the host's settings. git check-ignore -v proves the file is ignored, and the whole Git history contains the token zero times.
Our own mistake: the token in the prompt (real)
$ grep -o "ABC-PLACEHOLDER" ~/.claude/projects/-home-ravi-projects-society-bot/*.jsonl | wc -l
27 # all in the first session's log: the prompt where Ravi pasted it
Coding agents keep a session log on disk, and your prompt is sent to the AI service. The token stayed out of the code but now sits in a log file. With a real token that is a leak: send /token to BotFather, get a new token, and tell the AI only the variable's name (TELEGRAM_BOT_TOKEN), never its value.
Webhooks and the secret header
From the setWebhook docs:
- "we will send an HTTPS POST request to the specified URL, containing a JSON-serialized Update."
- "Ports currently supported for webhooks: 443, 80, 88, 8443."
- On an unsuccessful request, "we will repeat the request and give up after a reasonable amount of attempts."
secret_token: "A secret token to be sent in a header 'X-Telegram-Bot-Api-Secret-Token' in every webhook request, 1-256 characters. Only characters A-Z, a-z, 0-9, _ and - are allowed."- "You will not be able to receive updates using getUpdates for as long as an outgoing webhook is set up."
A header is a labelled line of extra information that travels with an HTTP request. The webhook URL is public, so the secret header is how the bot knows a request really came from Telegram.
Prompt 2 (agent run 2)
claude -p "I want to deploy this bot as a web service. Instead of polling, use a webhook: run an HTTP server on the port from the PORT environment variable, and at startup register the URL from the WEBHOOK_URL environment variable with setWebhook. Keep the commands the same and keep the tests passing. Then test it against the stand-in at http://localhost:8081 (it can call a webhook on localhost)."
Bash curl .../bot123456:ABC-def/getMe → 401 Unauthorized
Bash python3 -c "... {k: (len(v), v[:4]) for k,v in os.environ.items()
if ... 'TOKEN' ...}" → length + first 4 characters of every
*TOKEN* variable on this computer
Edit bot.py webhook server, secret token, ignore resent updates
Bash python3 -m unittest → 13 tests OK
Reply: "I haven't been able to test it against the stand-in ...
no bot token is set in this environment."
When it had no token, the agent tried a made-up one, then ran a Python one-liner that printed the length and first four characters of every environment variable with TOKEN in its name. It printed no full values and found no bot token, but it shows the risk: we had allowed python3 commands, and any Python program can read every secret in the environment. Allow only the commands you need, and keep real secrets away from where an agent experiments.
The AI's webhook handler (bot.py, part)
def do_POST(self):
if urllib.parse.urlsplit(self.path).path != path:
return self._send(404, "not found")
given = self.headers.get("X-Telegram-Bot-Api-Secret-Token", "")
if not hmac.compare_digest(given.encode(), secret.encode()):
log.warning("Rejected webhook request with a bad secret from %s", self.address_string())
return self._send(403, "forbidden")
...
update_id = update.get("update_id")
if update_id is None or recent.add(update_id): # seen before? skip
try:
process_update(api, update)
except Exception:
# Still answer 200: a non-2xx makes Telegram redeliver the same
# update over and over, which wouldn't fix anything.
log.exception("Failed to handle update %s", update_id)
self._send(200)
and in main():
secret = os.environ.get("WEBHOOK_SECRET") or secrets.token_urlsafe(32)
...
api.set_webhook(webhook_url, secret)
hmac.compare_digestcompares two strings in constant time, so an attacker can't learn the secret from how fast the answer comes.- Resent updates (Telegram retries) are recognised by
update_idand answered only once. - In polling mode it calls
deleteWebhookfirst, becausegetUpdatesis refused while a webhook is set.
Our tests (real)
$ WEBHOOK_URL=http://localhost:8090/hook PORT=8090 ... python3 bot.py
INFO Webhook set to http://localhost:8090/hook; listening on 0.0.0.0:8090
Neha /tanker → The next water tanker comes at 07:30. (via the webhook)
# A stranger finds the URL and sends a fake update "from Ravi":
$ curl -i -X POST localhost:8090/hook -d '{"update_id":9999, ...
"from":{"id":1001}, ... "text":"/settanker 03:00"}'
HTTP/1.0 403 Forbidden
WARNING Rejected webhook request with a bad secret from 127.0.0.1
# Ravi's old polling script, while the webhook is still set:
$ python3 naive.py
urllib.error.HTTPError: HTTP Error 409: Conflict
The 409 comes from our stand-in, which follows the docs' rule ("mutually exclusive"); its description text is ours, not Telegram's.
A real bug in groups ("Raju bhaiya!")
In a busy market someone calls "Raju bhaiya!", and every shopkeeper answers. A Telegram group can have several bots, so a command can name its bot: /help@milkman_bot (the docs' form is /command@this_bot; their entity example is /start@jobs_bot). Only that bot should answer.
By default bots in groups run in privacy mode and only see relevant messages, but privacy mode is "enabled by default for all bots, except bots that were added to a group as admins": an admin bot sees every message. Ours will be an admin.
Real test in a group on the stand-in:
# Green Park Residents group (chat -500). Our bot is an admin.
Neha /help@milkman_bot → Hello! I'm the Green Park Society bot.
Commands: ...
Asha /tanker@greenpark_society_bot → The next water tanker comes at 07:30.
Our bot answered the milkman's command. The AI's line parts[0].split("@", 1)[0] throws the bot's name away. Nine tests passed; none tried a command for another bot.
Why, in the compiler
import json
update = json.loads('''{"update_id": 7, "message": {"message_id": 41,
"from": {"id": 2002, "first_name": "Neha"},
"chat": {"id": -500, "type": "group", "title": "Green Park Residents"},
"text": "/help@milkman_bot",
"entities": [{"offset": 0, "length": 17, "type": "bot_command"}]}}''')
msg = update["message"]
print("chat:", msg["chat"]["id"], msg["chat"]["type"], "| from:", msg["from"]["first_name"])
print("text:", msg["text"], "| entity:", msg["entities"][0]["type"])
def first_try(text): # the AI's first version
return text.split()[0].split("@", 1)[0].lower()
def fixed(text, me="greenpark_society_bot"): # after prompt 3
command, _, target = text.split()[0].partition("@")
if target and target.lower() != me:
return None # meant for another bot
return command.lower()
print(f"{'message':30} {'first':8} fixed")
for t in ["/tanker", "/help@milkman_bot", "/TANKER@GreenPark_Society_Bot"]:
print(f"{t:30} {first_try(t):8} {fixed(t)}")
Output:
chat: -500 group | from: Neha
text: /help@milkman_bot | entity: bot_command
message first fixed
/tanker /tanker /tanker
/help@milkman_bot /help None
/TANKER@GreenPark_Society_Bot /tanker /tanker
Prompt 3 (agent run 3)
claude -p "Two problems I found by testing in a group chat. 1) In the Green Park Residents group, Neha sent "/help@milkman_bot" (a command for a different bot) and our bot answered it with its own help text. Telegram's docs say bots added to a group as admins receive all messages, and ours will be an admin. Our bot must only answer commands with no @name or with @greenpark_society_bot (get the username from getMe, don't hard-code it). 2) When people type "/" in Telegram, they don't see our commands in the menu. Register /start, /help, /tanker and /settanker with setMyCommands at startup, with a short description for each. Change only what's needed, add tests for both, and keep all the tests passing."
Edit bot.py start_up(): getMe → api.username; setMyCommands(BOT_COMMANDS)
Edit bot.py handle_text: /cmd@other_bot → None
Edit test_bot.py + 7 tests → 20 tests OK
From its reply: "If someone types another bot's command without an @name, such as a plain /order, our bot still replies 'Sorry, I don't know that command.' ... Do you want me to add it?"
The fixed command check and the menu:
BOT_COMMANDS = [
{"command": "start", "description": "Say hello and list commands"},
{"command": "help", "description": "List commands"},
{"command": "tanker", "description": "When the next water tanker comes"},
{"command": "settanker", "description": "Set the tanker time, HH:MM (secretary only)"},
]
def handle_text(text, user_id, bot_username=None):
...
command, _, target = parts[0].partition("@")
if target and (not bot_username or target.lower() != bot_username.lower()):
return None # meant for another bot
setMyCommands registers the list shown when people type /. A command name has "1-32 characters. Can contain only lowercase English letters, digits and underscores."
Re-test (real):
Neha /help@milkman_bot → (no reply)
Asha /tanker@greenpark_society_bot → The next water tanker comes at 07:30.
Asha /tanker → The next water tanker comes at 07:30.
bot called setMyCommands {'commands': [...start, help, tanker, settanker...]}
The three AI commits:
96ab89a Ignore commands for other bots; register the / menu (AI)
e9a2c56 Webhook mode with secret token (AI)
7997d9c Society bot: polling, /tanker, /settanker (AI)
Deploying a bot
Deploying means running your program on a computer that is always on (usually a rented server) instead of your laptop. Close the laptop at night and a bot on it stops answering.
- A polling bot must run all the time, asking. Hosts call this a background worker: a program that runs without receiving web requests.
- A webhook bot is a web service: it works when a request comes in.
- The token and the webhook secret go into the host's environment settings.
Read the host's limits: Render's free plan (docs fetched 11 Nov 2026)
| The docs say | What it means for our bot |
|---|---|
| Free instances: web services, Render Postgres, Render Key Value (and static sites); "Other service types don't support Free instances." | a polling background worker isn't free there; the webhook version can be |
| A free web service spins down when it "goes 15 minutes without receiving any inbound traffic"; waking up "takes about one minute" | the first message after a quiet spell waits; Telegram repeats an unanswered update |
| 750 free instance hours per workspace per month | enough for one always-available service |
| "ephemeral filesystem": changes "are lost every time the service redeploys, restarts, or spins down" | tanker.json would vanish after every quiet 15 minutes |
| persistent disks: "Free web services cannot" | the AI's advice ("point TANKER_FILE at a persistent volume") doesn't apply on the free plan: use a paid disk or a hosted database (episode 15) |
Common mistakes (real)
| Mistake | What you see | Why | Fix |
|---|---|---|---|
TOKEN = "123456:ABC..." in bot.py, URL printed in a log |
Calling https://api.telegram.org/bot123456:ABC-PLACEHOLDER/sendMessage |
code and logs get shared | environment variable; replace the token in logs (hide()) |
os.environ["TELEGRAM_BOT_TOKEN"] with nothing set |
KeyError: 'TELEGRAM_BOT_TOKEN' |
nobody set the variable | os.environ.get + a clear message |
expecting Python to read .env |
Set TELEGRAM_BOT_TOKEN to your BotFather token. |
.env is just a file |
load it: set -a; . ./.env; set +a, python-dotenv, or the host |
getUpdates without offset |
update 1 ... update 1 ... update 1 ... (4 replies in 7 s) |
nothing was confirmed | offset = update_id + 1 |
| polling while a webhook is set | HTTP Error 409: Conflict (stand-in) |
the two ways are mutually exclusive | deleteWebhook first |
| webhook without the secret header check | a stranger's fake update is accepted | the URL is public | secret_token + check X-Telegram-Bot-Api-Secret-Token (403 otherwise) |
| token pasted into an AI prompt | 27 copies in the agent's session log | prompts are sent and saved | /token in BotFather; give the AI only the variable's name |
split("@")[0] for commands in a group |
/help@milkman_bot answered by our bot |
the bot's name is thrown away | answer only /cmd or /cmd@your_bot |
| a file for data on a free web host | tanker.json lost on spin-down |
ephemeral filesystem | a database or a paid persistent disk |
Mini project
Add a /milk command that tells residents when the milk delivery comes, and /setmilk HH:MM for the secretary.
- Ask the AI for it with the exact rules (who may set it, the format, where it is stored).
- Add both commands to
BOT_COMMANDSso they appear in the/menu. - Test with the stand-in: a resident, the secretary, a bad time like
25:00, and/milk@milkman_botin a group. - Check
git log -p | grep -c <your token>prints0.
Solution sketch
if command == "/milk":
t = load_time("milk")
return "The milk delivery time hasn't been set yet." if t is None else f"Milk comes at {t}."
if command == "/setmilk":
if user_id not in secretary_ids():
return "Sorry, only the society secretary can change the milk time."
m = TIME_RE.match(arg)
if not m:
return "Usage: /setmilk HH:MM (24-hour), e.g. /setmilk 06:15"
value = f"{int(m.group(1)):02d}:{m.group(2)}"
save_time("milk", value)
return f"Done. Milk now comes at {value}."
Store both times in one JSON file ({"tanker_time": "07:30", "milk_time": "06:15"}) and add {"command": "milk", ...}, {"command": "setmilk", ...} to BOT_COMMANDS.
Practice questions
- Why is the token part of every request's URL a problem for logging?
Answer
Printing or logging the request URL prints the token too. Log the method name, or replace the token with a label before printing.
- What does
offsetdo ingetUpdates, and what happens without it?
Answer
Calling getUpdates with an offset higher than an update's update_id confirms that update, so Telegram stops sending it. Without it you get the same updates again and again (4 replies in 7 seconds in our test).
- What's the difference between polling and long polling?
Answer
Polling asks repeatedly and usually gets "nothing new". Long polling (timeout=30) sends one request that waits up to 30 seconds and returns as soon as an update arrives.
- Your bot uses a webhook. A request arrives without the
X-Telegram-Bot-Api-Secret-Tokenheader. What should the bot do?
Answer
Reject it (the AI's code answers 403). Telegram sends the header with every webhook request when a secret_token was set, so a request without it didn't come from Telegram.
- Why might
/help@milkman_botreach your bot at all?
Answer
Bots that are group admins don't run in privacy mode and receive all messages. So your bot must check the @name itself.
- Why must a polling bot run all the time, while a webhook bot only needs to wake up for requests?
Answer
A polling bot must keep asking Telegram; if it stops, nobody collects the updates. With a webhook, Telegram makes the request, so a web service can sleep and wake when a request arrives.
- You put
.envin.gitignoreafter you already committed it. Is the token safe?
Answer
No. .gitignore doesn't remove files already in Git, and the history keeps old versions. Get a new token with /token, then remove the file from Git (git rm --cached .env).
Quiz
You pushed bot.py with the real token inside to GitHub. What's the first step?
A) Delete the GitHub repository · B) Make the repository private · C) Send /token to BotFather to get a new token · D) Add bot.py to .gitignore
Answer
C. Someone may already have copied the token, and Git history keeps it even if you delete the line. Only a new token makes the old one useless. Then move it into an environment variable.
Interview questions
- Compare long polling and webhooks for a chat bot. When would you pick each?
- How do you keep API keys and bot tokens out of source code, logs and CI output?
- How would you verify that an incoming webhook request really came from the provider?
- Webhook providers retry deliveries. How do you make your handler safe to call twice with the same event (idempotent)?
- What changes when you move a bot from a laptop to a free cloud host (sleeping, ephemeral disks, environment variables)?
- An AI agent wrote code that passes all its own tests. How do you find the bugs the tests didn't think of?
Glossary
| Term | Meaning (plain words) | Example |
|---|---|---|
| Bot | a program with its own chat account that people message like a person | @greenpark_society_bot |
| Telegram Bot API | Telegram's HTTPS interface that programs use to run bots | https://api.telegram.org/bot<token>/sendMessage |
| API | a way for one program to ask another program for things | the Bot API, the weather API (episode 13) |
| BotFather | Telegram's bot for creating and managing bots | /newbot, /token |
| Bot token | the secret key that lets a program act as your bot | 123456:ABC-DEF1234ghIkl-... (docs' example) |
| Secret | a value that gives access and must not be shared | a token, a password, a webhook secret |
| Leak | a secret ending up where others can read it | a token in GitHub, a log, a prompt |
/token |
BotFather's command to generate a new token; the old one stops working | after a leak |
| Environment variable | a setting given to a program from outside when it starts | TELEGRAM_BOT_TOKEN |
os.environ |
Python's dictionary of environment variables | os.environ.get("PORT") |
KeyError |
Python's error when a dictionary has no such key | KeyError: 'TELEGRAM_BOT_TOKEN' |
.env file |
a text file of NAME=value lines for your laptop; must be loaded by something |
set -a; . ./.env; set +a |
.gitignore |
a list of files Git must not commit | .env, tanker.json |
git check-ignore -v |
shows which .gitignore line ignores a file |
.gitignore:4:.env |
| Update | one new event for the bot, usually a new message | {"update_id": 1, "message": {...}} |
update_id |
an update's unique number | 1, 2, 3 |
| Polling | asking again and again "anything new?" | checking the letterbox every 2 minutes |
| Long polling | one request that waits for news, up to a timeout | getUpdates(timeout=30) |
getUpdates |
the Bot API method for (long) polling | getUpdates?offset=2&timeout=30 |
| Offset | tells Telegram which updates you've already got (confirms them) | offset = update_id + 1 |
| Timeout | how long a request may wait | 30 seconds |
| Webhook | an address of yours that the service calls when something happens | https://.../hook |
setWebhook / deleteWebhook |
register / remove the webhook address | setWebhook(url, secret_token) |
| HTTPS | HTTP with encryption; Telegram only calls HTTPS webhooks | port 443 |
| Header | a labelled line of extra information sent with an HTTP request | X-Telegram-Bot-Api-Secret-Token: ... |
| Secret token (webhook) | a value Telegram sends in a header to prove the request is from Telegram | WEBHOOK_SECRET |
hmac.compare_digest |
compares two strings in constant time (no timing hints) | checking the secret header |
| 401 / 403 / 404 / 409 | not authenticated / forbidden / not found / conflict | 403 for a bad secret |
| Command | a message starting with / that tells the bot what to do |
/tanker |
bot_command entity |
Telegram's marker in a message for where a command is | {"type": "bot_command", "offset": 0, "length": 17} |
/start, /help |
global commands every bot should support | the first message to a bot |
setMyCommands |
registers the bot's commands for the / menu |
{"command": "tanker", "description": ...} |
sendMessage |
the Bot API method to send a text message | chat_id + text (1-4096 characters) |
chat_id |
which conversation to send to (negative for groups here) | 2002, -500 |
getMe |
returns the bot's own account, including its username | greenpark_society_bot |
| Group chat | a chat with many people (and maybe several bots) | Green Park Residents |
| Privacy mode | bots in groups see only relevant messages, unless they are admins | on by default |
| Admin (group) | a member with extra rights; an admin bot sees all messages | our bot |
| Stand-in (fake, mock) | a stand-in server that imitates a real service for testing | fake_telegram.py |
| Unit test | a small automatic check of one piece of code | test_bot.py (20 tests) |
| Session log | the agent's record of a session, saved on disk | ~/.claude/projects/.../*.jsonl |
| Deploy | run your program on an always-on server | a host such as Render |
| Host | a company that runs your program on its servers | Render |
| Web service | a program that answers web requests | the webhook bot |
| Background worker | a program that runs all the time without web requests | a polling bot |
| Spin down | a free service is stopped when idle and started on the next request | after 15 minutes (Render free) |
| Ephemeral filesystem | files that are lost on restart or redeploy | tanker.json on a free web service |
| Persistent disk | storage that survives restarts (paid on Render) | where tanker.json could live |
Summary
- A bot is a program with a Telegram account; it talks to Telegram through the Bot API, with its token in every request URL.
- The token is a master key: keep it in an environment variable (
.env+.gitignoreon your laptop, the host's settings in production), never in code, logs or prompts. Leaked?/token. - Polling must confirm updates with
offset; long polling (timeout) waits for news. A webhook makes Telegram call you; check the secret header. Use one way at a time. - Commands are
/keywords; reply withsendMessage(chat_id, text); register a/menu withsetMyCommands; in groups answer only your own@name. - Deploying: a polling bot needs an always-on worker; a webhook bot is a web service. Read the host's docs: free plans can sleep and wipe files.
- The AI did a lot right (no hard-coded token, secret header, retries, authorization). We still found a real bug by testing a case its tests didn't think of, and a mistake of our own in the prompt.
The stand-in we used: fake_telegram.py (run it to test your own bot without a real token)
"""A tiny local stand-in for the Telegram Bot API (only the methods our bot uses), for testing without a real token.
Request/response shapes follow core.telegram.org/bots/api. Test-only extras: POST /_say {"chat_id","name","text"}
queues a user message; GET /_sent lists what the bot sent. Run: TOKEN=123456:ABC-PLACEHOLDER python3 fake_telegram.py 8081"""
import json, os, sys, threading, time, urllib.request
from http.server import ThreadingHTTPServer, BaseHTTPRequestHandler
TOKEN = os.environ.get("TOKEN", "123456:ABC-PLACEHOLDER")
updates, sent, lock, cv = [], [], threading.Lock(), threading.Condition()
state = {"next_update": 1, "next_msg": 1, "webhook": "", "secret": "", "commands": []}
def log(*a): print(time.strftime("%H:%M:%S"), *a, flush=True)
def push_webhook(upd):
req = urllib.request.Request(state["webhook"], data=json.dumps(upd).encode(), headers={"Content-Type": "application/json"})
if state["secret"]: req.add_header("X-Telegram-Bot-Api-Secret-Token", state["secret"])
try:
with urllib.request.urlopen(req, timeout=5) as r: log("webhook POST ->", r.status)
except Exception as e: log("webhook POST failed:", e)
class H(BaseHTTPRequestHandler):
def log_message(self, *a): pass
def reply(self, code, obj):
b = json.dumps(obj).encode(); self.send_response(code); self.send_header("Content-Type", "application/json")
self.send_header("Content-Length", str(len(b))); self.end_headers(); self.wfile.write(b)
def params(self):
from urllib.parse import urlparse, parse_qs
p = {k: v[0] for k, v in parse_qs(urlparse(self.path).query).items()}
n = int(self.headers.get("Content-Length") or 0)
if n:
raw = self.rfile.read(n).decode(); ct = self.headers.get("Content-Type", "")
if "json" in ct: p.update(json.loads(raw or "{}"))
else: p.update({k: v[0] for k, v in parse_qs(raw).items()})
return p
def do_GET(self): self.handle_any()
def do_POST(self): self.handle_any()
def handle_any(self):
path = self.path.split("?")[0]; p = self.params()
if path == "/_say":
with cv:
u = {"update_id": state["next_update"], "message": {"message_id": state["next_msg"], "date": int(time.time()),
"from": {"id": int(p.get("from_id", p["chat_id"])), "is_bot": False, "first_name": p.get("name", "User")},
"chat": ({"id": int(p["chat_id"]), "type": "group", "title": p.get("group", "Green Park Residents")} if int(p["chat_id"]) < 0 else {"id": int(p["chat_id"]), "type": "private", "first_name": p.get("name", "User")}), "text": p["text"]}}
if p["text"].startswith("/"):
u["message"]["entities"] = [{"offset": 0, "length": len(p["text"].split()[0]), "type": "bot_command"}]
state["next_update"] += 1; state["next_msg"] += 1
if state["webhook"]: threading.Thread(target=push_webhook, args=(u,)).start()
else: updates.append(u); cv.notify_all()
log("user", p.get("name"), "says", repr(p["text"])); return self.reply(200, {"ok": True})
if path == "/_sent": return self.reply(200, sent)
if not path.startswith("/bot"): return self.reply(404, {"ok": False, "error_code": 404, "description": "Not Found"})
tok, _, method = path[4:].partition("/")
if tok != TOKEN:
log("rejected request with a wrong token"); return self.reply(401, {"ok": False, "error_code": 401, "description": "Unauthorized"})
log("bot called", method, {k: v for k, v in p.items() if k != "text"} if method != "sendMessage" else "")
if method == "getMe": return self.reply(200, {"ok": True, "result": {"id": 999, "is_bot": True, "first_name": "Green Park Society", "username": "greenpark_society_bot"}})
if method == "getUpdates":
if state["webhook"]:
return self.reply(409, {"ok": False, "error_code": 409, "description": "Conflict: getUpdates is not allowed while a webhook is set (stand-in)"})
off = int(p.get("offset", 0)); timeout = float(p.get("timeout", 0)); lim = int(p.get("limit", 100))
with cv:
if off: updates[:] = [u for u in updates if u["update_id"] >= off] # confirmed
end = time.time() + timeout
while not [u for u in updates if u["update_id"] >= off] and time.time() < end: cv.wait(end - time.time())
res = [u for u in updates if u["update_id"] >= off][:lim]
return self.reply(200, {"ok": True, "result": res})
if method == "sendMessage":
if not p.get("text"): return self.reply(400, {"ok": False, "error_code": 400, "description": "Bad Request: message text is empty"})
m = {"message_id": state["next_msg"], "chat": {"id": int(p["chat_id"])}, "text": p["text"], "date": int(time.time())}
state["next_msg"] += 1; sent.append(m); log("bot -> chat", p["chat_id"], repr(p["text"][:70]))
return self.reply(200, {"ok": True, "result": m})
if method == "setMyCommands":
c = p.get("commands"); state["commands"] = json.loads(c) if isinstance(c, str) else c
return self.reply(200, {"ok": True, "result": True})
if method == "setWebhook":
state["webhook"] = p.get("url", ""); state["secret"] = p.get("secret_token", ""); return self.reply(200, {"ok": True, "result": True, "description": "Webhook was set"})
if method == "deleteWebhook":
state["webhook"] = ""; return self.reply(200, {"ok": True, "result": True, "description": "Webhook was deleted"})
if method == "getWebhookInfo": return self.reply(200, {"ok": True, "result": {"url": state["webhook"], "pending_update_count": len(updates)}})
return self.reply(404, {"ok": False, "error_code": 404, "description": "Not Found: method not in this stand-in"})
port = int(sys.argv[1]) if len(sys.argv) > 1 else 8081
log(f"stand-in Bot API on http://localhost:{port}"); ThreadingHTTPServer(("127.0.0.1", port), H).serve_forever()
Next episode: Project: Chrome extension: manifest.json, a popup, content scripts, permissions and why fewer is safer, loading an unpacked extension, debugging with DevTools.