Phát triển Telegram Bot & Mini App chỉ với một dự án Next.js

Bài viết này sẽ giới thiệu một hướng tiếp cận phát triển hoàn toàn mới: sử dụng một dự án Next.js duy nhất để triển khai đồng thời cả Telegram Bot và Mini App, thực sự đạt được một bộ mã nguồn, một lần triển khai, tích hợp liền mạch. Bạn sẽ học cách xây dựng một hệ thống trò chơi ghi điểm hoàn chỉnh, bao gồm phần thưởng điểm danh hàng ngày, thanh toán bằng Telegram Stars thật và chức năng thông báo theo thời gian thực.

Tại sao chọn Next.js để thống nhất phát triển Bot và Mini App?

Ở mô hình truyền thống, nhà phát triển cần:

• Triển khai riêng biệt dịch vụ backend cho Bot
• Triển khai riêng biệt ứng dụng frontend cho Mini App
• Thực hiện kết nối dữ liệu giữa hai dự án
• Bảo trì hai bộ biến môi trường và cấu hình

Với giải pháp tích hợp của Next.js, bạn có thể:

• Một kho mã nguồn quản lý tất cả chức năng
• Chia sẻ API routes để xử lý lệnh Bot, yêu cầu Mini App và logic thanh toán
• Triển khai thống nhất trên các nền tảng như Vercel, giảm chi phí vận hành
• Dữ liệu được kết nối tự nhiên, không cần cơ chế đồng bộ bổ sung

Cách tiếp cận này đặc biệt phù hợp để nhanh chóng kiểm tra ý tưởng, phát triển sản phẩm MVP hoặc để các nhà phát triển độc lập nhanh chóng ra mắt dự án.

---

Trình diễn chức năng cốt lõi: Dự án này có thể làm gì?

Chúng ta sẽ xây dựng một hệ thống trò chơi ghi điểm, với các chức năng sau:

• Phần thưởng điểm danh hàng ngày: Người dùng có thể nhận 100 điểm mỗi 24 giờ, có hiển thị đồng hồ đếm ngược thời gian thực.
• Thanh toán bằng Telegram Stars: Người dùng mua điểm bằng tiền thật, hỗ trợ kiểm tra hoàn tiền tức thì.
• Xử lý lệnh Bot: Hỗ trợ các lệnh phổ biến như /start, /help, khởi chạy Mini App chỉ bằng một cú nhấp chuột.
• Đẩy thông báo thời gian thực: Các giao dịch như thanh toán thành công, hoàn tiền hoàn tất sẽ được gửi thông báo qua Bot.

Toàn bộ hệ thống chạy trong một ứng dụng Next.js, tương tác giữa Bot và Mini App hoàn toàn liền mạch.

---

Chuẩn bị trước khi bắt đầu

Trước khi bắt đầu phát triển, bạn cần chuẩn bị các công cụ sau:

1. Tài khoản Telegram: Để tạo Bot và kiểm thử Mini App.
2. Node.js 18+: Nếu chưa cài đặt, truy cập nodejs.org để tải về.
3. Ngrok: Để tạo đường hầm HTTPS khi phát triển cục bộ, vì Telegram yêu cầu Webhook và Mini App phải sử dụng HTTPS.

Cách lấy Ngrok

• Truy cập ngrok.com để đăng ký tài khoản miễn phí.
• Tải phiên bản phù hợp với hệ điều hành của bạn.
• Giải nén vào một thư mục riêng.
• Chạy lệnh ngrok config add-authtoken <mã token của bạn> để liên kết tài khoản.
• Sau khi hoàn tất, bạn có thể chạy lệnh ngrok http 3000 bất cứ lúc nào trong thư mục đó.

---

Thiết lập dự án nhanh chóng (Sử dụng trong 5 phút)

1. Lấy mã nguồn dự án và cài đặt phụ thuộc

Bạn có thể lấy mã nguồn đầy đủ và tài liệu chi tiết từ các kênh Telegram liên quan (liên kết cụ thể có thể tìm thấy trong mô tả video gốc).

git clone <Địa chỉ kho mã nguồn dự án>
cd <Thư mục dự án>
npm install

2. Cấu hình biến môi trường

Tạo tệp .env.local trong thư mục gốc của dự án để lưu trữ thông tin nhạy cảm:

TELEGRAM_BOT_TOKEN=Mã token Bot của bạn
NEXT_PUBLIC_APP_URL=Địa chỉ Ngrok của bạn

Lưu ý quan trọng: Đảm bảo .env.local đã được thêm vào .gitignore để tránh lộ thông tin Token Bot.

3. Tạo Telegram Bot

• Mở Telegram, tìm kiếm BotFather.
• Gửi lệnh /newbot để tạo Bot mới.
• Đặt tên và tên người dùng cho Bot (tên người dùng phải kết thúc bằng bot).
• Sao chép Bot Token được tạo ra và lưu vào .env.local.

4. Khởi chạy Ngrok và máy chủ phát triển

# Terminal 1: Khởi chạy Ngrok
ngrok http 3000

# Terminal 2: Khởi chạy máy chủ phát triển Next.js
npm run dev

# Terminal 3: Thiết lập Webhook
npm run webhook:setup

Nếu mọi thứ diễn ra suôn sẻ, bạn sẽ thấy thông báo "Webhook set successfully".

5. Cấu hình nút menu Mini App

• Quay lại BotFather, gửi lệnh /mybots và chọn Bot của bạn.
• Nhấp vào Bot Settings → Menu Button.
• Nhập URL (sử dụng địa chỉ HTTPS do Ngrok cung cấp) và văn bản nút (ví dụ: "Play Game").

Bây giờ, khi người dùng mở Bot của bạn, họ sẽ thấy một nút để khởi chạy trò chơi, nhấp vào đó sẽ mở giao diện Mini App!

---

Phân tích mã nguồn cốt lõi: Bot và Mini App phối hợp hoạt động như thế nào?

Điểm cuối Webhook: Trung tâm xử lý tin nhắn của Bot

Tất cả các cập nhật được gửi từ Telegram (lệnh người dùng, phản hồi thanh toán, v.v.) sẽ được chuyển đến lộ trình /api/telegram/webhook thông qua Webhook.

Các loại tin nhắn chính được xử lý bao gồm:

• Lệnh người dùng: /start, /help, v.v.
• Xác nhận trước thanh toán: Kiểm tra trước khi người dùng nhấp vào nút thanh toán.
• Phản hồi thanh toán thành công: Xác nhận giao dịch hoàn tất và phát hành điểm.
• Yêu cầu hoàn tiền: Có thể kiểm tra nhanh quy trình hoàn tiền trong giai đoạn phát triển.

Khi người dùng gửi lệnh /start lần đầu, Bot sẽ ngay lập tức gửi một nút "Khởi chạy trò chơi", không cần hướng dẫn thêm.

Quy trình thanh toán Telegram Stars

Chức năng thanh toán cốt lõi nằm ở lộ trình /api/buy-points:

1. Người dùng nhấp vào "Mua điểm" trong Mini App.
2. Gọi Telegram Bot API để tạo hóa đơn (createInvoiceLink).
3. Hóa đơn hiển thị trong giao diện thanh toán gốc của Telegram.
4. Sau khi người dùng hoàn tất thanh toán, Webhook nhận được thông báo.
5. Hệ thống cập nhật điểm cho người dùng và gửi tin nhắn biên nhận.

Cấu hình quan trọng:

• provider_token để trống (chế độ Telegram Stars).
• currency đặt thành XTR.
• Đơn vị của prices là số lượng sao (không phải xu).

Lợi ích cho nhà phát triển: Mỗi lần mua sẽ trả về ID biên nhận, bạn có thể ngay lập tức sử dụng lệnh /refund <ID biên nhận> để kiểm tra hoàn tiền mà không cần chờ phê duyệt hoặc xử lý thủ công. Điều này cực kỳ hiệu quả để kiểm tra quy trình thanh toán thực tế.

Hệ thống phần thưởng điểm danh hàng ngày

Trong lộ trình /api/claim-daily, chúng ta đã triển khai cơ chế khuyến khích dựa trên thời gian:

• Ghi lại thời gian nhận cuối cùng của mỗi người dùng.
• Kiểm tra xem đã qua 24 giờ hay chưa.
• Nếu chưa đủ 24 giờ, trả về thời gian còn lại để đếm ngược.
• Phát 100 điểm khi nhận thành công và gửi thông báo Telegram.

Giao diện người dùng sử dụng thành phần đếm ngược thời gian thực, cập nhật thời gian còn lại mỗi giây, giúp người dùng biết rõ khi nào có thể nhận thưởng lại. Mô hình này có thể mở rộng cho bất kỳ lối chơi nào yêu cầu giới hạn thời gian (như hồi năng lượng, làm mới lượt quay, v.v.).

---

Những lưu ý khi triển khai môi trường sản xuất

Mặc dù bài viết này sử dụng bộ nhớ để lưu trữ cho mục đích demo, nhưng bạn phải thực hiện các thay đổi sau trước khi triển khai dự án thực tế:

• Cơ sở dữ liệu: Sử dụng PostgreSQL hoặc MongoDB thay thế cho lưu trữ trong bộ nhớ.
• Xác thực người dùng: Xác minh chữ ký dữ liệu của Telegram Web App để ngăn chặn yêu cầu giả mạo.
• Bảo vệ giới hạn tỷ lệ: Ngăn chặn việc lạm dụng rút điểm hoặc các giao diện thanh toán.
• Giám sát nhật ký: Tích hợp dịch vụ theo dõi lỗi (như Sentry).
• Bảo mật Webhook: Xác minh rằng yêu cầu đến thực sự từ máy chủ Telegram.

Nền tảng triển khai được đề xuất:

• Vercel: Triển khai không cần cấu hình, tự động HTTPS.
• Heroku / Railway: Phù hợp cho các tình huống yêu cầu kết nối dài.
• Cloudflare Workers: Giải pháp điện toán biên, tăng tốc toàn cầu.

Khi triển khai, đừng quên cập nhật URL Webhook và liên kết menu Mini App với tên miền sản xuất của bạn.

---

Câu hỏi thường gặp (FAQ)

Tại sao cần Ngrok? Có thể dùng localhost trực tiếp không?

Webhook và Mini App của Telegram đều yêu cầu sử dụng giao thức HTTPS, localhost không thể đáp ứng yêu cầu này. Ngrok có thể tạo một đường hầm HTTPS có thể truy cập từ mạng công cộng, chuyển tiếp yêu cầu đến máy chủ phát triển cục bộ của bạn.

Làm thế nào để kiểm tra thanh toán thực tế mà không tốn tiền?

Trong giai đoạn phát triển, bạn có thể mua một lượng nhỏ Telegram Stars (tối thiểu vài xu) và sau đó sử dụng lệnh /refund để hoàn tiền ngay lập tức. Điều này cho phép bạn kiểm tra quy trình thanh toán, phản hồi Webhook và logic hoàn tiền bằng quy trình thực tế mà không cần nạp tiền nhiều lần.

Môi trường sản xuất có thể tiếp tục sử dụng lưu trữ trong bộ nhớ không?

Tuyệt đối không. Lưu trữ trong bộ nhớ sẽ làm mất tất cả dữ liệu sau khi máy chủ khởi động lại. Bạn phải sử dụng cơ sở dữ liệu bền vững (như PostgreSQL) và chuẩn bị kế hoạch sao lưu và di chuyển dữ liệu.

Lợi ích chính của giải pháp tích hợp Next.js là gì?

Lợi ích lớn nhất là tăng hiệu quả phát triển và giảm chi phí bảo trì. Bạn không cần:

• Quản lý hai kho mã nguồn.
• Lo lắng về sự không nhất quán dữ liệu giữa frontend và backend.
• Cấu hình các kết nối chéo miền và API phức tạp.
• Triển khai và giám sát hai dịch vụ riêng biệt.

Tất cả logic nằm trong một dự án, tỷ lệ tái sử dụng mã cao, định vị lỗi nhanh hơn.

Kiến trúc này có phù hợp cho ứng dụng quy mô lớn không?

Đối với sản phẩm MVP và các ứng dụng vừa và nhỏ, hoàn toàn đủ. Nếu số lượng người dùng hoạt động hàng ngày đạt hàng triệu, nên cân nhắc tách backend Bot và frontend Mini App, sử dụng kiến trúc microservices và hàng đợi tin nhắn chuyên dụng để xử lý lưu lượng truy cập cao.

---

Tóm tắt

Thông qua buổi thực hành trong bài viết này, bạn đã nắm vững các kỹ năng cốt lõi để xây dựng ứng dụng tích hợp Telegram Bot và Mini App bằng Next.js. Mô hình phát triển này có thể giúp bạn nhanh chóng kiểm tra ý tưởng, giảm chi phí phát triển và tạo nền tảng vững chắc cho việc mở rộng sau này. Hãy bắt tay vào thử nghiệm ngay để tạo ra trò chơi Telegram của riêng bạn trong thời gian ngắn nhất!