UnifyPortのグループメンション：LINE・WhatsAppでタグが文字列になる場合

UnifyPort経由のグループメッセージでメンションのマーカーがそのまま表示される場合は、リクエストの二つの要素を確認してください。トップレベルのmentions配列が対象メンバーを指定し、message.textまたはmessage.caption内の{{@<id>}}が表示位置を指定します。マーカーは配列内の完全なID、またはIDの@より前の部分と一致する必要があります。一致しないマーカーは通常の文字列として送信されるため、メッセージ全体の送信失敗とは限りません。

要点

• @Alexのような表示名だけでは、仕様上のメンション構造を満たしません。
• mentionsはmessageと同じ階層です。provider_data内ではありません。
• この契約ではLINEはテキストのみ、WhatsAppはテキストとメディアのキャプションに対応します。
• その他のプロバイダーはmentionsを無視します。送信成功だけでメンション成功とは判断できません。

グループ、メンバー、マーカーを対応させる

メンション送信リファレンスでは、次の三つを区別します。

入力	役割	よくある間違い
to.idとto.type: group	送信先グループ	対象メンバーを送信先にしてしまう
トップレベルのmentions[].id	メンションする相手	表示名だけを渡す
本文・キャプション内のマーカー	メンションの位置	配列にないIDを使う

例えばメンバーIDが100000000000002@lidなら、仕様上は{{@100000000000002@lid}}と{{@100000000000002}}のどちらも対応します。これは構文例であり、実在の送信先ではありません。自動生成では完全なIDを使うと関係が明確です。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 }]
  };
}

生成したJSONはサーバー側のX-Api-Key認証でPOST /v1/messagesに送信します。この関数は所属、担当者の権限、アカウントの準備状態を確認しません。送信前に別途確認してください。認証済みであることと、接続が稼働していることも別です。

複数人をメンションする場合も、ID一覧と各マーカーを同時に生成します。テンプレート展開やAIによる下書き処理の後、最終的なJSONを確認し、配列要素だけが削除されてマーカーが残る状態を防ぎます。

再送する前の切り分け

現象	確認箇所	修正
{{@...}}がそのまま見える	マーカーとIDの一致	同じメンバー選択から両方を生成
provider_data.mentionsを使用	旧フィールドの配置	トップレベルのmentionsへ変更。旧フィールドは現在利用されません
下書きに@Alexしかない	構造化されたIDとマーカー	相手を選択して両方を作成
LINEのメディアキャプションにメンション	コンテンツの対応範囲	別のテキスト送信をレビュー。自動で追加送信しない
Telegram、X、Zalo、TikTokにmentionsを指定	プロバイダーの境界	このメンション操作を無効化し、受理を成功と扱わない

これは現在の送信対応表に基づく説明です。すべてのアカウントや上流環境で同一の動作を保証するものではありません。whatsapp-protocolは別プロバイダーで、WhatsAppのメンション対応を引き継ぎません。

WhatsAppのキャプションでは、メディアリクエスト自体も有効でなければなりません。ファイル取得や配送の問題はメディア送信のトラブルシューティングで確認してください。メンションの修正で無効なメディアURLは直りません。

LINE公式APIの構文とは分ける

LINE公式のメッセージタイプの説明では、テキストメッセージv2で波括弧内の文字列をメンションや絵文字に置換できます。これはネイティブのMessaging APIの契約です。LINEのメッセージオブジェクトを、そのままUnifyPortのmessageとトップレベルのmentionsに置き換えられるわけではありません。

公式APIを直接利用する場合は公式の仕様に従ってください。UnifyPortは非公式インターフェースです。共通エンドポイントでも全ネイティブ機能が使えるわけではなく、相手への通知表示も保証しません。

受け入れ確認とFAQ

権限のあるテスト環境で、完全なIDの一致、意図的な不一致、旧フィールド、LINEのテキストメンション、未対応プロバイダーを確認してください。HTTP結果と受信画面の両方を確認します。これはテスト提案であり、実施済みの結果ではありません。

acceptedならメンションや通知は成功していますか？

いいえ。受理、配送、メンション表示、通知動作を分けて扱います。タイムアウトも未送信の証明にはなりません。再送前に調査してください。

受信したdata.message.mentionsをそのまま送信できますか？

いいえ。イベントリファレンスでは受信側の任意フィールドがdata.message.mentionsです。送信側はトップレベルに置き、生成した本文のマーカーと対応させます。受信メッセージに含まれる全員を自動でメンションせず、送信先と対象者を確認してください。

接続したすべてのチャネルで使えますか？

この契約ではWhatsAppのテキスト・キャプションとLINEのテキストが対象です。その他はフィールドを無視します。

次のステップと出典

グループメンションのリクエスト仕様に沿って、明示的に選んだ一人で確認してから、自動生成のグループ返信を有効にしてください。

確認日：2026-10-10。

• UnifyPort：メンション送信
• UnifyPort：メッセージ対応表
• LINE：Message types