← Tất cả bài viết
Cẩm nang

Deep link Telegram Bot: xử lý tham số start và liên kết tài khoản

Deep link của Telegram Bot truyền tham số qua lệnh /start trong cuộc trò chuyện riêng. Bản thân liên kết không chứng minh tài khoản website và người dùng Telegram thuộc cùng một người. Hãy dùng tham số để tra cứu yêu cầu đang chờ trên máy chủ, đợi bot nhận cập nhật thực tế, rồi yêu cầu xác nhận rõ ràng trước khi hoàn tất liên kết tài khoản nhạy cảm. Mở URL chưa có nghĩa là đã hoàn tất.

Những điểm cần nhớ

  • Tham số khởi động dài tối đa 64 ký tự, gồm chữ cái Latin, chữ số, dấu gạch dưới và dấu gạch nối.
  • start dành cho trò chuyện riêng; startgroup thuộc luồng thêm bot vào nhóm riêng biệt.
  • Mã chiến dịch có thể công khai. Token liên kết tài khoản nên khó đoán, có thời hạn ngắn và chỉ dùng một lần.
  • Bắt đầu tương tác với bot khác với cấp quyền cho tài khoản nhắn tin Telegram hiện có.

Liên kết start thực sự gửi gì

Tài liệu tính năng bot của Telegram mô tả deep linking, bao gồm việc liên kết người dùng Telegram với tài khoản trên nền tảng khác. Cú pháp là https://t.me/<bot_username>?start=<parameter>. Giá trị trong ngoặc nhọn chỉ mô tả cú pháp, không phải bot đang hoạt động hay token dùng trong môi trường thật.

Đặc tả deep link cho ứng dụng khách mô tả nút Start gọi thao tác khởi động bot cùng tham số. Vì vậy, giao diện nên chuyển trạng thái dựa trên lệnh thực sự nhận được, không dựa vào lần nhấp trình duyệt hay giả định tin nhắn tự động được gửi. Bot nhận văn bản như /start airplane; ở đây dùng tham số ví dụ của Telegram.

Các ký tự được phép là A-Z, a-z, 0-9, _ và -, tối đa 64 ký tự. Telegram khuyến nghị base64url để biểu diễn dữ liệu nhị phân và các nội dung khác. Tuy nhiên, chuyển đổi định dạng không phải mã hóa bảo mật và không tạo ra độ tin cậy. Không đưa mật khẩu, bot token, API hash, email hoặc thông tin đăng nhập có thể tái sử dụng vào URL.

Luồng thêm vào nhóm được mô tả riêng bằng startgroup. Không coi lệnh trong nhóm là bằng chứng đã hoàn thành luồng liên kết tài khoản cá nhân.

Tách định tuyến khỏi xác minh danh tính

Mục đíchTham số đề xuấtĐiều việc nhận tham số chứng minh
Mở chủ đề trợ giúpMã chủ đề công khai nằm trong danh sách cho phépNgười dùng yêu cầu chủ đề đó
Ghi nhận nguồn chiến dịchMã chiến dịch công khaiNguồn truy cập, không phải danh tính đã xác minh
Liên kết tài khoản website đã đăng nhậpMã tham chiếu phía máy chủ không lộ nội dung, dùng một lầnMột liên kết đang chờ xác nhận

Người dùng có thể tự nhập lệnh hoặc chuyển tiếp URL. Vì vậy, mã khách hàng trong tham số không chứng minh người gửi sở hữu hồ sơ khách hàng đó. Ngay cả token khó đoán cũng có thể bị chuyển tiếp hoặc lộ; tính ngẫu nhiên không đủ để chứng minh đúng cặp tài khoản dự kiến.

Nếu chưa rõ ranh giới thông tin xác thực, hãy đọc so sánh Telegram API ID, API hash và bot token. Tham số khởi động là dữ liệu đầu vào của ứng dụng, không phải các loại thông tin xác thực này.

Luồng liên kết tài khoản được đề xuất

Các bước dưới đây là khuyến nghị thiết kế ứng dụng, không phải dịch vụ token do Telegram cung cấp hay endpoint mới của UnifyPort.

  1. Bắt đầu trong phiên website đã đăng nhập. Hiển thị tài khoản sẽ được liên kết và yêu cầu người dùng chủ động thao tác. Áp dụng các biện pháp bảo vệ phiên và chống giả mạo yêu cầu thông thường của website.
  2. Tạo yêu cầu chờ trên máy chủ. Sinh token ngẫu nhiên an toàn về mật mã và phù hợp với URL. Lưu giá trị băm, tài khoản website đích, bot đích, mục đích, hạn dùng và trạng thái chờ. Đây là dữ liệu nội bộ được đề xuất, không phải trường Telegram API. Chọn hạn dùng theo chính sách rủi ro; định dạng tham số Telegram không quy định tuổi thọ token của ứng dụng.
  3. Nhận và kiểm tra cập nhật thực tế. Xác thực đường nhận dữ liệu, chỉ chấp nhận tin nhắn riêng của bot dự kiến, phân tích chính xác lệnh /start, kiểm tra độ dài và tập ký tự. Dùng danh tính người gửi từ tin nhắn thay vì ID tự khai trong tham số. Tài liệu Bot API định nghĩa các đối tượng Update và Message.
  4. Ghi nhận người yêu cầu nhưng chưa cấp quyền. Liên kết nguyên tử yêu cầu đang chờ với người dùng Telegram quan sát được. Từ chối yêu cầu hết hạn hoặc người dùng khác gửi lại token đã được ghi nhận cho một người. Không tiết lộ chi tiết tài khoản website cho người gửi Telegram chưa được xác nhận.
  5. Xác nhận cặp tài khoản trong phiên website ban đầu. Hiển thị danh tính Telegram dự kiến và yêu cầu chủ tài khoản đã đăng nhập phê duyệt. Nếu không đúng người, hủy yêu cầu thay vì ghi đè liên kết hiện có. Với quy trình nhạy cảm, bổ sung bước xác nhận phù hợp trên Telegram.
  6. Hoàn tất một lần và giữ nhật ký kiểm toán tối thiểu. Việc tiêu thụ token cuối cùng và tạo liên kết phải nguyên tử. Cập nhật trùng hoặc nhấn Start lần nữa không được tạo thêm liên kết, chuyển liên kết hay cấp lại quyền lợi. Cung cấp thao tác hủy liên kết riêng, có xác thực.

Không đưa token gốc vào hệ thống phân tích, nhật ký, ảnh chụp màn hình hoặc phiếu hỗ trợ. Giới hạn tần suất thử không hợp lệ. Nếu không có xác nhận, để yêu cầu hết hạn mà không cấp quyền truy cập.

Tìm bước còn thiếu

Hiện tượngKiểm tra tiếp
Liên kết mở nhưng không có lệnhTên bot, thao tác Start và đường nhận cập nhật
Chỉ nhận /startHiển thị hướng dẫn thông thường; không đoán tài khoản từ dữ liệu thiếu
Tham số sai hoặc hết hạnYêu cầu tạo lại từ website đã đăng nhập
Cùng cập nhật đến lần nữaDùng kết quả đã lưu, không lặp lại liên kết
Người khác gửi token đã được ghi nhậnTừ chối và cung cấp luồng mới; không tự động chuyển liên kết
Bot nhận lệnh nhưng website vẫn chờKiểm tra trạng thái ghi nhận người yêu cầu và xác nhận trong ứng dụng

Về đường truyền, xem Bot API webhook so với webhook đầu vào hợp nhất. Chọn polling hay webhook không giải quyết thay việc xác nhận danh tính.

UnifyPort phù hợp ở đâu

Luồng bắt đầu này thuộc Telegram Bot chính thức. Trong khi đó, tài liệu cấp quyền Telegram của UnifyPort mô tả cách kết nối tài khoản hiện có qua giao diện không chính thức bằng mã xác minh, QR hoặc nhập phiên. Tham số khởi động bot không cấp quyền cho tài khoản đó và không thay thế sự phê duyệt của chủ tài khoản.

Nếu mục tiêu thực tế là nhận tin từ tài khoản nhắn tin hiện có, hãy dùng luồng cấp quyền này cùng sự kiện message.received. Đừng giả định deep link của bot sẽ xuất hiện trong hộp thư của tài khoản thông thường đã kết nối. Ngay cả khi bộ phận hỗ trợ cũng xử lý Zalo, WhatsApp hoặc LINE, liên kết danh tính vẫn cần được ứng dụng quản lý riêng.

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

Mở liên kết có hoàn tất liên kết tài khoản không?

Không. Cần đợi lệnh của bot và giao dịch xác nhận trong ứng dụng. Một lần nhấp không chứng minh đã nhận tin hay quyền sở hữu tài khoản.

Có thể đặt ID khách hàng trong start không?

Có thể dùng làm dữ liệu định tuyến không nhạy cảm, nhưng không được dùng để cấp quyền. Liên kết tài khoản cần mã tham chiếu ngẫu nhiên phía máy chủ và xác nhận rõ ràng.

base64url có bảo vệ bí mật không?

Không, đây chỉ là cách biểu diễn dữ liệu. Giữ thông tin nhạy cảm trên máy chủ và coi URL liên kết là dữ liệu nhạy cảm cho đến khi token được dùng hoặc hết hạn.

Đây có phải đăng nhập tài khoản người dùng Telegram không?

Không. Bắt đầu tương tác với bot không tạo phiên người dùng đã được cấp quyền. Chọn cách tích hợp theo danh tính mà ứng dụng cần sử dụng.

Bước tiếp theo và nguồn tham khảo

Bắt đầu với đặc tả deep link Telegram, rồi kiểm tra tham số thiếu, liên kết chuyển tiếp, hết hạn, cập nhật trùng, xung đột danh tính và hủy bỏ. Đây là các bài kiểm tra nghiệm thu đề xuất, không phải kết quả đã thực hiện.

Đối chiếu tài liệu chính thức ngày 2026-11-10:

UnifyPort API

Biến tích hợp nhắn tin thành một pipeline sản phẩm ổn định.

Bắt đầu bằng cách gửi qua một API, rồi đưa mọi tin nhắn inbound trở lại hệ thống kinh doanh bằng sự kiện chuẩn.