通过 API 获取 WhatsApp 群邀请链接：读取不等于重置

通过 UnifyPort 获取 WhatsApp 群邀请链接，应调用 GET /v1/accounts/{account_id}/groups/invite-code，在查询参数中传入 group_id。响应包含 data.invite_url 和 data.invite_code。读取链接不等于重置链接。 WhatsApp 提供管理员停用原邀请链接并创建新链接的原生操作；UnifyPort 公开文档描述的是读取，不是重置。

要点

• 同时确定消息账号和目标群；邀请码不是群 ID。
• 在服务端读取，仅向获授权的操作员展示链接。
• 获取、分享、入群审批和重置是四种不同操作。
• 原生重置后重新读取，并替换应用可控制的旧副本。

邀请链接接口实际做什么

WhatsApp 的官方群邀请说明介绍了链接邀请，并提醒接收者可能继续转发链接。该说明也介绍了管理员停用邀请链接并创建新链接的操作。不要把客户端的重置功能套用到 API 读取请求上。

UnifyPort 获取群邀请链接文档定义了以下契约：

输入或输出	含义
路径中的 account_id	执行操作的已连接消息账号
查询参数 group_id	平台群标识
data.invite_url	返回的邀请 URL
data.invite_code	返回的邀请码，不是会话 ID

当前操作支持矩阵将此能力映射到 whatsapp，不包含 LINE、Telegram、Zalo 或独立的 whatsapp-protocol。接口说明提示多数平台需要群管理员权限。本流程应使用获授权的 WhatsApp 群管理员账号，并核实其当前权限；工作空间 API 访问权不等于群管理权。

这是已连接账号的非官方接口，不是 WhatsApp Cloud API 端点。

在不泄露 API Key 的前提下读取

先通过群列表在正确账号下选择目标群。该列表包含账号已加入但尚未用于收发消息的群。按分页取数并保存选中条目的 id；群的 conversation_id 与 id 相同。不要仅凭可能重名的群名称定位目标。

下面是请求示例，并非实际执行记录。环境变量分别使用服务端保存的 API Key、选中的账号 ID 和列表返回的群 ID：

curl --get \
  "https://api.unifyport.ai/v1/accounts/${UNIFYPORT_ACCOUNT_ID}/groups/invite-code" \
  -H "X-Api-Key: ${UNIFYPORT_API_KEY}" \
  --data-urlencode "group_id=${WHATSAPP_GROUP_ID}"

平台标识可能含有 @ 等字符，因此应正确编码查询参数。密钥必须留在服务端，不要将此认证请求放进浏览器 JavaScript。

成功后读取 data.invite_url 和 data.invite_code，不要用群 ID 拼接猜测的邀请 URL。如果响应失败或缺少预期链接，让界面显示错误或暂不可用，不要补造值。

诊断记录应保留 HTTP 状态、错误码和服务端 request_id。请求追踪指南说明了如何保存证据而不记录整个响应体。此处响应体包含邀请链接，不应进入分析属性或通用应用日志。

给不同意图设计不同按钮

控件	预期行为	不代表什么
显示当前链接	读取并展示 API 结果	已创建新链接
复制链接	为授权分发复制当前 URL	对方已经入群
审核入群申请	打开审核流程	已重置链接
重置链接	引导管理员使用 WhatsApp 原生操作	存在已公开的 UnifyPort 重置调用

展示或复制前，应检查应用自己的操作权限。避免将链接放在公开看板、客服截图或分析事件属性中。如果使用缓存，应标注“此前获取的链接”，而不是保证仍然有效。

入群审批是另一个流程。如果需要审核，请参考 WhatsApp 入群申请审批队列，先核对待处理申请再作决定。获取链接不会启用审批，也不会批准任何申请人。

原生重置后更新已有副本

考虑一个假设场景：管理员认为链接被过度传播，于是在 WhatsApp 中重置了它，但应用仍保存旧 URL。

建议按以下流程处理：

1. 管理员操作期间，暂停分发缓存链接。
2. 对同一账号和同一群重新调用读取接口。
3. 将新读取结果展示给授权操作员核对。
4. 替换应用管理的链接，以及用旧 URL 生成的二维码图片。
5. 通知其他分发渠道负责人检查他们保存的副本。

这些是应用运维建议，不是原子轮换功能。公开文档没有定义重置参数、重置端点、链接过期时间字段或专用重置确认 webhook。不要猜测字段，也不要因没有事件到达就断言链接未变化。如果读取失败，应保持暂停分发或明确标记未解决，不要悄悄恢复旧缓存。

常见问题

每次调用 invite-code 都会生成新链接吗？

文档定义的是获取链接和邀请码，没有承诺每次读取都会轮换或生成新链接。

可以把 invite_code 当作 group_id 吗？

不可以。使用在该消息账号下选中的平台群 ID；邀请码是另一项返回值。

能通过这个 API 重置链接吗？

当前公开文档没有重置操作。请使用 WhatsApp 原生管理员功能，再重新读取当前链接。

读取失败是否代表群已删除？

不是。应查看 HTTP 状态和错误详情。get_group_invite_code_failed 表示服务端或上游读取失败，不能作为群已删除的证据。

下一步与资料

先按获取群邀请链接实现只读流程。上线前检查群选择、权限不足、查询编码、日志脱敏，以及授权管理员原生重置后的副本刷新。以上是建议验收项目，不是已执行的测试结果。

资料核对日期：2026-10-15。

• WhatsApp：创建群与邀请成员
• UnifyPort：获取群邀请链接
• UnifyPort：平台操作支持
• UnifyPort：错误参考