用 UnifyPort 搭建 WhatsApp 群组入群申请审批队列

要把 WhatsApp 群组入群申请接入系统，不要把 webhook 当成唯一事实来源。正确做法是：仍然让 WhatsApp 的群组审批设置决定是否需要审批；UnifyPort 负责把 group.join_request 作为低延迟信号推给你，再用 GET /v1/accounts/{account_id}/groups/join-requests 拉取待审列表，最后用 POST /v1/accounts/{account_id}/groups/join-requests/update 批量同意或拒绝。

重点结论

• WhatsApp 官方帮助中心说明，Approve new members 默认关闭；开启后，群组管理员需要审批申请入群的人。
• group.join_request 只适合作为提醒信号。UnifyPort 文档也明确建议轮询 List group join requests，把列表接口作为可靠来源。
• 审批前先保存 account_id、群组 id、申请人 id、申请来源，以及你自己的审核记录。
• 如果你看过 Webhook 优先的入站集成清单，这篇就是群组审核场景里的同一条原则：先验签、先入库，再分发。

WhatsApp 仍然控制什么

WhatsApp 群组审批本身是群组管理员功能。官方帮助中心的 How to approve new members as a group admin 写明：开启 Approve new members 后，管理员需要批准任何想加入群组的人；这个设置默认关闭。

所以你的系统不应该替代这个开关。它要解决的是另一个问题：有申请出现时，谁来审核、审核人看到什么信息、最后对哪些申请人 id 执行同意或拒绝。

队列架构

推荐用一个已签名的 webhook endpoint 接收群组事件，再通过列表接口做状态同步：

1. 创建 webhook endpoint，把 subscribed_events 设置为包含 group.join_request；如果你已经收集所有公开事件，也可以用 ["*"]。如何选择可参考 UnifyPort Webhook Event Filters。
2. 收到 group.join_request 后，用 account_id 和 data.conversation.id 生成同步任务。
3. 调用 List group join requests 拉取当前待审列表。返回条目的 id 就是之后传入 member_ids 的值。
4. 把待审申请展示给人工审核人，或者套用你自己的内部规则。
5. 调用更新接口，传入 action: "approve" 或 action: "reject"。

如果你已经实现过 Telegram 群组入群申请审批队列，这里的运维逻辑相同：push 事件负责唤醒系统，列表接口才是你信任的状态。

事件和请求格式

一个 WhatsApp 入群申请事件可能长这样：

{
  "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" }
  }
}

审批前先同步列表：

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

再对返回的 id 执行同意或拒绝：

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"]
  }'

一个简单的 Node.js worker

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();
});

实际投产前，请按 webhook delivery 的要求，用 signing_secret、X-Device-Timestamp 和 X-Device-Signature 对原始请求体做 HMAC-SHA256 校验。

限制和取舍

这个方案不会给没有管理权限的账号自动获得管理员能力。它也不应该把推送事件当成唯一事实来源，因为 group.join_request 是 best-effort 信号。你的审核界面应该在展示或提交前重新拉取待审列表。UnifyPort 负责移动事件和执行操作，谁能进群仍然由你的团队规则和 WhatsApp 群组权限决定。

FAQ

只靠 webhook 能审批 WhatsApp 入群申请吗？

不建议。webhook 用来触发 worker；真正审批前，应调用 GET /v1/accounts/{account_id}/groups/join-requests，再把返回的条目 id 传给更新接口。

member_ids 应该填什么？

填 List group join requests 返回条目的 id。不要用昵称，也不要自己拼接手机号格式。

一定要 WhatsApp Business API 吗？

这篇教程使用的是 UnifyPort 的非官方接口，连接的是具备群组权限的 WhatsApp 账号。WhatsApp 官方的群组审批开关仍然决定是否会产生申请。

下一步看哪里？

先看 List group join requests，再接入 Approve / reject join requests。

资料来源（2026-09-02 核对）

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