Docs

Telegram Mini App — Hướng dẫn từng bước

Nó là gì?

Telegram Mini App cho phép khách hàng của bạn mở thực đơn nhà hàng kỹ thuật số trực tiếp trong Telegram — không cần cài đặt ứng dụng và không cần chuyển sang trình duyệt. Thực đơn trông giống như một phần tự nhiên của Telegram: điều chỉnh theo chủ đề của người dùng, hỗ trợ nút "Quay lại" và cử chỉ.

Lợi ích

  • 📱 Trong Telegram — khách hàng không cần chuyển sang trình duyệt
  • 🎨 Giao diện tự nhiên — màu sắc, phông chữ và chủ đề điều chỉnh theo Telegram
  • 🔗 Deep Links — liên kết trực tiếp đến thực đơn của nhà hàng cụ thể
  • 🌍 Ngôn ngữ tự động — ngôn ngữ được lấy từ cài đặt Telegram của người dùng
  • 🍪 Không cookies — biểu ngữ cookie không hiển thị trong Telegram

Bắt đầu nhanh

Bước 1 — Tạo bot

Mở @BotFather trong Telegram và gửi:

/newbot
  1. Nhập tên bot (ví dụ, Meni Menu Bot)
  2. Nhập username (ví dụ, MeniMenuBot) — phải kết thúc bằng Bot
  3. Lưu Bot Token nhận được (định dạng: 123456789:ABCdefGHI...)

💡 Nếu bot đã được tạo, chuyển sang Bước 2.

Tại sao cần Bot Token?

Bot Token là khóa bí mật để quản lý bot thông qua Telegram Bot API. Đối với cài đặt cơ bản của Mini App (bước 2–4) nó không cần thiết — mọi thứ được thực hiện qua BotFather. Nhưng nó sẽ cần thiết nếu bạn muốn:

  • Gửi tin nhắn cho khách hàng — thông báo về trạng thái đơn hàng, khuyến mãi, tin nhắn chào mừng
  • Thêm nút inline vào tin nhắn bot (ví dụ, nút "📋 Mở thực đơn" — xem phần dưới)
  • Tạo bot Telegram để nhận đơn hàng — bot có thể nhận và xử lý đơn hàng
  • Cài đặt Webhook — nhận sự kiện từ Telegram (nhấn nút, lệnh của người dùng)
  • Tích hợp với hệ thống CRM hoặc POS — xử lý đơn hàng tự động qua bot

🔒 Không công khai Bot Token — bất kỳ ai có token đều có thể quản lý bot của bạn. Nếu token bị lộ, thu hồi nó bằng lệnh /revoke trong BotFather.

Bước 2 — Tạo Mini App

Gửi lệnh BotFather:

/newapp
  1. Chọn bot từ danh sách
  2. Title — tên ứng dụng (ví dụ, Meni)
  3. Description — mô tả (ví dụ, Thực đơn nhà hàng kỹ thuật số)
  4. Photo — tải lên hình ảnh 640×640 px (biểu tượng ứng dụng)
  5. GIF — hoạt hình (không bắt buộc). Để bỏ qua, gửi /empty
  6. Web App URL — chỉ định địa chỉ ứng dụng khách của bạn:
https://meni.ge
  1. Short Name — tên ngắn cho liên kết (ví dụ, menu)

Sau đó, bạn sẽ có một liên kết hoạt động dạng:

https://t.me/YourBot/menu

Bước 3 — Thêm nút "Thực đơn" vào chat bot

Gửi BotFather:

/setmenubutton
  1. Chọn bot
  2. Gửi URL:
https://meni.ge
  1. Nhập văn bản nút (ví dụ, Open Menu hoặc 📋 Thực đơn)

Bây giờ khi mở chat với bot, nút sẽ xuất hiện ở dưới cùng màn hình mở ứng dụng của bạn.

Bước 4 — Cho phép tên miền

Gửi BotFather:

/setdomain

Chọn bot và chỉ định tên miền:

meni.ge

Điều này cho phép Telegram Web App hoạt động trên tên miền của bạn và tất cả các tên miền phụ của nó (ví dụ, locationid.meni.ge).

Deep Links — liên kết đến nhà hàng cụ thể

Telegram hỗ trợ tham số startapp, được truyền vào ứng dụng khi mở. Sử dụng nó cho liên kết đến nhà hàng cụ thể:

Liên kết Mở cái gì
t.me/YourBot/menu Trang chính
t.me/YourBot/menu?startapp=LOCATION_ID Thực đơn của nhà hàng cụ thể
t.me/YourBot/menu?startapp=LOCATION_ID__ru Thực đơn bằng tiếng Nga
t.me/YourBot/menu?startapp=LOCATION_ID__en Thực đơn bằng tiếng Anh

Ví dụ

Nếu LOCATION_ID của nhà hàng của bạn là lnc2w74z:

https://t.me/YourBot/menu?startapp=lnc2w74z
https://t.me/YourBot/menu?startapp=lnc2w74z__ru
https://t.me/YourBot/menu?startapp=lnc2w74z__en

📌 LOCATION_ID — là định danh của vị trí của bạn trong meni.ge. Bạn có thể tìm thấy nó trong bảng điều khiển quản trị hoặc trong URL dạng https://LOCATION_ID.meni.ge.

Nút inline từ bot

Nếu bot của bạn gửi tin nhắn cho khách hàng, bạn có thể thêm nút inline mở thực đơn:

Phương án 1 — Nút Web App (mở ngay lập tức)

{
  "inline_keyboard": [[{
    "text": "📋 Mở thực đơn",
    "web_app": {
      "url": "https://LOCATION_ID.meni.ge/ru"
    }
  }]]
}

Phương án 2 — Nút Deep Link

{
  "inline_keyboard": [[{
    "text": "📋 Mở thực đơn",
    "url": "https://t.me/YourBot/menu?startapp=LOCATION_ID__ru"
  }]]
}

Những gì hoạt động tự động

Sau khi kết nối trong Telegram, các tính năng sau tự động kích hoạt:

Chức năng Mô tả
🎨 Chủ đề Màu sắc ứng dụng điều chỉnh theo chủ đề Telegram (sáng/tối)
◀️ Nút "Quay lại" Nút tự nhiên của Telegram xuất hiện khi mở thẻ sản phẩm
📏 Viewport Ứng dụng mở rộng toàn màn hình
🔒 Bảo vệ khỏi đóng Vuốt dọc không đóng ứng dụng một cách tình cờ
🌍 Ngôn ngữ tự động Ngôn ngữ được xác định từ hồ sơ Telegram, nếu không được chỉ định rõ ràng
🍪 Cookies Biểu ngữ cookie không hiển thị trong Telegram

Mã QR cho nhà hàng

Các mã QR hiện có với URL dạng https://lnc2w74z.meni.ge sẽ tiếp tục hoạt động như bình thường — qua trình duyệt.

Để tích hợp thêm với Telegram, bạn có thể đặt mã QR thứ hai trên bàn với liên kết đến bot:

https://t.me/YourBot/menu?startapp=lnc2w74z

Kiểm tra hoạt động

  1. Mở liên kết https://t.me/YourBot/menu trên điện thoại
  2. Nhấn Start (nếu mở bot lần đầu)
  3. Nhấn nút 📋 Thực đơn ở thanh dưới cùng của chat
  4. Đảm bảo ứng dụng mở và tải thực đơn
  5. Thử mở deep link: https://t.me/YourBot/menu?startapp=LOCATION_ID

Các vấn đề thường gặp

Vấn đề Giải pháp
Ứng dụng không mở Kiểm tra rằng tên miền meni.ge đã được cho phép qua /setdomain
Màn hình trắng Đảm bảo rằng Web App URL được chỉ định là https://meni.ge (HTTPS bắt buộc)
startapp không hoạt động Kiểm tra định dạng: LOCATION_ID (không có khoảng trắng, ký tự đặc biệt). Phân cách cho ngôn ngữ là hai dấu gạch dưới __
Chủ đề không áp dụng Telegram Mini App SDK phải được kết nối (cập nhật ứng dụng khách)

Liên kết hữu ích