telegram
Send messages with buttons through your app’s own Telegram bot with manh/telegram, and create the link that lets a user receive them.
The app owner connects a bot (made with @BotFather) at Settings › Telegram. The bot token never appears in app code. Messages go out under the app’s bot.
Usage
import { send } from "manh/telegram";
import { env } from "manh/env";
export async function notifyManager(manager: User, o: Order) {
// … write to the database first
if (!manager.telegramChatId) return;
try {
await send(manager.telegramChatId, `Order #${o.id} awaits 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 (e: any) {
if (e.blocked) await clearChatId(manager.id); // the user blocked the bot
}
}Use it in .ts files only. Send after the database write, inside try/catch: the main action must not fail because a notification couldn’t go out.
Signature
type Button = { text: string; data?: string } | { text: string; url: string };
type SendOptions = { buttons?: Button[][]; parse?: "html" | "markdown"; silent?: boolean; replyTo?: number };
function send(chatId: number | string, text: string, o?: SendOptions): Promise<{ chatId: number; messageId: number }>;
function edit(chatId: number | string, messageId: number, text: string, o?: { buttons?: Button[][]; parse?: "html" | "markdown" }): Promise<void>;
function answerButton(callbackId: string, text?: string): Promise<void>;
function linkUrl(userId: number | string): Promise<string>;Parameters
chatId: the chat id, taken from thelinkevent (see Examples) and stored on the user.text: the content, up to 4,096 characters (the rest is cut).o.buttons: rows of buttons. A{ text, data }button sendsdata(up to 64 characters) to the*.telegram.tsfile when pressed; a{ text, url }button opens the link.o.parse:"html"or"markdown"for text formatting.o.silent:truesends without a notification sound.o.replyTo: themessageIdto reply to.messageId(edit): the message to edit, from the result ofsend.callbackId,text(answerButton): answer a button press with a small notice, up to 200 characters.userId(linkUrl): the user’s id in the app, up to 36 characters.
Returns
sendreturns{ chatId, messageId }.editandanswerButtonreturn nothing.linkUrlreturns a signedhttps://t.me/<bot>?start=…link, so nobody can claim another user’s account.
When Telegram reports an error, the function throws an error with status; err.blocked is true when the user blocked the bot or never pressed Start. On a rate limit (429), send waits and retries by itself. Without a connected bot every function throws.
Examples
A bot can only message people who pressed Start. Return the link for the signed-in user:
import { linkUrl } from "manh/telegram";
export default async (c, { user }) => ({ url: await linkUrl(user.id) });When the user presses Start, the app’s *.telegram.ts file receives { kind: "link", userId, chatId }. Store chatId in a telegramChatId column (text, nullable) of the users table:
export default async function (e) {
if (e.kind === "link") {
await saveChatId(e.userId, String(e.chatId));
return "Telegram notifications are on"; // a returned string is sent back to the chat
}
if (e.kind === "button") { /* e.data = "approve:12" */ }
}An app has one *.telegram.ts file. Events have kind "message", "button" or "link"; button presses are answered for you after the file runs.
Next steps
- Receive Telegram messages: *.telegram.ts: messages and button presses from the bot.
- email: notify by email.
- env:
MANH_APP_URLfor links in messages.