Telegram bot
≈ 15 min · you will have managers who get new orders on Telegram and press Approve right in the message.
Outgoing messages carry the owner’s bot name, not manh.run’s. The app receives messages and button presses in a *.telegram.ts file and sends messages with buttons through manh/telegram.
The app owner connects a bot
Create a bot with @BotFather in Telegram, then paste its token under Settings › Telegram in the project. The token stays with manh.run; neither the app’s code nor the agent sees it. Never put a token in code: check reports code.telegram-token-literal.
Users link their account
A bot can only message people who pressed Start. Add a nullable telegramChatId: text("telegram_chat_id") column to the users table, then give each person their own link with linkUrl(userId):
import { linkUrl } from "manh/telegram";
export default async (c, { user }) => ({ url: await linkUrl(user.id) }); // https://t.me/<bot>?start=…A page shows a button that opens the link, for example Get notifications on Telegram. The link is signed, so nobody can claim someone else’s account.
Receive messages and button presses
Each app has exactly one *.telegram.ts file. Its default export gets an event { kind, chatId, from, text, data, userId }; a returned string is sent back to the chat.
import { send } from "manh/telegram";
import { saveTelegramChat } from "../users/repository";
import { approveOrder } from "../orders/repository";
export default async function (e) {
if (e.kind === "link") { // the user pressed Start on linkUrl(userId)
await saveTelegramChat(e.userId, String(e.chatId));
return "Telegram notifications are on for your account.";
}
if (e.kind === "button") { // e.data = the pressed button's data
const [action, id] = e.data.split(":");
if (action === "approve") {
await approveOrder(Number(id), String(e.chatId));
await send(e.chatId, `Order #${id} approved`);
}
return;
}
if (e.text === "/orders") return "Type an order number to see its status."; // kind = "message"
}Send a message with buttons
Send after the database write, in try/catch: a notification must not break the main action.
import { send } from "manh/telegram";
import { env } from "manh/env";
export async function notifyManager(o: Order, chatId: string) {
try {
await send(chatId, `Order #${o.id}: ${o.total.toLocaleString("en-US")} VND waiting for approval`, {
buttons: [
[{ text: "Approve", data: `approve:${o.id}` }, { text: "Reject", data: `reject:${o.id}` }],
[{ text: "View order", url: `${env.MANH_APP_URL}/orders/${o.id}` }],
],
});
} catch (err: any) {
if (err.blocked) await clearTelegramChat(chatId); // the user blocked the bot
}
}Good to know
- A button press has no user on the request and doesn’t go through
access. Look up who pressed by the storedchatIdand check their role in the repository before approving. - Telegram may deliver an event again. The handler runs once per event, but keep writes safe to repeat anyway.
- The handler must finish quickly (under about 30 seconds). Slow work goes to a background job in
manh/jobs. - Button
datais at most 64 characters. Telegram allows about 30 messages per second per bot and 1 per second per chat;sendwaits and retries. edit(chatId, messageId, text)changes a sent message, for example to “Order #12 approved” after the press.
Next steps
- Scheduled jobs — send a reminder every morning without anyone pressing a button.
- std/telegram —
send,edit,answerButton,linkUrland every option. - *.telegram.ts — the full event type.