MODULE 4.1 / 7 OF 8
Telegram as work interface
Run a restricted query bot and understand where AI comes in.
1Telegram is the interface, not the agent
What it is
A bot receives messages via the Telegram API and returns responses. Intelligence can come from rules, a program, or a model call. The mobile app does not execute its tasks on the server by itself: there is an intermediate program with defined permissions.
Why learn
Separating interface and execution avoids calling any automatic response an intelligent agent. First build a reliable path to receive and reply; then connect the needed capability.
Key concepts
Message; Bot API; program; agent; result.
In practice
/status queries the bot's state without AI. /relatorio calculates fictitious sales without AI. A natural language summary could be added later, preserving the calculated numbers.
✓ Do it
Draw: phone → Telegram → bot → permitted function → response. Mark at which stage a future AI call would actually be useful.
✗ Avoid
Accepting a conclusion without checking the input that supports it.
2Create the bot and protect the token
What it is
In Telegram, find the official BotFather and use /newbot. Choose a name and identifier as shown in the instructions. The generated token authenticates your program with Telegram. Store it as TELEGRAM_BOT_TOKEN in a private file; the kit only contains example values.
Why learn
Anyone who controls the token can operate the bot. Screenshots of the process and URLs containing the token can leak access. If exposed, revoke the token in BotFather before continuing.
Key concepts
BotFather; token; environment variable; rotation.
In practice
The teacher creates a bot for personal use. She does not put the token in the README and does not send the credentials file to the students. Each installation uses its own credentials.
3Authorize people and actions
What it is
The kit bot only accepts private chats and configured IDs. It also accepts only known commands. Verifying the ID is different from checking the visible name: names can change. A message from an unknown user should not trigger file reads or system commands.
Why learn
A bot found on the internet may receive unexpected messages. Program authentication with a token does not mean authorization for anyone who talks to it. These are separate controls.
Key concepts
Numeric ID; access list; private chat; fixed commands.
In practice
The owner writes /relatorio and receives fictitious totals. A user outside the list does not receive data. Even the owner cannot write a shell command and expect the bot to execute it.
Sequence to try
- Prepare a training copy.
- Read the handle_message function from the kit. Locate the ID check and private chat verification before dispatching commands.
- Record the observed result and the next correction.
4Start with long polling
What it is
Long polling is the program asking Telegram for messages and waiting a bit when there are no new ones. It is simple to learn and does not require opening a public inbound port. Webhook is another strategy, where Telegram calls your HTTPS address; it is not needed in this lab.
Why learn
Choosing a single mode reduces configuration problems. Keep only one instance fetching messages for a bot: duplicate processes can compete for updates.
Key concepts
getUpdates; offset; timeout; single instance; outbound access.
In practice
The process waits up to 25 seconds for a message. Upon receiving it, it updates the offset to avoid repeating the same query. After a network failure, it waits before trying again.
✓ Do it
Start with python3 bot.py. Use Ctrl+C to terminate. If a conflict arises, check whether another process is using the same token or if a webhook is configured.
✗ Avoid
Mix the training copy with private files or production work.
5Connect capabilities in stages
What it is
The kit deliberately separates transport and work functions. It starts deterministic: status and report of fake data. To attach AI, define a function with limited input, timeout, output ceiling, and review. Do not expose codex exec directly to public messages nor disable protections to make it work.
Why learn
A predictable program allows testing the base without spending API. Then you assess whether AI improves interpretation, summarization, or classification and measure the result against a known reference.
Key concepts
Domain function; limits; timeout; review; minimal data.
In practice
A summary function can receive only the total and three categories, instead of the entire projects directory. The generated text never alters the total calculated by the program.
6Test operation and failures
What it is
Test allowed sender, blocked, group, unknown command, and missing data. Logs should report the type of failure and timestamp, without the token or full private messages. In the lab, stopping the process should halt responses: this proves the local program is on the path.
Why learn
A correct response does not prove the bot is restricted nor that it retrieves the network. A small set of scenarios demonstrates the important properties before migrating to a VPS.
Key concepts
Self‑test; network failure; logs without secrets; interruption; diagnosis.
In practice
If /status works and /relatorio fails, investigate the data file. If neither works, check the process, authentication, and connection. Do not change the model: these commands do not even use AI.
Criteria to review your delivery
Use this rubric after the lab. Each line asks for evidence; checking reading does not mean the practice was performed.
| Criterion | Expected evidence | If not passed |
|---|---|---|
| Scope | The delivery matches the objective of this class. | Reduce the task and name a single result. |
| Inputs | You know which files or data were used. | List the sources and remove unrelated material. |
| Execution | The procedure was carried out in the training environment. | Differentiate what was planned from what was done. |
| Verification | A result was compared with a reference. | Open the file or repeat the verifiable query. |
| Secrets | No token, password, or private data was shared. | Review the work copy before any submission. |
| Continuity | Another person can find the next step. | Update README and record a concrete pending item. |
GET HANDS-ON / ~15 MIN OR IN STEPS
A bot that responds without executing messages
Use fictional files and a training folder. Practices involving installation, Telegram or VPS may require additional time for registration and configuration.
Bot · inside materiais/bot
Read the block before using. Fields like Your Name and usuario@ip-da-vps are examples to adapt; administrative commands belong only to your training environment.
python3 bot.py --self-test cp .env.example .env chmod 600 .env # Edit .env locally; never share its values. python3 bot.py --identify # Fill ALLOWED_USER_IDS with your ID and stop identification mode. python3 bot.py
Ready criterion
Run a restricted query bot and understand where the AI comes in. Log the generated file, the test executed, and the observed result.
Open lab files and modelsCheck what remained
Can a Telegram message be passed directly to the shell?
View commented answer
No. The bot must map allowed commands to defined functions and verify the sender.
If your answer was different, return to the corresponding topic and write the difference in one sentence. The check does not block your study.
Module summary
- Message; Bot API; program; agent; result.
- BotFather; token; environment variable; rotation.
- Numeric ID; access list; private chat; fixed commands.
- getUpdates; offset; timeout; single instance; outbound access.
- Domain function; limits; timeout; review; minimal data.
- Self‑test; network failure; logs without secrets; interruption; diagnosis.
Consult the source
Tools verified on 20/09/2026; screen names and availability may change.