Hướng dẫn August 24, 2026

Yêu cầu tham gia nhóm Telegram: Xây hàng đợi phê duyệt đáng tin cậy

Một hàng đợi duyệt thành viên Telegram đáng tin cậy không nên chỉ phụ thuộc vào sự kiện đẩy. Hãy định kỳ lấy danh sách yêu cầu đang chờ, dùng id của từng mục làm mã thành viên cho bước kiểm duyệt, rồi gửi rõ hành động approve hoặc reject. Webhook group.join_request có thể giúp giao diện cập nhật nhanh, nhưng tín hiệu này chỉ được chuyển theo cơ chế best-effort. Danh sách truy vấn mới là nguồn trạng thái chính xác.

Điểm chính

Bot API chính thức của Telegram có thể gửi cập nhật chat_join_request khi bot là quản trị viên và có quyền can_invite_users.
Trong UnifyPort, bật chế độ xét duyệt bằng group_id và enabled: true, sau đó lấy hàng đợi bằng chính group_id đó.
Khi phê duyệt hoặc từ chối, đưa id của các mục trả về vào member_ids.
Chỉ dùng group.join_request như tín hiệu độ trễ thấp; luôn đối soát bằng danh sách yêu cầu đang chờ.
Duy trì bước quyết định của con người trừ khi quy tắc tiếp nhận rất hẹp, rõ ràng và có thể kiểm tra.

Chọn mô hình danh tính trước khi viết hàng đợi

Nếu danh tính bot phù hợp, Bot API chính thức của Telegram đã cung cấp ChatJoinRequest, approveChatJoinRequest và declineChatJoinRequest. Bot phải là quản trị viên nhóm và có quyền can_invite_users. Đây là lựa chọn trực tiếp khi nhóm được thiết kế để bot quản lý và quy trình chỉ dành cho Telegram.

Nếu việc xét duyệt phải diễn ra qua tài khoản Telegram hiện có, hoặc đội ngũ tại Việt Nam muốn dùng cùng kiểu tích hợp cho Zalo, WhatsApp và các kênh khác, bạn có thể dùng UnifyPort messaging account đã kết nối. Trước khi chọn, hãy xem khác biệt giữa Telegram API ID, API Hash và Bot Token.

Đừng trộn lẫn các mô hình này. Bot Token đại diện cho bot. API ID và API Hash nhận diện ứng dụng Telegram client. UnifyPort messaging account đại diện cho tài khoản đã kết nối mà API sẽ thay mặt thực hiện hành động.

Xây hàng đợi phê duyệt yêu cầu vào nhóm Telegram

1. Bật chế độ xét duyệt thành viên

Nhóm phải yêu cầu phê duyệt trước khi có hàng đợi đang chờ. Gọi endpoint chế độ xét duyệt với account ID đã kết nối, group_id đích và giá trị boolean enabled:

curl -X POST \
  "https://api.unifyport.ai/v1/accounts/<ACCOUNT_ID>/groups/join-approval-mode" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "group_example",
    "enabled": true
  }'

Thao tác này yêu cầu quyền quản trị viên trong nhóm. Hãy tách cấu hình quản trị này khỏi worker kiểm duyệt chạy định kỳ; worker không cần đổi chính sách nhóm mỗi lần chạy. Xem hợp đồng yêu cầu hiện tại tại Set group join approval mode.

2. Định kỳ lấy danh sách làm nguồn dữ liệu chính

Truyền group_id dưới dạng query parameter:

curl \
  "https://api.unifyport.ai/v1/accounts/<ACCOUNT_ID>/groups/join-requests?group_id=group_example" \
  -H "X-Api-Key: <YOUR_API_KEY>"

Chỉ lưu trạng thái mà ứng dụng thật sự cần: request ID, nhóm đích, trạng thái quyết định, người kiểm duyệt và thời gian nội bộ. Đừng giả định webhook tương ứng chắc chắn đã đến trước khi một mục xuất hiện trong phản hồi này.

Quan hệ giữa các trường rất đơn giản: mỗi mục từ List group join requests có một id; dùng giá trị đó trong member_ids của lệnh cập nhật. Không thay bằng tên hiển thị và không tự đoán mã Telegram.

3. Làm cho quyết định trở nên rõ ràng

Nên có ít nhất bốn trạng thái nội bộ:

Trạng thái	Ý nghĩa	Bước tiếp theo
`pending`	Vẫn tồn tại ở nguồn và chưa được duyệt	Hiển thị cho quản trị viên
`approved`	Người kiểm duyệt đồng ý	Gửi `approve`
`rejected`	Người kiểm duyệt từ chối	Gửi `reject`
`stale`	Không còn xuất hiện khi đối soát	Đóng mà không gửi thêm

Đội ngũ có thể dùng câu trả lời thu thập bên ngoài Telegram, allowlist hoặc kiểm tra thủ công. Hãy ghi rõ đó là quy tắc của ứng dụng, không phải trường của Telegram hay UnifyPort. Không tự động chấp nhận chỉ dựa trên tên hồ sơ hoặc phần giới thiệu không đáng tin cậy.

4. Phê duyệt hoặc từ chối theo lô

Gửi một hoặc nhiều ID đã nhận, cùng nhóm đích và hành động rõ ràng:

curl -X POST \
  "https://api.unifyport.ai/v1/accounts/<ACCOUNT_ID>/groups/join-requests/update" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "group_example",
    "action": "approve",
    "member_ids": ["member_example", "member_other"]
  }'

Để từ chối, giữ nguyên cấu trúc và dùng "action": "reject". Endpoint này cũng yêu cầu quyền quản trị viên nhóm. Hãy đọc Approve or reject join requests trước khi thiết kế retry hoặc kích thước lô.

Sau mỗi lần cập nhật, hãy lấy lại danh sách. Việc này đưa giao diện nội bộ về đúng trạng thái hiện tại của nguồn, kể cả khi hai quản trị viên thao tác gần như cùng lúc.

5. Dùng `group.join_request` để đánh thức worker, không thay việc truy vấn

Nếu muốn giao diện kiểm duyệt làm mới nhanh, hãy đăng ký group.join_request cho webhook endpoint. Sự kiện cho biết có người xin vào nhóm đang bật xét duyệt, nhưng việc chuyển sự kiện là best-effort. Luồng an toàn là:

nhận sự kiện;
xác minh và phản hồi webhook;
đưa một tác vụ làm mới vào hàng đợi;
gọi endpoint danh sách;
hiển thị quyết định dựa trên danh sách đang chờ được trả về.

Push giảm độ trễ, còn đối soát khôi phục trạng thái đúng. Khi xây receiver, hãy kết hợp với hướng dẫn bảo vệ webhook HMAC trước replay và xử lý retry.

Tách yêu cầu tham gia khỏi thay đổi thành viên

Yêu cầu tham gia không đồng nghĩa thành viên đã được thêm. Khi nhận group.join_request, đừng đánh dấu người xin vào là thành viên ngay. Hãy phê duyệt, đối soát, rồi xử lý thay đổi thành viên sau đó bằng luồng sự kiện riêng.

Trong audit log, “xin tham gia”, “quản trị viên phê duyệt” và “được thêm vào nhóm” là ba sự kiện khác nhau. Với phần sau phê duyệt, xem hướng dẫn về sự kiện thêm và xóa thành viên trong Telegram Communities.

Checklist trước khi chạy production

Xác nhận danh tính đã kết nối có quyền quản trị viên nhóm.
Chỉ lưu X-Api-Key dưới dạng secret phía server.
Bật chế độ phê duyệt như một thao tác quản trị riêng.
Định kỳ lấy danh sách đang chờ ngay cả khi không có webhook.
Chỉ dùng request id trả về từ danh sách trong member_ids.
Ghi người kiểm duyệt và lý do quyết định vào audit log riêng.
Lấy lại danh sách sau mỗi thao tác phê duyệt hoặc từ chối.
Xác minh chữ ký webhook trước khi dùng sự kiện làm tín hiệu làm mới.
Không xem sự kiện yêu cầu tham gia là bằng chứng thành viên đã thay đổi.

Giới hạn và đánh đổi

Dùng Bot API chính thức khi bot quản trị viên là danh tính mong muốn và quy trình chỉ dành cho Telegram. Đây là phương án trực tiếp, có tài liệu chính thức và phương thức riêng để phê duyệt hoặc từ chối.

Dùng unofficial interface của UnifyPort khi danh tính tài khoản hiện có hoặc một mẫu API chung cho Telegram, Zalo và WhatsApp quan trọng hơn. Bạn vẫn cần quyền quản trị viên, chính sách kiểm duyệt rõ ràng, quản lý API Key an toàn và bước đối soát. Giao diện không quyết định nhóm nên tin ai; việc chuyển event theo best-effort cũng có nghĩa phải duy trì luồng truy vấn.

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

Bot Telegram có thể phê duyệt yêu cầu vào nhóm không?

Có. Bot API chính thức cung cấp phương thức phê duyệt và từ chối. Bot phải là quản trị viên nhóm và có quyền can_invite_users.

Có nên chỉ xử lý webhook `group.join_request` không?

Không. Hãy dùng nó như thông báo nhanh rồi lấy danh sách đang chờ. Tài liệu UnifyPort nêu rõ tín hiệu push này là best-effort và truy vấn danh sách là nguồn đáng tin cậy.

Điền gì vào `member_ids`?

Dùng id của từng mục do endpoint danh sách trả về. Không suy ra từ tên hiển thị.

Có thể phê duyệt nhiều yêu cầu trong một lần gọi không?

Có. Endpoint cập nhật nhận một hoặc nhiều giá trị member_ids và action là approve hoặc reject.

Cần làm gì sau lệnh phê duyệt?

Lấy lại danh sách đang chờ, cập nhật hàng đợi nội bộ và xử lý thay đổi thành viên sau đó tách biệt với yêu cầu ban đầu.

Bước tiếp theo

Bắt đầu với API Reference về danh sách yêu cầu vào nhóm, sau đó xây endpoint chế độ xét duyệt và cập nhật quanh vòng lặp đối soát đó.

Nguồn

Đã kiểm tra ngày 24 tháng 8 năm 2026:

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.

Lấy API Key Xem tham chiếu API