*.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 botDù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
- Chủ app tạo bot bằng @BotFather trong Telegram.
- 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.
- 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:
- 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. - Trang hiện nút Nhận thông báo qua Telegram mở link đó.
- Người dùng bấm Start. File
*.telegram.tsnhận sự kiệnkind: "link"cóuserIdvàchatId. - Lưu
chatIdvào dòng người dùng. Từ đó app gửi tin cho họ bằngsend(chatId, …).
Hàm nhận sự kiện
File export default một hàm async (e). Mỗi sự kiện có:
| Trường | Có ở | Ý nghĩa |
|---|---|---|
kind | mọi sự kiện | "message", "button" hoặc "link" |
chatId | mọi sự kiện | cuộc trò chuyện để trả lời |
from | mọi sự kiện | { id, name, username } của người gửi trên Telegram |
messageId | mọi sự kiện | tin nhắn vừa đến, hoặc tin chứa nút vừa bấm |
text | message, link | nội dung tin, hoặc chú thích của ảnh |
data | button | data của nút được bấm |
callbackId | button | dùng với answerButton |
userId | link | id người dùng đã truyền vào linkUrl, dạng chuỗi |
raw | mọi sự kiện | bả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ụ
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";
}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 theoe.kindvàe.texttrong cùng một hàm. - Không viết token của bot trong code.
checkbáocode.telegram-token-literal. - Bấm nút là hành động của người đó: kiểm vai của
usertrước khi duyệt, như ở handler.datacủ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
sendsau khi ghi database, trongtry/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;
sendtự 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.tshayaccess.
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,linkUrlvà lỗi có thể gặp.