Giao diện

FAQ & Troubleshooting — Telegram Auth ​

Các câu hỏi thường gặp và cách xử lý sự cố khi sử dụng plugin Telegram Auth.

Bot không phản hồi / Login Widget không hiển thị ​

Triệu chứng: Nút Telegram Login không xuất hiện trên trang đăng nhập, hoặc click không có phản ứng.

Kiểm tra theo thứ tự:

  1. Bot username đúng chưa? — public.botUsername phải khớp chính xác username bot (không có @)
  2. Domain đã đăng ký chưa? — Gửi /setdomain cho BotFather và đăng ký domain Digiforce
  3. HTTPS chưa? — Telegram Login Widget yêu cầu trang web chạy trên HTTPS
  4. Authenticator đã bật chưa? — Kiểm tra authenticator đã enabled trong Settings

Test nhanh: Thử truy cập URL:

https://oauth.telegram.org/auth?bot_id={bot_id}&origin={your_domain}

Lỗi HMAC verify failed ​

Triệu chứng: Server trả 401 "Invalid Telegram auth data" hoặc "Invalid WebApp data".

Nguyên nhân phổ biến:

  1. Bot Token sai — telegram.botToken không khớp với bot đang dùng cho Login Widget
  2. Data bị modified — dữ liệu auth bị thay đổi trên đường truyền
  3. Sai thuật toán — Login Widget dùng SHA256(bot_token), Web App dùng HMAC("WebAppData", bot_token) — không được nhầm lẫn

Gỡ lỗi:

  • Kiểm tra bot token bằng cách gọi https://api.telegram.org/bot{token}/getMe
  • Nếu API trả về thông tin bot → token đúng
  • Nếu trả 401 → token sai hoặc bot đã bị xóa

Avatar không hiển thị ​

Triệu chứng: User đăng nhập qua Telegram nhưng avatar không được tải.

Lưu ý: Avatar chỉ được tải trong Web App flow (telegram:validate). Login Widget flow không tải avatar tự động.

Nếu dùng Web App mà vẫn không có avatar:

  1. User có avatar không? — Kiểm tra photo_url trong initData
  2. Server kết nối được Telegram API không? — Server cần truy cập api.telegram.org
  3. Storage writable? — Kiểm tra thư mục storage/uploads/ có quyền ghi
  4. Firewall? — Đảm bảo server cho phép outbound request đến api.telegram.org

Lỗi CORS khi gọi API ​

Triệu chứng: Console trình duyệt báo CORS error khi gọi telegram:redirect hoặc telegram:validate.

Kiểm tra:

  1. Plugin tự động bật CORS cho hai endpoint này — nếu vẫn lỗi, có thể reverse proxy đang override CORS headers
  2. Kiểm tra reverse proxy (nginx/Apache) không strip hoặc override header Access-Control-Allow-Origin
  3. Đảm bảo request URL đúng (không bị redirect 301/302 trước khi đến Digiforce)

Nginx example — đảm bảo không override CORS:

nginx
location /api/telegram: {
    proxy_pass http://digiforce_backend;
    # Không thêm add_header Access-Control-* ở đây
    # Plugin tự xử lý CORS
}

Web App: initData rỗng hoặc undefined ​

Triệu chứng: window.Telegram.WebApp.initData trả về string rỗng.

Nguyên nhân: Mini App không chạy trong context Telegram WebView — có thể đang test trên browser thông thường.

Giải pháp:

  • Chỉ có thể lấy initData khi chạy trong Telegram app
  • Để test, sử dụng Telegram Bot API test environment
  • Hoặc mock initData với HMAC tính từ bot token (chỉ dùng khi phát triển)

Đăng nhập Telegram có an toàn không? ​

HMAC verification đảm bảo:

  • Data đến từ Telegram server (vì chỉ Telegram biết bot token để tính hash)
  • Data không bị thay đổi trên đường truyền
  • auth_date cho phép reject data quá cũ

Lưu ý bảo mật:

  • Bot token phải được giữ bí mật — chỉ lưu server-side
  • Không log bot token hoặc expose qua API
  • public.botUsername an toàn để expose — chỉ là username public