Xây hàng đợi duyệt yêu cầu vào nhóm WhatsApp bằng UnifyPort

Nếu muốn tự động hóa yêu cầu vào nhóm WhatsApp, đừng xem webhook là nguồn trạng thái duy nhất. Hãy tách vai trò: cài đặt nhóm trong WhatsApp quyết định thành viên mới có cần được duyệt hay không; UnifyPort gửi group.join_request như một tín hiệu nhanh, backend của bạn đọc danh sách đáng tin cậy bằng GET /v1/accounts/{account_id}/groups/join-requests, rồi dùng POST /v1/accounts/{account_id}/groups/join-requests/update để approve hoặc reject từng requester.

Tóm tắt chính

• Help Center chính thức của WhatsApp cho biết Approve new members mặc định đang tắt. Khi bật, admin nhóm phải duyệt người muốn tham gia.
• group.join_request phù hợp để đánh thức worker, không nên là database duy nhất. Tài liệu UnifyPort khuyến nghị poll List group join requests làm nguồn trạng thái đáng tin cậy.
• Trước khi duyệt, hãy lưu account_id, group id, requester id, request method nếu có, và quyết định moderation của đội.
• Với đội hỗ trợ ở Việt Nam, WhatsApp và Zalo thường cùng tồn tại. Nguyên tắc trong Webhook-First Inbound Integration Checklist vẫn giống nhau: verify, store, then route.

WhatsApp vẫn kiểm soát phần nào

Duyệt thành viên mới là tính năng dành cho admin nhóm WhatsApp. Trang Help Center chính thức How to approve new members as a group admin giải thích rằng khi Approve new members được bật, admin phải approve người muốn vào nhóm; cài đặt này mặc định đang tắt.

Vì vậy backend của bạn không thay thế cài đặt của WhatsApp. Backend nên trả lời các câu hỏi vận hành: ai cần xem yêu cầu, họ cần thấy dữ liệu gì, và requester id nào sẽ được approve hoặc reject.

Kiến trúc hàng đợi

Dùng một webhook endpoint có chữ ký để nhận tín hiệu nhóm, rồi reconcile với API danh sách pending:

1. Tạo webhook endpoint và thêm group.join_request vào subscribed_events; nếu bạn đã thu thập mọi public event, có thể dùng ["*"]. Cách chọn filter được giải thích trong UnifyPort Webhook Event Filters.
2. Khi nhận group.join_request, tạo reconciliation job theo account_id và data.conversation.id.
3. Gọi List group join requests cho nhóm đó. Trường id của item trả về chính là giá trị cần truyền vào member_ids.
4. Hiển thị danh sách cho moderator, hoặc áp dụng rule nội bộ.
5. Gọi update endpoint với action: "approve" hoặc action: "reject".

Nếu bạn từng xây hàng đợi duyệt yêu cầu vào nhóm Telegram, bài học vận hành giống nhau: push event đánh thức hệ thống, còn list API là trạng thái cần tin cậy.

Ví dụ event và request

Một yêu cầu vào nhóm WhatsApp có thể đến dưới dạng event chuẩn hóa như sau:

{
  "id": "evt_gjr_5e1c8a3f9b",
  "type": "group.join_request",
  "provider": "whatsapp",
  "account_id": "acc_8c21d0",
  "occurred_at": "2026-06-08T13:10:30Z",
  "data": {
    "conversation": { "id": "120363041234567890@g.us", "type": "group" },
    "requester": { "id": "8613912345678@lid", "type": "user" },
    "request_method": "invite_link",
    "event": { "kind": "group_join_request" }
  }
}

Trước khi duyệt, hãy đọc lại danh sách:

curl "https://api.unifyport.ai/v1/accounts/acc_8c21d0/groups/join-requests?group_id=120363041234567890%40g.us" \
  -H "X-Api-Key: $UNIFYPORT_API_KEY"

Sau đó dùng id trả về để approve hoặc reject:

curl -X POST "https://api.unifyport.ai/v1/accounts/acc_8c21d0/groups/join-requests/update" \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "120363041234567890@g.us",
    "action": "approve",
    "member_ids": ["8613912345678@lid"]
  }'

Worker Node.js nhỏ

const pending = new Map();

app.post('/webhook', verifyUnifyPortSignature, async (req, res) => {
  const event = req.body;
  if (event.type !== 'group.join_request') return res.status(200).end();

  const groupId = event.data.conversation.id;
  const key = `${event.account_id}:${groupId}`;
  pending.set(key, { accountId: event.account_id, groupId });

  res.status(200).end();
});

Trước khi chạy production, làm theo webhook delivery: kiểm tra HMAC-SHA256 trên raw body bằng signing_secret, X-Device-Timestamp và X-Device-Signature.

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

Luồng này không cấp quyền admin cho một account vốn không có quyền quản lý nhóm. Nó cũng không biến push event thành nguồn sự thật duy nhất: group.join_request là tín hiệu best-effort. UI moderation nên đọc lại danh sách pending trước khi hiển thị trạng thái cuối hoặc gửi quyết định. UnifyPort chuẩn hóa event và action; còn ai được vào nhóm vẫn phụ thuộc vào rule của đội và quyền trong WhatsApp.

FAQ

Chỉ dùng webhook có duyệt được yêu cầu vào nhóm WhatsApp không?

Không nên. Webhook dùng để đánh thức worker. Trước khi quyết định, hãy gọi GET /v1/accounts/{account_id}/groups/join-requests và truyền id của các item trả về vào update endpoint.

member_ids phải dùng trường nào?

Dùng id từ response của List group join requests. Đừng dùng tên hiển thị và đừng tự đoán format số điện thoại.

Có cần WhatsApp Business API không?

Tutorial này dùng unofficial interface của UnifyPort, kết nối với một WhatsApp account có quyền nhóm cần thiết. Cài đặt duyệt thành viên chính thức của WhatsApp vẫn quyết định có phát sinh yêu cầu vào nhóm hay không.

Nên bắt đầu từ tài liệu nào?

Bắt đầu với List group join requests, rồi thêm Approve / reject join requests khi moderation UI đã sẵn sàng.

Sources checked on 2026-09-02

• WhatsApp Help Center: How to approve new members as a group admin
• UnifyPort API reference: Webhook events and List group join requests