You have a client (or a community) that keeps answering the same five questions in Telegram, and they want a bot to take over. If you skip the setup steps around the bot token and the group settings, the thing either leaks its credentials or quietly ignores half the questions posted in the group. Do it once, properly, and you have a small product you can build in an afternoon and resell to every client after this one.
Here's the whole job in one paragraph: create the bot with @BotFather and keep the token in an environment variable, never in the code. Have the client keep FAQ answers in a plain text file they can edit themselves. Give your coding agent a written spec that covers question matching, a fallback reply for anything it doesn't recognize, and a "talk to a human" handoff. Run it with polling instead of a webhook, test it from a second Telegram account, and check the group privacy settings before the client adds it anywhere public.
What you're building, and what to ask for first
The scope is deliberately small: a bot that answers frequently asked questions in a private chat and optionally inside the client's group. No database, no admin panel, no AI. A file of question-and-answer pairs, a program that reads incoming messages and replies, and a way out when the bot doesn't know the answer.
Before you touch any code, get three things from the client: the actual questions with their approved answers, the name of the person who handles the human handoff (their Telegram @username), and where the bot will run. If the handoff person is on vacation and nobody else can answer, the bot should say so instead of going silent. Agree on that in writing.
Create the bot with @BotFather
Every bot starts with @BotFather. Send it the /newbot command and follow the steps until it hands you a token, which authenticates your bot on the Bot API (bot tutorial). Telegram's own tutorial says to save the token somewhere secure, treat it like a password, and never share it. Two details worth knowing: a leaked token can be revoked and replaced through @BotFather, and the tutorial suggests keeping the token in environment variables or a settings file rather than in the code (bot tutorial).
Next, register the commands so Telegram shows users a menu. In @BotFather use Edit Commands under /mybots (the /setcommands route) and send each command with a short description, for example /faq, /human, /start (bot tutorial). Commands must start with a slash, can be up to 32 characters long, and lowercase is recommended (commands docs). Three commands is plenty for v1.
Polling or webhook: start with polling
The Bot API gives you exactly two mutually exclusive ways to receive messages: the getUpdates method (polling) or a webhook (getUpdates docs). Polling means your program asks Telegram "anything new?" on a loop; the API calls this long polling. A webhook means Telegram pushes each message to a URL you own, which sounds nicer until you read the requirements: a public HTTPS endpoint, TLS 1.2 or newer (plain HTTP is not possible), a verified or self-signed certificate, and one of four supported ports: 443, 80, 88, or 8443 (webhook guide).
You also can't run both at once: it's not possible to get updates via long polling while a webhook is set (bot FAQ). For a small FAQ bot, polling is the right call, and Telegram's own webhook guide says there is nothing wrong with using getUpdates if it works (webhook guide). One caution the docs give: uncollected updates are stored on Telegram's servers but kept no longer than 24 hours, so don't let the bot sit offline for days and expect a backlog (getUpdates docs).
The spec prompt for your coding agent
Telegram's own docs are written to be handed to an AI tool: the features page tells developers with limited coding experience to direct their AI tool at the documentation (features page). Don't just say "make me a Telegram bot". Paste a spec. If you don't have a coding agent set up yet, you can try the zcode agent harness free.
Here's the spec to paste:
Build a small Telegram FAQ bot in Python. Requirements:
- Read the bot token from the BOT_TOKEN environment variable. Never
hardcode it. If it is missing, exit with a clear error message.
- Receive updates with long polling (getUpdates). Do NOT use a webhook.
- Load questions and answers from faq.md, a plain file of pairs, one
question per line, answer on the next line, sections separated by
"##" headings. Match an incoming message against exact question text
first, then against keywords from the question.
- Every message that matches nothing gets a fallback reply: say you
didn't understand, list the available commands, and tell the user
they can type "human" to reach a person.
- The "human" keyword (and a /human command) replies with the handoff
contact from the HANDLER_USERNAME environment variable, plus the
user's own question back so they can copy it into a direct message.
- /start sends a short greeting and the command list. /help does the same.
- Append every unmatched question to unanswered.log with a timestamp,
so the client can see what to add to faq.md.
- Include a README explaining how to run the bot and how to edit faq.md.
Reference docs: https://core.telegram.org/bots/api and
https://core.telegram.org/bots/tutorial
When the agent finishes, check two things by hand: the token appears nowhere in the source, and faq.md is a file the client can open and edit without your help.
The FAQ file, the fallback, and the handoff
The FAQ file is the product. Keep it as plain text the client edits themselves, because every change that needs you is an invoice they didn't plan for. Start with the questions the client actually receives, not the ones you imagine. The unanswered.log file from the spec is your roadmap: after a week, the most common unmatched questions become the next entries.
The fallback reply is not optional. A bot that stays silent on an unknown question looks broken; a bot that says "I didn't catch that, type human for a person" looks intentional. For the handoff, have the bot repeat the user's own question back to them along with the handler's @username. One Telegram rule matters here: your bot can only message a user after that user has contacted the bot first, and a message can be 1 to 4096 characters long (bot tutorial), which is more than enough for any FAQ answer.
Test it, then deploy it
Test with a second Telegram account, not your main one, because a fresh account knows nothing about your bot and will click around the way a real user does. Run through /start, a question the FAQ answers, a nonsense question for the fallback, and the human handoff. Then add the bot to a private test group and post there.
Groups behave differently, and this is where most one-afternoon bots fail. By default, bots run in privacy mode in groups (bots added as admins are the exception), which limits what they receive: a privacy-enabled bot in a group sees commands meant for it (like /faq@yourbot), general commands from a user if the bot was the last one to send a message there, messages sent via the bot, and replies to its own messages. A bot that is a group admin, or one with privacy mode turned off, receives all messages except those from other bots, and bots never see other bots' messages at all (bot FAQ). Check the privacy setting for your bot in @BotFather's settings and make sure the client knows which mode it runs in.
For hosting, polling means no domain and no certificate, so any cheap VPS or an always-on machine the client already owns will do. Put the token in an environment variable on the server, keep it out of the git repository, and remember you can revoke and replace it through @BotFather if it ever leaks (bot tutorial). If you're picking a plan for the coding agent you'll build bots like this with, there's 10% off GLM coding plans.
Ship checklist
- Bot created via /newbot; token saved in an environment variable only
- Commands registered: /start, /faq, /human
- faq.md readable and editable by the client; unanswered.log writing
- Fallback reply fires on every unknown message; handoff tested
- Tested end to end from a second Telegram account
- Group privacy mode checked and explained to the client
- Token absent from the repo; revocation path known
There's more on our blog on building small client tools with a coding agent.
If this saved you an afternoon, a small tip on the post keeps these guides coming.
Latest comments
0