Skip to Content

*.telegram.ts

File *.telegram.ts nhận mọi tin nhắn, nút bấm và lượt bấm Start gửi tới bot Telegram của app; mỗi app có đúng một file như vậy.

app/ ├── users/ │ └── users.table.ts # thêm cột telegramChatId ├── me/ │ └── telegram-link/ │ └── get.ts # trả link để người dùng bật thông báo ├── orders/ │ └── repository.ts # gửi tin có nút "Duyệt" khi có đơn mới └── bot/ ├── repository.ts └── bot.telegram.ts # mọi thứ gửi tới bot

Dùng khi nào

Nhân viên ít mở app nhưng luôn mở Telegram. Bot của app báo đơn mới, việc cần duyệt, lịch hẹn sắp tới; người nhận bấm nút ngay trong Telegram để duyệt hay từ chối. Họ cũng nhắn lệnh ngắn cho bot, ví dụ /don để xem số đơn đang chờ.

Nối bot vào app

  1. Chủ app tạo bot bằng @BotFather trong Telegram.
  2. Chủ app dán token của bot ở Kết nối › Telegram trong project. manh.run giữ token và trỏ bot về app; code của app không bao giờ thấy token.
  3. Tin nhắn đi ra mang tên bot của chủ app, không phải manh.run.

Chưa nối bot thì send và linkUrl ném lỗi “Telegram is not connected”. Agent không hỏi token, chỉ nhờ chủ app làm bước 2.

Người dùng liên kết với bot

Telegram chỉ cho bot nhắn người đã bấm Start, và bot không biết người đó là ai trong app. Vì vậy mỗi người dùng nhận một link riêng:

  1. Handler gọi linkUrl(user.id) từ manh/telegram, trả về https://t.me/<bot>?start=…. Link có chữ ký nên không ai mạo nhận tài khoản người khác.
  2. Trang hiện nút Nhận thông báo qua Telegram mở link đó.
  3. Người dùng bấm Start. File *.telegram.ts nhận sự kiện kind: "link" có userId và chatId.
  4. Lưu chatId vào dòng người dùng. Từ đó app gửi tin cho họ bằng send(chatId, …).

Hàm nhận sự kiện

File export default một hàm async (e). Mỗi sự kiện có:

TrườngCó ởÝ nghĩa
kindmọi sự kiện"message", "button" hoặc "link"
chatIdmọi sự kiệncuộc trò chuyện để trả lời
frommọi sự kiện{ id, name, username } của người gửi trên Telegram
messageIdmọi sự kiệntin nhắn vừa đến, hoặc tin chứa nút vừa bấm
textmessage, linknội dung tin, hoặc chú thích của ảnh
databuttondata của nút được bấm
callbackIdbuttondùng với answerButton
userIdlinkid người dùng đã truyền vào linkUrl, dạng chuỗi
rawmọi sự kiệnbản cập nhật gốc của Telegram

Hàm trả một chuỗi thì chuỗi đó được gửi lại vào cuộc trò chuyện. Trả undefined thì không gửi gì. Nút bấm được trả lời tự động sau khi hàm chạy xong; gọi answerButton(e.callbackId, "Đã duyệt") nếu muốn hiện một thông báo nhỏ.

Gửi tin từ bất kỳ file server nào bằng manh/telegram: send(chatId, text, { buttons, parse, silent, replyTo }) trả { chatId, messageId }; edit(chatId, messageId, text, { buttons }) sửa tin đã gửi. buttons là mảng hàng, mỗi nút là { text, data } (data tối đa 64 ký tự) hoặc { text, url }.

Ví dụ

app/bot/bot.telegram.ts
import { saveChatId, userByChatId, approveOrder, pendingCount } from "./repository"; export default async function (e) { if (e.kind === "link") { await saveChatId(Number(e.userId), String(e.chatId)); return "Đã bật thông báo Telegram cho tài khoản của bạn."; } const user = await userByChatId(String(e.chatId)); if (!user) return "Bạn chưa liên kết tài khoản. Mở app, vào Hồ sơ và bấm Nhận thông báo qua Telegram."; if (e.kind === "button") { const [action, id] = e.data.split(":"); if (action === "approve") return approveOrder(user, Number(id)); // trả câu "Đã duyệt đơn #12" return; } if (e.text === "/don") return `Có ${await pendingCount(user)} đơn đang chờ duyệt.`; return "Lệnh có sẵn: /don"; }
app/orders/repository.ts
import { send } from "manh/telegram"; // … sau khi đã ghi đơn mới vào database: try { await send(manager.telegramChatId, `Đơn #${o.id} chờ duyệt: ${o.total.toLocaleString("vi-VN")} ₫`, { buttons: [[{ text: "Duyệt", data: `approve:${o.id}` }, { text: "Từ chối", data: `reject:${o.id}` }]], }); } catch (err) { if (err.blocked) await clearChatId(manager.id); // người nhận đã chặn bot }

Cần biết

  • Mỗi app một file *.telegram.ts. Deploy từ chối file thứ hai; rẽ nhánh theo e.kind và e.text trong cùng một hàm.
  • Không viết token của bot trong code. check báo code.telegram-token-literal.
  • Bấm nút là hành động của người đó: kiểm vai của user trước khi duyệt, như ở handler. data của nút đến từ Telegram, cần kiểm như input.
  • Một cập nhật chỉ đến hàm một lần, nhưng vẫn viết dữ liệu sao cho chạy hai lần không sai.
  • Hàm ném lỗi thì lỗi được ghi vào nhật ký, Telegram không gửi lại. Người dùng không nhận được gì nên hãy bắt lỗi và trả một câu dễ hiểu.
  • Hàm phải xong nhanh, dưới khoảng 30 giây. Việc chậm đẩy sang việc nền.
  • Gọi send sau khi ghi database, trong try/catch: thông báo lỗi không được làm hỏng việc chính. Người nhận chặn bot thì lỗi có err.blocked === true; xoá chatId đã lưu.
  • Telegram giới hạn khoảng 30 tin mỗi giây cho một bot và 1 tin mỗi giây cho một cuộc trò chuyện; send tự chờ rồi thử lại khi bị giới hạn. Tin dài hơn 4.096 ký tự bị cắt.
  • Thêm cột telegramChatId: text("telegram_chat_id") cho phép null vào bảng người dùng; thêm index nếu tra người dùng theo cột này.
  • Hàm không có người dùng đăng nhập, không đi qua middleware.ts hay access.

Bước tiếp theo

  • Bot Telegram của app — làm thông báo Telegram có nút duyệt từ đầu tới cuối.
  • std/telegram — send, edit, answerButton, linkUrl và lỗi có thể gặp.
Cập nhật