Pick one job that happens at least daily and annoys someone. A bot that does one thing reliably gets used. A bot that tries to do ten things gets muted.

Why Telegram for internal automation?

Telegram's Bot API is free, well documented, and works over plain HTTPS with no SDK required. Bots can join groups, send inline keyboards, receive files and photos, and run on a webhook you host anywhere. If your team lives in Slack instead, the same architecture applies, with Slack events and Block Kit in place of Telegram updates and inline keyboards.

What does the architecture look like?

Telegram  --HTTPS POST-->  /api/telegram (Next.js route)
                              | 1. check secret header
                              | 2. insert update_id (unique)
                              | 3. return 200 immediately
                              v
                         background step
                              | 4. parse or classify the message
                              | 5. risky? ask for approval button
                              | 6. run the action (DB, tracker, payments)
                              v
                         sendMessage back to the chat

Each piece has a reason. The secret header stops strangers from posting fake updates. The unique update_id stops Telegram retries from running the same action twice. The fast 200 keeps Telegram from retrying in the first place. The background step lets slow work, like an LLM call, happen without holding the webhook open.

How do you create the bot and register the webhook?

1. Open a chat with @BotFather in Telegram, send /newbot, and pick a name and a username ending in bot. BotFather returns a token. Treat it like a password.
2. If the bot will read normal messages in a group, send /setprivacy to BotFather and disable privacy mode. With privacy mode on, the bot only sees commands, mentions, and replies to it, which is often what you want anyway.
3. Generate a random secret string for webhook verification.
4. Deploy your route, then register the webhook:

curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook" \
  -d "url=https://yourapp.com/api/telegram" \
  -d "secret_token=$TELEGRAM_WEBHOOK_SECRET" \
  -d 'allowed_updates=["message","callback_query"]'

Telegram then includes your secret in the X-Telegram-Bot-Api-Secret-Token header on every request. Webhooks must use HTTPS on port 443, 80, 88, or 8443, which any normal host like Vercel already gives you.

How do you write the webhook handler?

Here is a minimal Next.js App Router handler in TypeScript. It verifies the secret, records the update once, and hands the work off after responding.

// app/api/telegram/route.ts
import { after } from "next/server";
import { createClient } from "@supabase/supabase-js";
import { handleUpdate } from "@/lib/bot/handle-update";

const db = createClient(process.env.SUPABASE_URL!, process.env.SUPABASE_SERVICE_ROLE_KEY!);

export async function POST(req: Request) {
  if (req.headers.get("x-telegram-bot-api-secret-token") !== process.env.TELEGRAM_WEBHOOK_SECRET) {
    return new Response("forbidden", { status: 403 });
  }

  const update = await req.json();

  const { error } = await db
    .from("telegram_updates")
    .insert({ update_id: update.update_id, payload: update });

  if (error?.code === "23505") return new Response("ok"); // duplicate delivery, already handled
  if (error) return new Response("db error", { status: 500 }); // let Telegram retry

  after(() => handleUpdate(update)); // runs after the response is sent
  return new Response("ok");
}

The table behind it is small:

create table telegram_updates (
  update_id bigint primary key,
  payload jsonb not null,
  status text not null default 'received',
  received_at timestamptz not null default now()
);

after() is available in recent Next.js versions and works on Vercel. If your host cannot run work after the response, write the row and let a queue or a cron worker pick up rows where status = 'received'. That version is also easier to retry and inspect.

How do you send replies and buttons?

You only need one small helper for most bots:

// lib/bot/telegram.ts
const API = `https://api.telegram.org/bot${process.env.TELEGRAM_BOT_TOKEN}`;

export async function tg(method: string, body: Record<string, unknown>) {
  const res = await fetch(`${API}/${method}`, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify(body),
  });
  const data = await res.json();
  if (!data.ok) throw new Error(`Telegram ${method} failed: ${data.description}`);
  return data.result;
}

export const reply = (chatId: number, text: string, extra: object = {}) =>
  tg("sendMessage", { chat_id: chatId, text, ...extra });

An approval request is a message with an inline keyboard:

await reply(managerChatId, `Refund 42.00 USD on order 8812?\nReason: double charge`, {
  reply_markup: {
    inline_keyboard: [[
      { text: "Approve", callback_data: `refund:approve:${actionId}` },
      { text: "Reject", callback_data: `refund:reject:${actionId}` },
    ]],
  },
});

Keep callback_data short, because Telegram caps it at 64 bytes. Store the full action in your database and put only its id in the button. When the button is pressed you receive a callback_query update. Call answerCallbackQuery so the spinner stops, check that the presser is allowed to approve, then run the action.

Where does an LLM fit in, and where should it not?

Use the model for one job: turning a free-text message into a structured, validated action. Do not let it call your payment API directly.

// lib/bot/classify.ts
import { z } from "zod";

export const Action = z.discriminatedUnion("type", [
  z.object({ type: z.literal("expense"), amount: z.number(), currency: z.string().length(3), vendor: z.string() }),
  z.object({ type: z.literal("task"), title: z.string(), assignee: z.string().nullable(), due: z.string().nullable() }),
  z.object({ type: z.literal("refund"), orderId: z.string(), amount: z.number(), reason: z.string() }),
  z.object({ type: z.literal("unknown") }),
]);

export async function classify(text: string) {
  const raw = await callModelForJson({
    system: "Convert the ops message into one JSON action. If unsure, return {\"type\":\"unknown\"}. Never guess amounts.",
    user: text,
  });
  const parsed = Action.safeParse(raw);
  return parsed.success ? parsed.data : { type: "unknown" as const };
}

callModelForJson is whatever structured-output call your provider supports. The important parts are the schema check and the "unknown" escape hatch. Then route by risk:

This keeps the model useful without making it the last line of defense.

How do you keep the bot safe and well behaved?

• Allowlist chats and users. Check chat.id and from.id against a table of known team members before doing anything. Anyone can find and message a public bot.
• Keep secrets server side. The bot token, database keys, and model keys live in environment variables, never in messages or logs.
• Respect rate limits. Telegram's documentation suggests staying around one message per second per chat, about 20 per minute in a group, and about 30 per second overall. Batch digests into one message instead of many.
• Split long text. A single message is limited to 4096 characters, so chunk long reports or send a file.
• Log every action with the update_id, who triggered it, what ran, and the result. When someone asks "why did the bot do that?", you need an answer.
• Test the parser. Keep 30 or more real messages with their expected actions and run them whenever the prompt or model changes.

What usually breaks first?

How long does a first version take?

A single-job bot, such as expense logging or a daily digest, is usually a few days of focused work for someone comfortable with TypeScript and a hosted database. Approvals, multiple jobs, and integrations with tools like Linear, Notion, or Stripe add time, mostly in permissions and edge cases rather than in the Telegram parts.

How Luminix Studio builds ops bots

Luminix Studio builds web and mobile apps and the AI automations around them for startups worldwide, including Telegram and Slack bots, content pipelines, internal tools, and agent loops. The shape above is the one we reach for: a verified webhook, idempotent updates, a schema-checked model step, and human approval on anything that moves money or data. If you want an ops bot for your team, or want an existing one made reliable, see luminixstudio.com.