Coder Legion - Recent posts tagged telegram-bot

How I Built a Telegram Habit-Tracker Bot with No Programming Experience

Mon, 21 Sep 2026 12:26:13 +0000

Hi everyone!

This is my first post here. I am writing not for experienced developers, but for those who want to gain their first programming experience using AI models.

Here is how it went for me.

Recently, I had no idea about programming and had never built Telegram bots. Three months ago, as an experiment, I started "vibe coding," and now I have a working Telegram bot with several thousand lines of code, modules for selecting and saving time, passwords, a database, payment processing, 10 languages, and chart generation. You can launch the bot at https://telegram.me/I_promise_myself_bot (click the "Try free & Unlock" button).

I want to share my experience—how I used several different LLMs in a regular free chat, how I bypassed limits, and how I got out of dead ends when the AIs completely stalled, forgot context, and the bot started breaking.

Where It All Started

Like everyone else, I started with ChatGPT, then tried Grok, Mistral, Gemini, Qwen, and DeepSeek bit by bit. I wanted to figure out through trial and error what each could do and for how long. I quickly ran into token limits in free chats. Also, over long distances, they lose context at different times, start mixing up file structures, and produce non-working pieces of code.

As long as there were 200-300 lines of code, working with AIs was manageable, but when the code exceeded 1,000 lines, the problems began. To overcome bottlenecks, I couldn't paste or upload such an amount of code into the window for the AI to see the whole code, find the exact error, or add a new feature.

Another problem was that any AI, as a rule, forgets the conversation after a few hours or starts hallucinating heavily. After that, you have to kill the chat and create a new one, re-supplying the new chat with the general task, snippets of chat history and code, and almost the entire conversation so it understands what I want from it. I regularly read bloggers, and regarding this, I asked Kostya Doronin for advice on how to work with AIs when code accumulates to more than 1,000 lines across multiple files. Surprisingly, he readily suggested several free and paid workarounds, but I managed with free ones only. I fundamentally wanted to figure out if it's possible to make something working with AIs for free.

I had to change my approach a bit. First, I roughly figured out what can be squeezed out of this or that AI, when they start glitching, and how to bypass it. I stopped loading one AI with all tasks at once and started dividing tasks among models.

I settled on these:

1.Claude is the architect. It has the best logic and understanding of the general code and project structure. I used it for brainstorming and design, modularizing, and creating step-by-step instructions for other AIs. Also as a "rescuer" in dead-end situations when another AI started leading me in circles. The only downside is that free tokens run out very quickly, and you have to wait a few hours.
2.Qwen turned out to be the main "workhorse" over long distances. If you give it a detailed plan from Claude, Qwen handles it well and sticks to the plan. Claude has strict limits on free messages, but with Qwen, you could code all day long in the same chat, solving tasks one step at a time. It holds up for about 7 days before hallucinations begin, after which you need to kill the chat and start a new one.
3.Gemini is an additional tool for quickly double-checking individual pieces of code, like a "fresh perspective" on a problem or a new task. But in the free version, it is not particularly good at programming and architecture, and if you work with it for a whole day or two, it also starts hallucinating. Although there were periods when these same models worked for weeks without any hallucinations at all. And sometimes a day was enough for both Qwen and Gemini to start glitching, which I never encountered with Claude. Probably because it ran out quickly! From which I concluded that model owners for some reason release different quality versions of the same model into the wild.

In other words, all these LLMs are a very unreliable thing, and for serious projects, you should only work with people. But as assistants in simple coding tasks, they are very good.

Project Architecture

At the beginning of creating the bot, Claude guided me step-by-step to download and set up all these tools on my computer:

•Language and framework: Python 3.11+, aiogram 3.x.
•Database: Started with simple Google Sheets, but eventually switched to PostgreSQL, hosted on Supabase. Mistake: should have used PostgreSQL from the very beginning.
•Background tasks: APScheduler for push notifications.
•Graphics: matplotlib for reports.
•Payments: Paddle SDK integration.
•Localization: Multilingual system based on JSON (languages). Mistake: did it at the very end, but should have done it at the very beginning because I had to redo a lot of things.
•Security: Isolating tokens in a separate file.

Development Process

For each new bot feature, I tasked Claude with developing as detailed a step-by-step instruction plan for Qwen as possible. I coded in VS Code, but didn't use LLMs inside it directly, only in chats:

1.I initially split the entire project into logical modules: there is one main file up to 2,000 lines, and the rest are 200-700 lines. Everything is separate – handlers, database operations, notifications, buttons, and localization.
2.Working with Qwen: Before any changes, I saved all recent files with working code in a separate folder so I could easily roll back. I gave Qwen a step-by-step plan and changed or added functionality step by step. I inserted it into the project, ran the bot, and checked the operation and logs. If there was a problem, I gave the logs to all three AIs at once to find the issue. If the problem hit a dead end, I started over from the last working code, but mentioned in the task to Claude (if tokens remained) that there were such-and-such problems during the previous change and they needed to be avoided. If Claude was exhausted, I asked Gemini. And so I moved step by step.

How I Got Out of Dead Ends

Somewhere in the middle of the project, the code exceeded a thousand lines, and problems began: the AI forgot the context and broke what was already working when trying to fix a bug.

At that moment, I brought in Claude:

1.I described the essence of the technical problem and the bot's startup logs in VS Code.
2.I provided snippets of chat history where Qwen started going in circles.
3.I attached the problematic code.

Mostly, Claude found the error on the first try and provided a solution. If it didn't know, it asked leading questions and we ran additional checks. Unlike Qwen or Gemini, which immediately "poured out" a bunch of possible causes after which going in infinite circles began. In especially neglected cases, I "pitted models against each other": I drove the problematic piece in circles between Claude, Gemini, and Qwen until one of them found the bug. Their collective intelligence works much more reliably.

Conclusions

After a few months of casual work, I got a working Telegram bot with several thousand lines of code, written from scratch with no experience.

What I realized for myself:

1.On simple tasks, AI replaces a team, but you need to understand the project structure well yourself and at least superficially understand the code. If you have no knowledge, you can learn to think systemically and architecturally on such projects.
2.Use different models. Using a single AI for everything is undesirable. The "architect + coder + fresh perspective" bundle works better.
3.Small steps. Wrote a function – tested it. Broke – rolled back to the last working version.
4.Save chat history. Chat history with AI helps you not to lose the logic of the project yourself after a week or month of work, and to provide context to another AI for problem analysis.

I will be glad to answer questions in the comments!

SmartAlert-T (SAT)

Fri, 19 Jun 2026 18:35:30 +0000

SmartAlert-T (SAT) — Node.js

The first line of defense for your servers and applications.
Send beautiful, structured Telegram alerts — critical, warning, info — straight from your Node.js code, cron jobs and background workers.

Built by Gift Balogun. This is the Node.js twin of the PHP/Laravel SmartAlert-T package — identical message styling and footer across both runtimes.

✨ Features

🚨 Three alert levels — Critical, Warning, Info — each with distinct emoji + styling.
💬 Send to individual users, groups, supergroups and channels.
🟦 TypeScript-first — ships with full type definitions.
⏱️ Cron & background-process friendly — optional non-throwing mode so alerting never crashes your jobs.
🏷️ Rich context metadata block + automatic timestamp.
🔒 HTML-safe message escaping.
🪶 Zero runtime dependencies — built on the Node.js core https module.
🖋️ Branded footer with copyright to Gift Balogun on every message.

📦 Installation

npm install smart-alert-t
# or
yarn add smart-alert-t

Requires Node.js >= 14.

🤖 Getting your Telegram credentials

Create a bot — open @BotFather, send /newbot, and copy the bot token (e.g. 123456789:AAH...).
Find your chat id:
- Personal chat: message @userinfobot for your numeric id.
- Group: add the bot to the group, then open https://api.telegram.org/bot<TOKEN>/getUpdates and read chat.id (group ids are usually negative).
- Channel: use @your_channel_username and make the bot an admin.

🚀 Quick start

CommonJS

const { SmartAlert } = require('smart-alert-t');

const alert = SmartAlert.make({
  token: 'YOUR_BOT_TOKEN',
  chatId: 'YOUR_CHAT_ID',   // user, group, or @channel
  appName: 'Payments API',  // optional label on every alert
});

await alert.critical('Database down', 'Primary DB is unreachable.', { host: 'db-01' });
await alert.warning('High memory',   'Worker memory at 86%.',       { service: 'queue' });
await alert.info('Deploy complete',  'v2.4.1 shipped to prod.',     { version: '2.4.1' });

ES Modules / TypeScript

import { SmartAlert } from 'smart-alert-t';

const alert = new SmartAlert({
  token: process.env.SMART_ALERT_TOKEN!,
  chatId: process.env.SMART_ALERT_CHAT_ID!,
  appName: 'Billing Service',
});

await alert.info('Job done', 'Nightly export completed.', { rows: 48211 });

🎨 The three alert types

Method	Emoji	Use it for
`critical()`	🚨	Outages, data loss, anything paging-worthy
`warning()`	⚠️	Degraded state that needs attention soon
`info()`	ℹ️	Deploys, job completions, routine heads-up

Every method shares the same signature and returns a Promise:

alert.critical(
  title: string,                       // short headline
  message: string,                     // body text
  context?: Record<string, unknown>,   // optional metadata block
  chatId?: string | number | null,     // optional per-call destination override
): Promise<SmartAlertResult>;

A rendered alert looks like:

🚨 [CRITICAL] Database down
App: Payments API

Primary DB is unreachable.

• host: db-01
• region: eu-west-1

🕒 2026-06-03 10:42:11 UTC
Powered by SmartAlert-T © 2026 — Gift Balogun

👥 Sending to users vs. groups vs. channels

The destination is just the chatId:

// Individual user
await alert.info('Hi', 'Personal message.', {}, 123456789);

// Group / supergroup (ids are typically negative)
await alert.warning('Heads up', 'Group message.', {}, -1001234567890);

// Public channel
await alert.critical('Outage', 'Channel broadcast.', {}, '@my_status_channel');

Set a default chatId in the constructor and override it per call only when needed.

⏰ Using it in cron jobs & background processes

Set throwOnError: false so a transient Telegram hiccup can never crash your scheduled task — the promise resolves to { ok: false, error } instead of rejecting.

const os = require('os');
const { SmartAlert } = require('smart-alert-t');

const alert = SmartAlert.make({
  token: process.env.SMART_ALERT_TOKEN,
  chatId: process.env.SMART_ALERT_CHAT_ID,
  appName: `Server: ${os.hostname()}`,
  throwOnError: false,
});

const result = await alert.warning('Disk filling up', 'Root volume at 82%.', { used: '82%' });
if (!result.ok) {
  console.error('[SAT] delivery failed:', result.error);
}

Crontab example (every 5 minutes):

SMART_ALERT_TOKEN=123456789:AAH...
SMART_ALERT_CHAT_ID=-1001234567890
*/5 * * * * /usr/bin/node /var/www/app/examples/cron-health-check.js >> /var/log/sat.log 2>&1

node-cron example:

const cron = require('node-cron');
const { SmartAlert } = require('smart-alert-t');

const alert = SmartAlert.make({
  token: process.env.SMART_ALERT_TOKEN,
  chatId: process.env.SMART_ALERT_CHAT_ID,
  throwOnError: false,
});

cron.schedule('*/5 * * * *', async () => {
  // your health check...
  await alert.info('Heartbeat', 'Service is alive.');
});

See examples/basic-usage.js, examples/cron-health-check.js and examples/typescript-usage.ts for complete scripts.

⚙️ Configuration reference

Option	Type	Default	Description
`token`	`string`	—	Telegram bot token from @BotFather. Required.
`chatId`	`string \\| number \\| null`	`null`	Default destination (user/group/`@channel`).
`appName`	`string \\| null`	`null`	Optional label shown on every alert.
`timeout`	`number`	`10000`	Request timeout in milliseconds.
`throwOnError`	`boolean`	`true`	Reject on failure (`true`) or resolve an error payload.

🛡️ Error handling

Default mode rejects with a SmartAlertError:

const { SmartAlert, SmartAlertError } = require('smart-alert-t');

try {
  await alert.critical('X', 'Y');
} catch (err) {
  if (err instanceof SmartAlertError) {
    // log, retry, fall back to email, ...
  }
}

With throwOnError: false, every call resolves to { ok: false, error } on failure and the decoded Telegram response on success.

🧪 Testing & building

npm install
npm run build   # compile TypeScript -> dist/
npm test        # run the offline unit tests

The test suite covers alert-type validation, message formatting, HTML escaping and error handling — all without network calls.

📄 License

MIT © Gift Balogun

How to Build a Telegram Bot for Infrastructure Alerts

Tue, 02 Jun 2026 18:33:02 +0000

Your infrastructure will not always fail loudly.

Sometimes your database gets slow.
Sometimes your queue worker stops.
Sometimes your API starts returning errors.
Sometimes your server disk quietly moves from 70% to 95% usage while you are busy fixing “one small bug.”

The real problem is not that infrastructure breaks.

The real problem is finding out too late.

If users are the first people telling you your app is slow or unavailable, your monitoring setup is already behind. As developers, especially when building SaaS products, APIs, mobile apps, internal tools, or homelab powered systems, we need a faster way to know when something goes wrong.

That is where a Telegram bot for infrastructure alerts becomes useful.

The solution is simple: create a Telegram bot that sends instant alerts when your server, database, queue, API, or background jobs start misbehaving.

It does not need to be complicated. You do not need a huge observability stack on day one. You just need a reliable way to get notified before a small issue becomes a production incident.

Why Use Telegram for Infrastructure Alerts?

There are many ways to receive infrastructure alerts: email, Slack, Discord, SMS, dashboards, and full monitoring platforms.

But Telegram has a few advantages that make it very developer friendly:

It is fast.
It works well on mobile.
Bots are easy to create.
Messages can be sent through a simple API.
You can send alerts to yourself or a team group.
It is lightweight enough for small projects, SaaS apps, and homelabs.

For solo developers and small teams, Telegram is often enough to start with.

You do not always need a complex monitoring setup immediately. Sometimes, what you need first is this:

“Tell me when the database is down.”

“Tell me when the API is slow.”

“Tell me when disk space is almost full.”

“Tell me when a payment webhook fails.”

That alone can save you hours of debugging and embarrassment.

What We Are Building

In this guide, we are building a simple Telegram bot for infrastructure alerts.

The bot will send notifications for events like:

Server downtime
Database connection failure
Slow API response time
Queue worker issues
Failed background jobs
High disk usage
Failed backups
Unexpected application errors

The basic flow looks like this:

Your application or server detects a problem.

Then it sends a message to your Telegram bot.

The bot delivers the alert to your Telegram chat or group.

Simple.

But extremely useful.

When This Becomes Valuable as a Developer

If you are building a Laravel API, a Flutter mobile app, a SaaS dashboard, a Django backend, a NestJS API, or even running a homelab, infrastructure alerts quickly become important.

In development, you can refresh the page and inspect logs manually.

In production, that is not enough.

Users do not care that your queue worker stopped because Supervisor failed.

They do not care that your database is hosted somewhere with occasional network delay.

They do not care that your VPS disk got full because logs were growing too fast.

They only know the app feels broken.

A Telegram infrastructure alert system gives you a chance to respond before users start complaining.

That is the real value.

Step 1: Create a Telegram Bot

The first step is creating a bot inside Telegram.

Open Telegram and search for BotFather. BotFather is the official bot used to create and manage Telegram bots.

Create a new bot and give it:

A display name
A username ending in bot

After creating the bot, Telegram will give you a bot token.

That token is important.

Treat it like a password.

Do not commit it to GitHub.
Do not paste it inside frontend code.
Do not expose it in public logs.

Your bot token is what allows your application to send messages through your Telegram bot.

Step 2: Get Your Telegram Chat ID

After creating your bot, you need to know where the bot should send alerts.

That destination is called a chat_id.

The chat can be:

Your private Telegram account
A Telegram group
A Telegram channel

For most developers, starting with a private chat is fine.

Send a message to your bot first. Something simple like:

Hello bot

Then use the Telegram Bot API getUpdates method to inspect recent messages and find your chat_id.

Once you have the chat_id, save it. Your application will need it when sending alerts.

Step 3: Store Your Bot Credentials Safely

Never hardcode your Telegram bot token directly in your application.

Use environment variables instead.

For example:

TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_CHAT_ID=your_chat_id_here
TELEGRAM_API_BASE=your_telegram_bot_api_base_url

If you are using Laravel, you can add the values to your .env file and reference them through your config.

Inside config/services.php, you can add:

'telegram' => [
    'bot_token' => env('TELEGRAM_BOT_TOKEN'),
    'chat_id' => env('TELEGRAM_CHAT_ID'),
    'base_url' => env('TELEGRAM_API_BASE'),
],

This keeps your credentials clean, reusable, and easier to manage across development, staging, and production environments.

Step 4: Create a Telegram Alert Service in Laravel

If your backend is Laravel, one clean way to structure this is by creating a dedicated service class.

Something like:

<?php

namespace App\Services;

use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Log;

class TelegramAlertService
{
    public function send(string $title, string $message, string $level = 'warning'): void
    {
        $token = config('services.telegram.bot_token');
        $chatId = config('services.telegram.chat_id');
        $baseUrl = config('services.telegram.base_url');

        if (!$token || !$chatId || !$baseUrl) {
            Log::warning('Telegram alert skipped because credentials are missing.');
            return;
        }

        $text = strtoupper($level) . "\n\n" .
            $title . "\n\n" .
            $message . "\n\n" .
            'Time: ' . now()->toDateTimeString();

        $response = Http::timeout(10)->post(
            "{$baseUrl}/bot{$token}/sendMessage",
            [
                'chat_id' => $chatId,
                'text' => $text,
            ]
        );

        if ($response->failed()) {
            Log::warning('Failed to send Telegram infrastructure alert.', [
                'status' => $response->status(),
                'body' => $response->body(),
            ]);
        }
    }
}

This service gives you one reusable place to send infrastructure alerts.

Now, instead of scattering Telegram API calls across your codebase, you can simply inject or call this service wherever you need it.

Step 5: Send Your First Test Alert

Once your service is ready, send a test message.

For example, inside a route, command, job, or controller, you can do:

use App\Services\TelegramAlertService;

app(TelegramAlertService::class)->send(
    'Infrastructure Alert Test',
    'If you are seeing this message, your Telegram alert bot is working.',
    'info'
);

If everything is configured correctly, you should receive a Telegram message almost immediately.

That first message feels small, but it is an important milestone.

You now have a direct communication line between your infrastructure and your phone.

Step 6: Monitor Your Database Connection

A database failure is one of the most important things to monitor.

If your application depends on MySQL, PostgreSQL, or another database, you should know quickly when the connection fails or becomes too slow.

In Laravel, you can create a custom Artisan command for health checks:

php artisan make:command CheckInfrastructureHealth

Inside the command, you can test the database connection:

<?php

namespace App\Console\Commands;

use App\Services\TelegramAlertService;
use Illuminate\Console\Command;
use Illuminate\Support\Facades\DB;
use Throwable;

class CheckInfrastructureHealth extends Command
{
    protected $signature = 'infra:check-health';

    protected $description = 'Check infrastructure health and send alerts when something is wrong.';

    public function handle(TelegramAlertService $telegram): int
    {
        try {
            $start = microtime(true);

            DB::connection()->getPdo();

            $duration = round((microtime(true) - $start) * 1000, 2);

            if ($duration > 1000) {
                $telegram->send(
                    'Slow Database Response',
                    "Database connection succeeded, but response time is {$duration}ms.",
                    'warning'
                );
            }

            $this->info("Database check passed in {$duration}ms.");

            return self::SUCCESS;
        } catch (Throwable $e) {
            $telegram->send(
                'Database Connection Failed',
                $e->getMessage(),
                'critical'
            );

            return self::FAILURE;
        }
    }
}

This checks whether your database is reachable.

It also alerts you when the database responds too slowly.

That matters because sometimes the database is not fully down. Sometimes it is just slow enough to ruin the user experience.

And honestly, slow systems can be more frustrating than broken ones.

At least broken systems are obvious.

Slow systems make you question everything.

Step 7: Schedule the Infrastructure Check

After creating your health check command, schedule it to run automatically.

If you are using Laravel’s scheduler, you can run the command every minute or every few minutes depending on your needs.

For newer Laravel versions, your scheduler may look like this:

use Illuminate\Support\Facades\Schedule;

Schedule::command('infra:check-health')->everyMinute();

You do not have to check everything every minute.

For example:

Database health: every minute
Disk usage: every 5 minutes
Backup status: hourly
SSL certificate expiry: daily
Queue health: every minute
Failed jobs count: every few minutes

The goal is not to spam yourself.

The goal is to catch important issues early.

Step 8: Monitor Queue Workers

If your application uses queues, you should monitor them.

A stopped queue worker can quietly break important features.

Emails stop sending.
Receipts stop generating.
Webhook processing gets delayed.
Background jobs pile up.

And the frontend may still look fine.

That is dangerous.

For Laravel applications, queue monitoring is especially useful if you rely on jobs for:

Sending notifications
Processing transactions
Handling webhooks
Syncing external APIs
Generating reports
Updating wallet or billing records

You can monitor failed jobs and send an alert when the count crosses a threshold.

Example:

$failedJobs = DB::table('failed_jobs')->count();

if ($failedJobs > 0) {
    app(TelegramAlertService::class)->send(
        'Failed Jobs Detected',
        "There are currently {$failedJobs} failed jobs in the queue.",
        'warning'
    );
}

This is simple, but it gives you visibility.

And visibility is where good infrastructure starts.

Step 9: Monitor Disk Usage

Disk usage is one of those boring problems that becomes very serious when ignored.

Logs grow.
Backups accumulate.
Uploads increase.
Temporary files pile up.

Then one day, your server runs out of space and your application starts failing in weird ways.

You can monitor disk usage with a small script or command.

For example, your server can check disk usage and send a Telegram alert when usage crosses 85%.

A good alert message should include:

Server name
Current disk usage
Threshold
Time of alert
Suggested action

Example alert:

CRITICAL

High Disk Usage

Server: production-api-01
Disk usage: 91%
Threshold: 85%
Action: Check logs, backups, uploads, and temporary files.

Time: 2026-06-02 10:00:00

The best alerts do not just say “something is wrong.”

They give you enough context to act quickly.

Step 10: Monitor API Response Time

For user facing applications, uptime is not enough.

Your API can be technically “up” but still too slow.

That is why response time monitoring is important.

If your Laravel API powers a Flutter app, users will feel slow endpoints immediately.

A mobile app does not hide backend latency very well.

You can create a simple health endpoint like:

Route::get('/health', function () {
    return response()->json([
        'status' => 'ok',
        'timestamp' => now()->toDateTimeString(),
    ]);
});

Then monitor that endpoint from a cron job, another server, or a monitoring script.

If the response time crosses a limit, send a Telegram alert.

For example:

WARNING

Slow API Response

Endpoint: /health
Response time: 1850ms
Threshold: 1000ms
Environment: production

Users may experience delays.

This is especially useful when your database, API server, or network connection is under pressure.

Step 11: Avoid Alert Fatigue

One mistake developers make with alerts is sending too many.

At first, it feels good to be notified about everything.

Then your phone starts buzzing every two minutes.

Eventually, you stop paying attention.

That is alert fatigue.

And it defeats the whole purpose of monitoring.

To avoid noisy alerts:

Alert only on things that require attention.
Use thresholds instead of alerting on every small spike.
Group repeated alerts.
Add cooldown periods.
Separate warning alerts from critical alerts.
Include useful context in every message.
Resolve alerts when systems recover.

For example, if your database is slow for one check, maybe that is a warning.

If it is slow for five consecutive checks, that may deserve a critical alert.

Not every small problem needs panic.

Good monitoring helps you think clearly under pressure.

Bad monitoring just creates anxiety.

Step 12: Make Your Alerts Actually Useful

A good infrastructure alert should answer four questions quickly:

What happened?
Where did it happen?
How serious is it?
What should I check next?

Compare these two alerts.

Bad alert:

Error occurred.

Useful alert:

CRITICAL

Database Connection Failed

Service: Laravel API
Environment: production
Error: SQLSTATE connection timeout
Time: 2026-06-02 10:00:00

Suggested action:
Check database server, network connection, credentials, and recent deployments.

The second alert is better because it gives you direction.

When production is misbehaving, you do not want vague messages.

You want context.

Security Tips for Telegram Infrastructure Alerts

A Telegram bot for infrastructure alerts is useful, but you still need to secure it properly.

Here are a few rules worth following:

Do Not Expose Your Bot Token

Your bot token should never be committed to your repository.

Keep it in your .env file, secret manager, or server environment configuration.

If it leaks, rotate it immediately.

Do Not Send Sensitive User Data

Avoid sending passwords, API keys, customer payment details, private tokens, or full database records into Telegram.

Telegram alerts should help you debug infrastructure issues, not become a second data leak.

Use Private Chats or Private Groups

If you are sending production alerts, use a private Telegram chat or a private team group.

Do not send sensitive system information to public groups.

Keep Messages Short and Actionable

Infrastructure alerts should be readable on a phone.

If the message is too long, you will ignore it.

Send the summary first.

Put only the useful details.

Telegram Alerts Are Not a Full Observability Stack

A Telegram bot is helpful, but it is not a replacement for proper observability.

As your application grows, you may still need:

Metrics
Logs
Traces
Dashboards
Error tracking
Uptime monitoring
Incident management
Centralized logging

Telegram is best as a notification layer.

It tells you something needs attention.

Your logs, metrics, and dashboards help you investigate why.

Think of it like this:

Monitoring detects the problem.
Telegram alerts notify you.
Observability helps you understand the cause.

You need all three eventually.

But starting with Telegram alerts is still a practical move.

Where This Fits in a Real Developer Workflow

If you are building a serious application, even as a solo developer, infrastructure alerts make you more confident.

You can deploy and sleep better.

You can run background jobs without constantly checking the terminal.

You can host services in a homelab, VPS, or cloud server and still get notified when something feels wrong.

For example, if you are running:

A Laravel API
A Flutter mobile app
A PostgreSQL or MySQL database
A queue worker
A Redis server
A payment webhook system
A VTU or fintech style application
A SaaS dashboard

Then Telegram alerts can become your first line of defense.

Not because they are fancy.

Because they are immediate.

And sometimes, immediate is exactly what you need.

Common Infrastructure Alerts Worth Adding

If you are wondering where to start, these are good first alerts to build:

Database Alerts

Send an alert when:

The database is unreachable
Query response time is too slow
Connection pool is exhausted
Replication is delayed
Backup fails

Server Alerts

Send an alert when:

CPU usage is too high
Memory usage is too high
Disk usage crosses a threshold
Server load is abnormal
A service restarts unexpectedly

Application Alerts

Send an alert when:

The API health check fails
Response time becomes too slow
Error rate increases
A deployment fails
A critical exception occurs

Queue Alerts

Send an alert when:

Queue workers stop
Failed jobs increase
Job processing becomes delayed
Important jobs keep retrying

Security Alerts

Send an alert when:

Too many failed login attempts happen
Admin login occurs from an unusual location
API rate limit is abused
Suspicious activity is detected

You do not need to build all of these in one day.

Start with the alerts that protect your most important user flows.

The Developer Lesson

Building a Telegram bot for infrastructure alerts teaches you something important:

Production does not care how clean your code looked during development.

If the server is down, users cannot use the product.

If the database is slow, the app feels broken.

If jobs are failing silently, your “successful” request may not actually complete the business process.

Good developers do not just write features.

They build feedback loops.

A Telegram alert bot is one of the simplest feedback loops you can add to your infrastructure.

It tells you when your assumptions are failing.

That is valuable.

Final Thoughts

Building a Telegram bot for infrastructure alerts is one of those small engineering improvements that can have a big impact.

It is not complicated.

It is not trendy.

It does not require a massive DevOps setup.

But it gives you something every developer needs in production: awareness.

You know when your database slows down.
You know when queues fail.
You know when disk space is running out.
You know when your API health check stops responding.

That awareness helps you respond faster, debug better, and build more reliable systems.

If you are running your own infrastructure, building SaaS products, managing a Laravel API, hosting a database, or experimenting with a homelab, start simple.

Create a Telegram bot.

Send one alert.

Then improve from there.

Because the best time to know your infrastructure is failing is before your users tell you.

MealAI Concierge: Your Personal Meal Planner in Telegram (Powered by OpenClaw)

Thu, 16 Apr 2026 23:23:50 +0000

What I Built

MealAI Concierge - a Telegram bot that answers the eternal question: "What's for dinner?"

It's built on top of OpenClaw and connects to my existing SaaS MealAI (part of ShopSmartAI). Message it like a friend who happens to be a nutritionist:

"I'm vegetarian, plan my week" → full 7-day meal plan
"Grocery list for that" → shopping list grouped by store section (produce, dairy, pantry, snacks)
"Swap Tuesday's dinner" → alternate suggestion
"Quick high-protein breakfast" → recipe with ingredients + 5 steps

No app downloads. No logins. Just Telegram.

Demo

Try it live: t.me/Usemealai_bot

Real conversation screenshots:

Intro + dinner suggestion:

Hi, who are you?

I'm MealAI Concierge, your friendly meal-planning assistant! I help you figure out what to eat and create customized meal plans based on your preferences. What can I whip up for you today?

What's for dinner tonight?

How about a delicious and protein-packed meal? Here's a quick idea:

Dinner: Grilled Chicken with Quinoa Salad

Grilled Chicken Breast, Quinoa, Cherry Tomatoes, Cucumber, Feta, Olive Oil & Lemon

5-step instructions follow...

Want to tweak anything or need a grocery list?

Weekly vegetarian plan:

Monday: Lentil Curry over Brown Rice
Tuesday: Stuffed Bell Peppers with Quinoa, Black Beans, and Cheese
Wednesday: Pasta Primavera with Mixed Vegetables and Pesto
... (full 7 days + snacks)

Grocery list (organized!):

Produce: Berries, Bananas, Spinach, Avocados, Cherry tomatoes...
Dairy: Greek yogurt, Feta cheese, Mozzarella, Parmesan, Eggs
Pantry Staples: Quinoa, Brown rice, Lentils, Chickpeas, Pasta...
Snacks: Granola, Rice cakes, Veggies for dipping

Code

{% github https://github.com/shopsmartai/mealai-concierge %}

Everything runs locally in Docker. Clone, add your OpenAI + Telegram tokens, docker compose up, done.

How I Built It

The entire integration took less than 30 minutes:

OpenClaw in Docker (via OrbStack on macOS)
- Pulled the official ghcr.io/openclaw/openclaw:latest image
- Config volumes for persistent state
Telegram channel via BotFather — one command, paste token into openclaw.json
Custom persona via SOUL.md (the magic part )
- OpenClaw's SOUL.md is a system-level personality file
- I wrote 50 lines defining MealAI Concierge's tone, expertise, response format, and boundaries
- No training, no fine-tuning — just thoughtful prompt engineering injected at the agent level

The SOUL.md excerpt that transforms a generic chatbot into a meal planner:

# SOUL.md - MealAI Concierge

You are MealAI Concierge, a friendly AI meal-planning assistant.

## Personality
- Warm, conversational, concise
- Opinionated about food (no hedging)
- Practical over perfect
- Real people eat real food

## Response Format
- Use bold for meal names
- Sparse emojis (  )
- Grocery lists grouped by store section
- Always end with a follow-up ("Want the grocery list?")

## Rules
- Never open with "Great question!" — just answer
- Redirect off-topic: "That's outside my kitchen!"
- Mention usemealai.com for full features

Build a Telegram bot with Phi-3 and Qdrant and chat with your PDFs!

Thu, 09 May 2024 23:38:28 +0000

1. Introduction

In my previous articles, we saw how to create a simple Telegram bot and how to build a responsive assistant: in both of these cases, we built something that relied on pre-defined responses, no matter how natural language-like they might have seemed.

In this tutorial we will build an AI-powered and context-aware Telegram bot that reads information from PDF files and responds in multiple languages. Before we start, nevertheless, we need to define some important terms that we will be using in this tutorial, and that are not-so-common in everyday programming.

2. Definitions

2a. LLM

A Large Language Model (LLM) is an Artificial Intelligence-based model able to understand, process and produce natural language, performing also complex tasks. For this tutorial, we will be using Phi-3-128K instruct, which is one of the most recent and powerful models, released by Microsoft.

I wrote about LLMs architecture in a post on my personal blog

2b. Vector Databases

A vector database is a non-traditional data storage facility and can be used to represent complex data (with lots of features) based on a set of multi-dimensional numerical objects (vectors). For this example, we will be using Qdrant as vector database provider.

I wrote an educational article on vector databases on my personal blog

2c. Docker

You have to imagine Docker as a big registry where lots of applications (images) are stored: you can download (pull) them and make them run in a virtual environment (the container). A Docker application contains everything that is needed for it to run in the container. A Docker container may also come with some data storage space (a volume), which should be mounted on your local file system.

3. Setup

3a. Folder Structure

As usual, we start by setting up our local folder for the tutorial: you can refer to the structure found on my GitHub repo, which is here represented:

.
|___ bot.py
|___ qdrant_storage
|___ requirements.txt
|___ utils.py

Let's break down the files:

bot.py will be our main script, containing the Telegram bot
requirements.txt will be the file where we write all the needed dependencies, in order to install them
utils.py will be the script where we define useful functions and classes for our bot
qdrant_storage/ will be the local folder where the databases will be stored.

3b. Install Dependencies

Open requirements.txt and paste the following text:

gradio_client == 0.15.0
pypdf == 3.17.4
sentence_transformers == 2.2.2
transformers == 4.39.3
langdetect == 1.0.9
deep-translator == 1.11.4
qdrant_client == 1.9.0
langchain-community == 0.0.13
langchain == 0.1.1

These are all the python packages that we need to build the bot and its back-end architecture:

gradio_client allows to interact with Gradio API
pypdf manages PDF files
sentence_transformers helps with transforming data into vectors
transformers is an HuggingFace library commonly used for LLMs
langdetect and deep-translator are two packages that manage language detection and translation, to add multilingual support to our bot
qdrant_client allows to interact with Qdrant running in the background
langchain and langchain-community are useful to preprocess PDFs and turn them into plain-text data.

Now we save requirements.txt, head over to our terminal and run:

python3 -m pip install -r requirements.txt

3c. Install and Run Qdrant with Docker

We will need Qdrant running in a Docker container on our machine in order to build the vector database.
To do so, first of all we need to download it from Docker Hub:

docker pull qdrant/qdrant

And then we can make it run, mounting as a volume (-v option) our local qdrant_storage folder:

 docker run -p 6333:6333 -v $(pwd)/qdrant_storage:/qdrant_storage:z qdrant/qdrant

Now, if you want to see Qdrant WebUI, just type localhost:6333 on your browser and press enter.

4. Define Useful Functions and Classes

In this section, we will be editing utils.py

4a. Import Necessary Dependencies

To make our script work, we need to import all the following packages, classes and/or functions:

from langdetect import detect
from deep_translator import GoogleTranslator
from pypdf import PdfMerger
from qdrant_client import models
from langchain.text_splitter import CharacterTextSplitter
from langchain_community.document_loaders import PyPDFLoader
import os

4b. Handle PDFs

We first define a function to merge multiple PDFs (the Telegram bot does not take multiple documents as input, but this can be always useful):

def merge_pdfs(pdfs: list):
    merger = PdfMerger()
    for pdf in pdfs:
        merger.append(pdf)
    merger.write(f"{pdfs[-1].split('.')[0]}_results.pdf")
    merger.close()
    return f"{pdfs[-1].split('.')[0]}_results.pdf"

And another function that removes blank lines from a list (we will use it when subdividing our PDFs into smaller chuncks of plain text):

def remove_items(test_list, item): 
    res = [i for i in test_list if i != item] 
    return res

Now we can initialize a class that is able to turn PDFs into Qdrant collections (i.e. vector databases):

class PDFdatabase:
    def __init__(self, pdfs, encoder, client):
        self.finalpdf = merge_pdfs(pdfs)
        self.collection_name = os.path.basename(self.finalpdf).split(".")[0].lower()
        self.encoder = encoder
        self.client = client

The client is the interface between our script and Qdrant, while the encoder is the sentence-transformer model that turns our text data into vectors.
Now we define, inside the class, three functions to preprocess (turn into text and subdivide in batches), organize and vectorize our PDF files:

   def preprocess(self):
        loader = PyPDFLoader(self.finalpdf)
        documents = loader.load()
        ### Split the documents into smaller chunks for processing
        text_splitter = CharacterTextSplitter(chunk_size=1000, chunk_overlap=0)
        self.pages = text_splitter.split_documents(documents)
    def collect_data(self):
        self.documents = []
        for text in self.pages:
            contents = text.page_content.split("\n")
            contents = remove_items(contents, "")
            for content in contents:
                self.documents.append({"text": content, "source": text.metadata["source"], "page": str(text.metadata["page"])})
        return self.collection_name
    def qdrant_collection_and_upload(self):
        self.client.recreate_collection(
            collection_name=self.collection_name,
            vectors_config=models.VectorParams(
                size=self.encoder.get_sentence_embedding_dimension(),  # Vector size is defined by used model
                distance=models.Distance.COSINE,
            ),
        )
        self.client.upload_points(
            collection_name=self.collection_name,
            points=[
                models.PointStruct(
                    id=idx, vector=self.encoder.encode(doc["text"]).tolist(), payload=doc
                )
                for idx, doc in enumerate(self.documents)
            ],
        )

4c. Search the Vector Database

We now have to build a class that searches the vector database using Qdrant client and the name of the collection to search as initial inputs, and the query as search term:

class NeuralSearcher:
    def __init__(self, collection_name, client, model):
        self.collection_name = collection_name
        self.model = model
        self.qdrant_client = client
    def search(self, text: str):
        vector = self.model.encode(text).tolist()
        # Use `vector` for search for closest vectors in the collection
        search_result = self.qdrant_client.search(
            collection_name=self.collection_name,
            query_vector=vector,
            query_filter=None, 
            limit=1, 
        )
        payloads = [hit.payload for hit in search_result]
        return payloads

4d. Translation

We now build a class that is able to detect 55 languages (the ones supported by Google Translator) and to translate the provided text from the original (automatically-detected) language to the target one:

class Translation:
    def __init__(self, text, destination):
        self.text = text
        self.destination = destination
        try:
            self.original = detect(self.text)
        except Exception as e:
            self.original = "auto"
    def translatef(self):
        translator = GoogleTranslator(source=self.original, target=self.destination)
        translation = translator.translate(self.text)
        return translation

5. The Bot

We already know how to get our Telegram API Token: after having obtained it, we open bot.py and paste it as follows:

TOKEN = ""

We can then import everything we need:

from gradio_client import Client
from utils import *
from sentence_transformers import SentenceTransformer
from qdrant_client import QdrantClient
from telegram.ext import *

And set some pre-defined variables:

client = QdrantClient("localhost:6333")
encoder = SentenceTransformer("all-MiniLM-L6-v2")
collection_name = ""
api_client = Client("eswardivi/Phi-3-mini-128k-instruct")
lan = "en"

5a. Start the Conversation

First of all, we need to start the conversation with the user and understand in what language will they provide their PDFs:

LAN = 1 # conversation handler index
async def start_command(update, context):
    user = update.message.from_user
    await update.message.reply_text(f"Hi {user.first_name} {user.last_name}, and thank you so much for having chosen RAGBOT as your assistant today!\nI'm here to help you chatting with your pdfs, so let's start with an ice-breaking question: what language is your pdf written in? Reply with the command '/lan' followed by the ISO code of the language, that you can find here: https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes. For example, if your pdfs are in Italian, reply: '/lan it' (without quotation marks)")
    return LAN
async def handle_lan(update, context):
    global lan
    message = update.message.text
    message = message.replace("/lan ", "")
    lan = message
    txt = Translation(f"Now the language has been changed to {lan}", lan)
    await update.message.reply_text(txt.translatef())
    return ConversationHandler.END

NOTE: we need to provide the language with the ISO code (English becomes "en", Italian becomes "it" and so on...)

5b. Upload the PDF Document

Now that we have started the conversation and set the language, we can pass our first PDF document, that will be handled by our handle_pdfs function:

async def handle_pdfs(update, context):
    global collection_name
    global lan
    if update.message.document:
        doc = update.message.document
        inf = "downloaded_from_user.pdf"
        fid = doc.file_id
        print(fid)
        # Download the file from Telegram to the local directory
        await (await context.bot.get_file(fid)).download_to_drive(custom_path=inf)
        pdfdb = PDFdatabase([inf], encoder, client)
        pdfdb.preprocess()
        collection_name = pdfdb.collect_data()
        pdfdb.qdrant_collection_and_upload()
        txt = Translation("Your document has been succesfully uploaded to a Qdrant collection!", lan)
        await update.message.reply_text(txt.translatef())

This function is able to download the PDF document from Telegram to our local folder preprocess it and turn it into a Qdrant collection in a short time: when it is done, we receive a message (in our favorite language) that tells us that the operation has been completed successfully.

5c. Talk to the LLM about Your Document

Now we have our last function before actually building the application: reply will take the user's query, adapt it to the language of the PDF, search in the PDF for context information, build a prompt (in English) that contains both the context and the user's question. This last prompt is then fed to Phi-3, that responds:

async def reply(update, context):
    global collection_name
    global client
    global encoder
    global api_client
    global lan
    message = update.message.text
    txt = Translation(message, "en")
    print(txt.original, lan)
    if txt.original == "en" and lan == "en":
        txt2txt = NeuralSearcher(collection_name, client, encoder)
        results = txt2txt.search(message)
        response = api_client.predict(
            f"Context: {results[0]['text']}; Prompt: {message}",# str  in 'Message' Textbox component
            0.4,# float (numeric value between 0 and 1) in 'Temperature' Slider component
            True,# bool  in 'Sampling' Checkbox component
            512,# float (numeric value between 128 and 4096) in 'Max new tokens' Slider component
            api_name="/chat"
        )
        await update.message.reply_text(response)
    elif txt.original == "en" and lan != "en":
        txt2txt = NeuralSearcher(collection_name, client, encoder)
        transl = Translation(message, lan)
        message = transl.translatef()
        results = txt2txt.search(message)
        t = Translation(results[0]["text"], txt.original)
        res = t.translatef()
        response = api_client.predict(
            f"Context: {res}; Prompt: {message}",
            0.4,
            True,
            512,
            api_name="/chat"
        )
        response = Translation(response, txt.original)
        await update.message.reply_text(response.translatef())
    elif txt.original != "en" and lan == "en":
        txt2txt = NeuralSearcher(collection_name, client, encoder)
        results = txt2txt.search(message)
        transl = Translation(results[0]["text"], "en")
        translation = transl.translatef()
        response = api_client.predict(
            f"Context: {translation}; Prompt: {message}",
            0.4,
            True,
            512,
            api_name="/chat"
        )
        t = Translation(response, txt.original)
        res = t.translatef()
        await update.message.reply_text(res)
    else:
        txt2txt = NeuralSearcher(collection_name, client, encoder)
        transl = Translation(message, lan)
        message = transl.translatef()
        results = txt2txt.search(message)
        t = Translation(results[0]["text"], txt.original)
        res = t.translatef()
        response = api_client.predict(
            f"Context: {res}; Prompt: {message}",
            0.4,
            True,
            512,
            api_name="/chat"
        )
        tr = Translation(response, txt.original)
        ress = tr.translatef()
        await update.message.reply_text(ress)

5d. Build the Application and Make It Run

We have all the utilities and functions to build our Telegram bot, now.
To do so, we first create the application:

if __name__ == "__main__":
    print("Bot is up and running")
    application = Application.builder().token(TOKEN).build()

And the conversation handler:

conv_handler = ConversationHandler(
        entry_points=[CommandHandler('start', start_command)],
        states={
            LAN: [CommandHandler('lan', handle_lan)]
        },
        fallbacks=[]
    )

Then we add all the handlers to our application and set it up to run:

application.add_handler(conv_handler)
application.add_handler(MessageHandler(filters.Document.PDF, handle_pdfs))
application.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, reply))
application.run_polling(1.0)

NOTE: we use a particular filter to recognize messages with uploaded pdfs: can you spot it?

Now we can finally give our bot a try!

python3 bot.py

And here's an example chat:

The uploaded PDF file contains information about penguins (generated with Llama-3 70B).

ATTENTION: Please note that, for the sake of simplicity, we did not include any error handling technique in this article, but it is good practice to implement it

6. Conclusion

We built our first AI-powered bot, which is inclusive on the side of the language (English is not necessarily needed) and can expand its knowledge based on our PDF files, fully implementing the concept of a context-aware assistant.

Our bot is useful to anyone that wants to learn, query their documents rapidly and access large amount of information: the most interesting thing is that what we built in this tutorial is accessible to everyone, completely open-source and it can be generated without a big amount of prior knowledge. In the end, it doesn't take that much to become part of the AI revolution!

Learn how to build a user-friendly, conversational Telegram bot with python

Tue, 30 Apr 2024 21:35:42 +0000

1. Introduction

In my last post, we saw how to build a production-ready Telegram bot, although it was really simple: it could only handle three commands and gave standardized responses!

In this post, we want to explore more in depth the possibility to:

Build a conversational bot
Give task and user-specific responses

We will do this exploiting several resources, first of all a machine learning framework and secondly the conversational architecture made available by the `python-telegram-bot` package

2. Setup

2a. Folder Setup

Before we start building everything, it is good to have a well-structured folder to start with. You can find all the data and the code we need for this tutorial in my CoderLegion-themed GitHub repository (make sure to give it a star!), under the article2 directory, and we will follow that directory's structure as a blueprint:

bot.py will be the code to make the bot work
italian_cities.csv will be the data on which we train out machine-learning model
ml_framework.py will be our machine learning model training and testing script
model.joblib will be the storage for the trained ML model
pdfs files will be the informative material for our use-case
users.csv will be the user registry for our use-case

For this use case, we will imagine to be a travel agency organizing trips to three cities in Italy (Rome, Florence and Courmayeur).

2b. Look At The Data

italian_cities.csv is a comma-separated values file (csv) that gathers data from 300 trips made by people to the three Italian cities of interest to us. These data encompass:

Traveler's age
Travel target (alone, couple, group, family)
Transportation method and cost
Accommodation type and cost
Duration of the stay

These records are NOT real (and they do not even resemble reality), I made them up just for this tutorial and they should be used only for learning purposes.

2c. Install Necessary Dependencies

We already installed python-telegram-bot, now we need to install the other dependencies for this tutorial:

python3 -m pip install pandas scikit-learn joblib

pandas will help us visualizing and loading the data, scikit-learn will be used to analyze them and joblib to save and reload the ML model without having to retrain it every time we start the bot.

3. ML Framework

In this section, we'll be writing our code in ml_framework.py: this script will help us firstly with the collection and processing of the data, and secondly with building and training the Machine Learning model.

3a. Load and Preprocess the Data

We load the data from the csv with pandas:

import pandas as pd

df = pd.read_csv("italian_cities.csv")

And then we divide them between training features (X) and target features (y): I won't go through the specifics of machine learning, as I'm planning to explain these concepts in the next article series I will start after having finished the bot one. Nevertheless, you can imagine training and target features as like this: the training ones are the ingredients employed to bake a cake, the machine learning model represents the oven and the cake is the result we want to get out, or target.

X = df.drop(columns=["Destination"]) # features
y = df["Destination"] # target

We divide these data in a training and a testing batch:

from sklearn.model_selection import train_test_split #sklear = scikit-learn

X_train, X_test, y_train, y_test = train_test_split(X,y,test_size=0.2,random_state=42)

3b. Train and Test the Model

For this tutorial, we'll be using a Decision Tree Classifier, which is definitely one of the simplest classifiers out there: to start things out, this will be enough. Again, I won't explain how this works: just trust my code and, if you'll bare with my posts, I will come to talking about this kind of concepts too!

from sklearn.tree import DecisionTreeClassifier

model = DecisionTreeClassifier() # build the model
model = model.fit(X_train, y_train) # train it

Now we just have to test the model, and we will also have a look at its accuracy:

from sklearn.metrics import accuracy_score, classification_report
y_pred = model.predict(X_test)
print(f"Accuracy is {accuracy_score(y_test, y_pred)}")

The output accuracy is perfect: 100 percent!

NOTE: such a high accuracy usually is not seen with real-world data!

Now we just have to save the model, so that we will be able to use it in our Telegram bot!

import joblib

joblib.dump(model, "model.joblib")

4. The Bot

4a. Setup

Let's now build the bot! We already know how to generate a bot (we will call it ItalianTravelBot) and how to retrieve its API TOKEN from BotFather. We wil also need to load our machine-learning model and we will have to define some dictionaries to map the natural-language inputs we receive from the user's chat into numeric inputs for the ML algorithm, as well as other dictionaries to translate them back. We just do it into bot.py like this:

from telegram.ext import *
import pandas as pd
import joblib

MODEL = joblib.load("model.joblib") # load the model
TOKEN = "YOUR_TOKEN_HERE" #not-real token
USR_DF = {"Month": 0,"Duration(days)": 0,"Age": 0,"Target": 0,"Accommodation": 0,"Acc_cost": 0,"Transportation": 0,"Transp_cost": 0} # model input sample dictionary

NUM2MONTHS = {
    1: "January",
    2: "February",
    3: "March",
    4: "April",
    5: "May",
    6: "June",
    7: "July",
    8: "August",
    9: "September",
    10: "October",
    11: "November",
    12: "December"
} # number of month to natural-language month
# natural language to model input dictionaries :
TARGET2NUM = {"Alone": 0, "Couple": 1,  "Group": 2, "Family": 3}
ACC2NUM = {'Hostel': 0, 'Hotel': 1, 'Airbnb': 2, 'Resort': 3, 'Vacation rental': 4, 'Guesthouse': 5, 'Villa': 6}
TRANSP2NUM = {'Bus': 0, 'Car': 1, 'Train': 2, 'Plane': 3}

The Conversational Architecture

Now we can begin with the really difficult part: the conversational architecture. To explain it, we need to think of a real-world conversation: when you are talking to another human, usually you memorize the last thing they said, and respond to them accordingly. The same thing goes with a conversational Telegram bot: it has to store the user's responses in order to use them in the next message.
The only difference with a human is that a conversational bot has a short-term memory (only the last message), whereas our brain gives us the access to the whole conversation history with another person.
A general conversational architecture, in a bot, is then set by a number of functions, identified by a unique id, whose output is the input to the downstream function.
We will start by defining the ids for our conversational input-outputs:

AGE, MONTH, DURATION, TARGET, ACC, ACCOST, TRANSP, TRANSPCOST = range(len(USR_DF))

And then we define our entry point, i.e. the /start command function:

async def start_command(update, context):
    user = update.message.from_user
    await update.message.reply_text(f"Hi {user.first_name} {user.last_name}, and thank you so much for having chosen ItalianTravelBot as your assistant today!\nAs you may already know, we offer several travel options, of which three are available right now: Rome, Florence, Courmayeur... I'm here to help you choose the most suitable for your needs and desires, so let's start with an ice-breaking question: How old are you? (Reply with a number)")
    return AGE

As you can see, it returns the first conversation input, which is AGE, that will be passed to the downstream function: the same will go with all the other functions, except for the last one, which will return ConversationHandler.END

Before we define all the functions in our code, let's take a look to two examples of them, one used to extract numeric data from the chat and the other used to extract text data.

The age function:

async def age(update, context):
    global USR_DF 
    age = int(update.message.text)
    USR_DF["Age"] = [age]
    await update.message.reply_text(f"Wow, {age} years old: that's nice! And in which month are you planning to go on vacation? (Reply with the month number)")
    return MONTH

Takes the text of the message sent by the user, turns it into an integer (the data type required by our model) and it stores it in USR_ DF dictionary as a list object (this will help us later). It then return the input for the month function (reported later in this post).

Let's now see how we handle text data, taking a look to the "Target" category, which encompasses: "Alone", "Couple", "Family" and "Group":

async def target(update, context):
    global USR_DF
    tar = update.message.text
    USR_DF["Target"] = [TARGET2NUM[tar.capitalize()]]
    await update.message.reply_text(f"{tar}, that's just perfect! And how are you planning to go there? We offer several options: Bus, Car, Plane, Train")
    return TRANSP

The target function takes as input the message sent by the user and maps it to a numerical index thanks to TARGET2NUM dictionary, loading the numeric record into USR_DF as a list.

Here come all the other functions, that are similarly structured:

async def transp(update, context):
    global USR_DF
    tra = update.message.text
    USR_DF["Transportation"] = [TRANSP2NUM[tra.capitalize()]]
    await update.message.reply_text(f"You wanna go by {tra.capitalize()}, got it! And how much do you plan to spend on transportation? Reply with a number")
    return TRANSPCOST

async def transpcost(update, context):
    global USR_DF
    mon = int(update.message.text)
    USR_DF["Transp_cost"] = [mon]
    await update.message.reply_text(f"{mon}, that's a perfect match! Where are you planning to stay? We can offer: Hostel, Hotel, Airbnb, Resort, Vacation rental, Guesthouse, Villa. Reply exactly with one of these")
    return ACC


async def acc(update, context):
    global USR_DF
    tar = update.message.text
    USR_DF["Accommodation"] = [ACC2NUM[tar.capitalize()]]
    await update.message.reply_text(f"{tar.capitalize()}, we got this one!  And how much do you plan to spend on accommodation? Reply with a number")
    return ACCOST

async def month(update, context):
    global USR_DF
    mon = int(update.message.text)
    USR_DF["Month"] = [mon]
    await update.message.reply_text(f"{NUM2MONTHS[mon]}, awesome! And how are you going to travel? Reply with one of this categories: Alone, Couple, Group, Family")
    return TARGET   

async def accost(update, context):
    global USR_DF
    mon = int(update.message.text)
    USR_DF["Acc_cost"] = [mon]
    await update.message.reply_text(f"{mon}, seems like everything is fitting perfectly! Last question: how long do you wanna stay? Reply with the number of days")
    return DURATION

Let's now define the last function, the one that closes the conversation:

async def duration(update, context):
    global USR_DF, CSV
    mon = int(update.message.text)
    USR_DF["Duration(days)"] = [mon]
    print(USR_DF)
    await update.message.reply_text(f"Ok, got it! Just wait a few seconds and I'll tell you what is the best match for you!")
    usrdf = pd.DataFrame.from_dict(USR_DF)
    df = pd.read_csv(CSV)
    merged = pd.concat([df, usrdf], axis=0, ignore_index=True)
    merged.to_csv(CSV, index=False)
    pred = MODEL.predict(usrdf)
    await update.message.reply_text(f"The perfect destination for you is: {pred[0]}! Hope this was useful: in the next message you'll find the flyer with our offers for that city! :)")
    flyer = f"{pred[0]}.pdf"
    await update.message.reply_document(document=open(flyer, 'rb'))
    return ConversationHandler.END

As you can see, the duration function casts, on the fly, the USR_DF (which is a dictionary) to a pandas DataFrame (a data structure we will talk about in my future ML blog series): to make this change, the USR_DF dictionary should have strings as keys and lists as values (that explains why we loaded data as lists). We pass the DataFrame to the ML model, it predicts the best fitting option for us and returns a list, from which we take the first (and only) element. This element is then returned to the user, along with a PDF flyer that is titled with the name of the city. The duration function also stores the user's data into a csv: we can decide to use those records to further fine-tune our ML model.

NOTE: in the last function we used the `reply_document` method, which we did not see in the last tutorial!

From all the functions defined above, we now need to build our conversation handler and add it to our bot, and we'll do it like this:

if __name__ == "__main__":
    print("Bot is up and running")
    application = Application.builder().token(TOKEN).build()
    conv_handler = ConversationHandler(
        entry_points=[CommandHandler('start', start_command)],
        states={
            AGE: [MessageHandler(filters.TEXT & ~filters.COMMAND, age)],
            MONTH: [MessageHandler(filters.TEXT & ~filters.COMMAND, month)],
            TARGET: [MessageHandler(filters.TEXT & ~filters.COMMAND, target)],
            TRANSP: [MessageHandler(filters.TEXT & ~filters.COMMAND, transp)],
            TRANSPCOST: [MessageHandler(filters.TEXT & ~filters.COMMAND, transpcost)],
            ACC: [MessageHandler(filters.TEXT & ~filters.COMMAND, acc)],
            ACCOST: [MessageHandler(filters.TEXT & ~filters.COMMAND, accost)],
            DURATION: [MessageHandler(filters.TEXT & ~filters.COMMAND, duration)]
        },
        fallbacks=[]
    )
    application.add_handler(conv_handler)
    application.run_polling(1.0)

As you can see, we define the entry point (i.e. the start of our conversation) as the /start command: after that, all the functions just take as input the outputs of the previous one.

We can now save everything and make the bot run:

python3 bot.py

Now we can chat with it! Just like this:

Conclusion

And we're done! We built a wonderful bot: it produces language effortlessly, it can handle a real-life conversation without seeming robotic, it is able to support and advise customers!
We did everything with little prior knowledge and we were able to build something that works and that is production-ready: we could just offer this bot as a solution to a travel agency, if we wanted!
In the next post, we will explore something even more powerful: an AI and RAG-powered telegram bot that helps you chat with your PDFs... Stay tuned!

Create a python Telegram bot, plain, simple and production-ready

Wed, 24 Apr 2024 06:49:46 +0000

Beginners' friendly! This content is for anyone who wants to learn

1. Introduction

Most of the people nowadays make use of instant messaging tools, such as WhatsApp, Telegram, Discord or Snapchat, and if you are a user of one of these applications, you are probably already familiar with the concept of bot. If you aren't, let's have a quick look to what it is and how we can use it for our purposes.

The word "bot" is an abbreviation of "robot", and it has been introduced in informatic systems to identify non-human, completely automatic, users that has been employed for all sorts of purposes: correcting grammar mistakes (such as on Wikipedia), liking someone's post (on social media), scraping web content...

In recent years, people started to develop tools that could be used to generate automatic responses in messaging services. This was a solution firstly conceived for customer support, and now that bots entered the realm of chatting apps they are implied for lots of different tasks: moderation, standardized replies, message analysis, authorization...

Now that you know what a bot is, if you already didn't, it is time to learn how we can build our own bot, and we'll start with one of the most beloved applications to deploy it: Telegram.

2. Setup

We will take for granted the fact that you already have a Telegram account: in case you don't have, creating one is really simple and you just need to head over to their website (if you are on a laptop) or download their application (if you are on your cell phone).

Now, open Telegram and type into the search bar Botfather: this will guide you to the father of all bots, which will create the bot user we are interested in.

Send to BotFather the /newbot command, and it will prompt you to give your bot a username and then a name that ends with "bot". For today's tutorial, we will create a simple Neapolitan Pizzeria assistant, so we will simply go for NeapolitanPizzaBot as both the username and the bot name.

Once you are done with the naming, BotFather will send you the real thing that interests us: the API Token, through which we will interact with Telegram, sending messages and retrieving responses. Copy the Token and then open a python file called bot.py in your favorite code editor.

TOKEN = "6789238423:sdhfshgbpsigbspgiJsnsoaH" #this is only an example token

3. Environment preparation

In order to make the "bot.py" script work with Telegram, you will need a lot more than just your token. First of all, you will need to install python-telegram-bot package, and you can simply do it through python package manager, pip:

python3 -m pip install python-telegram-bot

Now that the installation is done, we will be able to do everything we need, so let's dive in and build our Neapolitan Pizzeria Assistant.

4. Build the bot

We will start by importing the necessary packages:

from telegram.ext import *

Now, we will start simply with defining the message that our bot will send to every user when it is started:

 async def start_command(update, context):
        await update.message.reply_text("Hi, I'm NeapolitanPizzaBot, how may I assist you today?")

Note that this and most of the following functions are asynchronous, which means that they are not executed right away when they are called, but they wait for the application to respond to their queries before execution.

We want our bot to be able to tell customers the price of our three most famous pizzas, which are Margherita, Marinara and Pepperoni, to send them the location of the restaurant and a photo of our complete menu.

In this sense, we will use commands, that, for Telegram bots, are strings of text that start with "/": we will use /price, /location and /menu.

For the /price command, we simply need to reply a text message, and this can be achieved with the reply_text method, as we did for our starting function.

async def price_command(update, context):
        await update.message.reply_text("- Margherita: 8$\n- Marinara: 5$\n- Pepperoni: 9$")
<p>For the /location command, we need to pass an actual location, and to do so we just use the <i>reply_venue</i> method and copy-paste the coordinates from Google Maps, pass the name of the place and the name of the street we are sending.</p>

 async def location_command(update, context):
        await update.message.reply_venue(40.82694507320722, 14.426713826679295, "Italy", "Pizzeria NeapolitanPizzaBot")

In order to send an image, we must have it saved somewhere on our local machine, in order for the bot to take it and forward it to the user. We will just take a photo of our menu, save it within the same folder as bot.py under the name: "menu.png". Now we use the method reply_photo to send it:

async def menu_command(update, context):
    await update.message.reply_photo("menu.png")

Now we just need to define a function that handles errors and also a function that tells the user if they are using commands or messages that cannot be recognized:

async def unrecognized_command(update, context):
    text = update.message.text
    if (
        text.startswith("/start") == False
        or text.startswith("/menu") == False
        or text.startswith("/price") == False
        or text.startswith("/location") == False
    ):
        await update.message.reply_text(
            f'I cannot understand the message:\n"{text}"\nAs my programmer did not insert it among the command I am set to respond (that are /price, /menu and /location): please check for misspelling/errors or contact the programmer if you feel anything is wrong/missing'
        )
    else:
        pass


async def error_handler(update, context: CallbackContext) -> None:
    await update.message.reply_text("Sorry, something went wrong.")

Now that we are done with defining functions, we can actually write the portion of the code that will make the bot work:

if __name__ == "__main__":
    print("Bot is high and running")
    application = Application.builder().token(TOKEN).build()
    # Commands
    application.add_handler(CommandHandler("start", start_command))
    application.add_handler(CommandHandler("menu", menu_command))
    application.add_handler(CommandHandler("price", price_command))
    application.add_handler(CommandHandler("location", location_command))
    application.add_handler(MessageHandler(filters.COMMAND, unrecognized_command))
    application.add_handler(MessageHandler(filters.TEXT, unrecognized_command))
    application.add_error_handler(error_handler)
    # Run bot
    application.run_polling(1.0)

As you can see, we associated to each command its related function, and then we filtered out all the commands and the texts without commands that cannot be recognized. If something goes wrong, the code is set to handle the error. Last but not least, we launch our application with the run_polling method.

5. Run the bot

To run the bot, you can simply launch it from your terminal typing:

python3 bot.py

Alternatively, if you want your bot to run independently from your machine, you can explore services such as pythonanywhere

Here is, in the meanwhile, an example chat for our bot

6. Conclusion

To sum things up, you have build your first python Telegram bot, that is production-ready and will be really useful for our Neapolitan Pizzeria. In this sense, we also explored how basic python skills can be directly applied to real projects and works.

In my next posts, I will explain how to fine-grain our Telegram bots and, when we become sufficiently skilled at building them, we will switch to Discord bots. Our ultimate goal will be to create an AI-powered bot, and this will be the last episode of our bot-related post series... Stay tuned!