telegram
Gửi tin nhắn có nút bấm qua bot Telegram của chính app bằng manh/telegram, và tạo link để người dùng bật nhận tin.
Chủ app nối bot (tạo bằng @BotFather) ở Cài đặt › Telegram. Token của bot không bao giờ nằm trong code app. Tin gửi đi mang tên bot của app.
Cách dùng
import { send } from "manh/telegram";
import { env } from "manh/env";
export async function notifyManager(manager: User, o: Order) {
// … ghi database trước
if (!manager.telegramChatId) return;
try {
await send(manager.telegramChatId, `Đơn #${o.id} chờ duyệt`, {
buttons: [
[{ text: "Duyệt", data: `approve:${o.id}` }, { text: "Từ chối", data: `reject:${o.id}` }],
[{ text: "Xem đơn", url: `${env.MANH_APP_URL}/orders/${o.id}` }],
],
});
} catch (e: any) {
if (e.blocked) await clearChatId(manager.id); // người dùng đã chặn bot
}
}Chỉ dùng trong file .ts. Gửi tin sau khi ghi database, trong try/catch: việc chính không được hỏng vì tin báo không gửi được.
Chữ ký
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>;Tham số
chatId: mã cuộc trò chuyện, lấy từ sự kiệnlink(xem Ví dụ) và lưu trên người dùng.text: nội dung, tối đa 4.096 ký tự (phần thừa bị cắt).o.buttons: các hàng nút. Nút{ text, data }gửidata(tối đa 64 ký tự) về file*.telegram.tskhi bấm; nút{ text, url }mở link.o.parse:"html"hoặc"markdown"để định dạng chữ.o.silent:truethì gửi không kèm tiếng báo.o.replyTo:messageIdcủa tin cần trả lời.messageId(edit): tin cần sửa, lấy từ kết quảsend.callbackId,text(answerButton): trả lời một lần bấm nút bằng thông báo nhỏ, tối đa 200 ký tự.userId(linkUrl): id người dùng trong app, tối đa 36 ký tự.
Trả về
sendtrả{ chatId, messageId }.editvàanswerButtonkhông trả gì.linkUrltrả linkhttps://t.me/<bot>?start=…có chữ ký, nên không ai mạo nhận được tài khoản người khác.
Khi Telegram báo lỗi, hàm ném lỗi có status; err.blocked là true khi người dùng đã chặn bot hoặc chưa bấm Start. Gặp giới hạn tốc độ (429), send tự chờ và thử lại. Chưa nối bot thì mọi hàm ném lỗi.
Ví dụ
Bot chỉ nhắn được cho người đã bấm Start. Trả link cho người đang đăng nhập:
import { linkUrl } from "manh/telegram";
export default async (c, { user }) => ({ url: await linkUrl(user.id) });Người dùng bấm Start, file *.telegram.ts của app nhận sự kiện { kind: "link", userId, chatId }. Lưu chatId vào cột telegramChatId (kiểu text, cho phép null) của bảng users:
export default async function (e) {
if (e.kind === "link") {
await saveChatId(e.userId, String(e.chatId));
return "Đã bật thông báo Telegram"; // chuỗi trả về được gửi lại vào cuộc trò chuyện
}
if (e.kind === "button") { /* e.data = "approve:12" */ }
}Mỗi app có một file *.telegram.ts. Sự kiện có kind là "message", "button" hoặc "link"; nút bấm được trả lời tự động sau khi file chạy xong.
Bước tiếp theo
- Nhận tin Telegram: *.telegram.ts: nhận tin nhắn và lượt bấm nút từ bot.
- email: báo tin qua email.
- env:
MANH_APP_URLcho link trong tin.