Skip to Content

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

app/orders/repository.ts
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

manh/telegram
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 the link event (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 sends data (up to 64 characters) to the *.telegram.ts file when pressed; a { text, url } button opens the link.
  • o.parse: "html" or "markdown" for text formatting.
  • o.silent: true sends without a notification sound.
  • o.replyTo: the messageId to reply to.
  • messageId (edit): the message to edit, from the result of send.
  • 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

  • send returns { chatId, messageId }.
  • edit and answerButton return nothing.
  • linkUrl returns a signed https://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:

app/me/telegram-link/get.ts
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:

app/bot/bot.telegram.ts
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

Last updated