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 引用回覆指南使用不透明的回覆 token 選擇內容。提及指向人，引用指向訊息，兩者欄位不能互換。

由同一次選擇產生兩部分

以下應用程式端 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：訊息類型