UnifyPort 群组 @ 提及：修复 WhatsApp 与 LINE 的普通文本标记

通过 UnifyPort 发送群消息后，如果提及标记原样显示，先检查请求的两个部分：顶层 mentions 数组声明要提及的成员，message.text 或 message.caption 中的 {{@<id>}} 决定标记位置。标记必须匹配数组中的完整 ID，或该 ID 在 @ 前的部分。不匹配的标记会作为普通文本发送，不能据此判断整条消息发送失败。

要点

• 只写 @Alex 这样的显示名称，不能代替文档要求的提及结构。
• mentions 与 message 同级，不应放在 provider_data 中。
• 此接口支持 WhatsApp 文本和媒体说明中的提及；LINE 仅支持文本提及。
• 其他渠道会忽略 mentions。发送成功不等于提及生效。

对齐群组、成员和正文标记

群组提及参考 区分三个输入：

输入	用途	常见错误
to.id，搭配 to.type: group	指定目标群组	把被提及成员当成发送目的地
顶层 mentions[].id	指定被提及的人	只提供显示名称
正文或媒体说明中的标记	指定提及出现的位置	使用数组中不存在的 ID

例如，成员 ID 为 100000000000002@lid 时，匹配规则允许 {{@100000000000002@lid}} 或 {{@100000000000002}}。这只是语法示例，不是真实收件人。自动生成消息时建议使用完整 ID，让对应关系更明确。不要修改标识符后缀，也不要根据姓名猜测成员 ID。

在支持的渠道中，可以通过会话成员列表查看所选群组成员。返回项包含 peer_id、display_name，列表支持分页。选择成员时保留消息账号和群组范围；显示名称只是标签，不是身份主键。

提及成员也不同于引用消息。WhatsApp 引用回复指南使用不透明的回复令牌选择消息内容。提及指向人，引用指向消息，不能交换字段。

从同一次选择生成两个部分

下面是用于构造文本请求的应用端 JavaScript，并非完整发送程序。参数应来自有权限的操作员所选消息账号、群组和已核实的成员 ID，正文来自审核后的草稿。这里的本地校验比 API 更严格：不允许草稿自行插入额外提及标记。

function buildGroupMention({ provider, accountId, groupId, memberId, text }) {
  if (!['whatsapp', 'line'].includes(provider)) {
    throw new Error('Mention sending is not enabled for this provider');
  }
  if (![accountId, groupId, memberId, text].every(
    value => typeof value === 'string' && value.trim().length > 0
  )) {
    throw new Error('Account, group, member, and text are required');
  }
  if (/[{}\s]/u.test(memberId) || text.includes('{{@')) {
    throw new Error('Use the selected member to create the mention marker');
  }
  return {
    account_id: accountId,
    to: { id: groupId, type: 'group' },
    message: { type: 'text', text: `{{@${memberId}}} ${text}` },
    mentions: [{ id: memberId }]
  };
}

在服务端使用 X-Api-Key 认证，将生成的 JSON 提交给 POST /v1/messages。这个函数不检查群成员资格、操作员权限或账号就绪状态，发送前仍需完成这些检查。授权成功也不代表连接正在运行。

需要提及多人时，应一起生成所选 ID 列表和全部标记。模板替换或 AI 起草完成后，检查最终序列化请求，避免后续处理删掉数组项却保留正文标记。

再次发送前先定位问题

现象	检查点	处理方式
{{@...}} 原样显示	标记与 ID 是否匹配	从同一个成员选择生成数组和标记
使用 provider_data.mentions	旧字段位置	改用顶层 mentions；旧字段已不再生效
草稿中只有 @Alex	缺少结构化身份和标记	先选成员，再生成两个输入
LINE 媒体说明包含提及	渠道与内容支持范围	如需改发独立文本消息，应明确审核，不要静默追加消息
Telegram、X、Zalo 或 TikTok 请求含 mentions	渠道边界	禁用此提及控件，不把请求受理当作成功提及

这些规则来自当前消息支持文档，并不保证每个账号及上游部署行为完全相同。whatsapp-protocol 是独立渠道，不继承 WhatsApp 的提及能力。

WhatsApp 媒体说明中的提及也不能修复文件请求。文件地址访问和投递问题应参照媒体发送排障指南独立处理。

不要混用 LINE 原生语法

LINE 官方消息类型文档介绍了文本消息 v2，可以将花括号内的字符串替换成提及或表情。这属于原生 Messaging API 契约，不意味着 LINE 原生消息对象可以直接代替 UnifyPort 的 message 和顶层 mentions。

如果直接接入官方 API，请按其原生文档实现。UnifyPort 提供非官方接口；统一端点并不等于复制全部原生消息功能，也不保证收件人看到通知。

验收与常见问题

启用控件前，建议在获授权的测试环境中分别检查：完整 ID 匹配、故意不匹配的标记、旧字段、LINE 文本提及，以及不支持的渠道。既要检查 HTTP 结果，也要查看接收端渲染。这里是建议测试项，并非已执行的测试结果。

accepted 能证明提及或通知成功吗？

不能。请求受理、消息投递、提及渲染和通知行为应分别记录。超时也不能证明消息没有发送，应先调查再决定是否重发。

能直接把入站 data.message.mentions 用作发送请求吗？

不能原样复制。事件参考中的可选入站字段是 data.message.mentions，出站 mentions 则位于顶层，并需要与生成的正文标记匹配。先核对目的地和实际要提及的人，不要自动提及入站消息中的所有成员。

所有已连接渠道都支持吗？

不支持。此发送契约支持 WhatsApp 文本和媒体说明，以及 LINE 文本。其他渠道会忽略该字段。

下一步与参考资料

先按群组提及请求参考验证一个明确选中的成员，再启用自动生成的群组回复。

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

• UnifyPort：群组提及
• UnifyPort：消息支持范围
• LINE：消息类型