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：訊息類型