UnifyPort Group Mentions: Fix Literal Tags in WhatsApp and LINE

If a UnifyPort group message displays a literal mention marker, check both halves of the request: a top-level mentions array declares the tagged members, and {{@<id>}} inside message.text or message.caption selects where a tag appears. The marker must match a declared ID, or its local part before @. An unmatched marker is sent as literal text; it is not a failed-send signal.

Key takeaways

• A displayed name such as @Alex is not a substitute for the documented mention structure.
• Put mentions beside message, not inside provider_data.
• WhatsApp supports text and media-caption mentions; LINE supports text mentions only through this contract.
• Other providers ignore mentions. A successful send alone does not prove a mention worked.

Match the recipient, member, and marker

The mention-send reference describes three separate inputs:

Input	Purpose	Common mistake
to.id, with to.type: group	Select the destination group	Using the selected member as the destination
Top-level mentions[].id	Identify who is tagged	Supplying only a display name
Marker inside text or caption	Position the tag in the content	Referring to an ID absent from mentions

For a member ID 100000000000002@lid, the documented matching rule permits {{@100000000000002@lid}} or {{@100000000000002}}. This is a syntax illustration, not a real recipient. Prefer the full-ID form in generated messages so the relationship is explicit. Never create a member identity by changing an identifier suffix or guessing from a name.

Use the conversation-members reference to inspect the selected group’s members where supported. Its items expose peer_id and display_name, and the list supports pagination. Keep identity selection scoped to the connected messaging account and group; display names are labels, not identity keys.

This also differs from quoting a particular message. The quoted-reply guide uses an opaque reply token to select content. A mention selects a person; a quote selects a message. Do not exchange their fields.

Build both halves from one selection

Below is application-side JavaScript for constructing a text request, not a complete sender. The arguments come from an authorized operator’s selected account, group, and verified member identity. The final text comes from a reviewed draft. Local validation is intentionally stricter than the API: it does not let the draft introduce additional mention markers.

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 }]
  };
}

Submit this JSON body to POST /v1/messages with server-side X-Api-Key authentication. The helper does not check membership, operator permissions, or account readiness; perform those checks before dispatch. In particular, authorization is separate from a running connection.

For multiple mentions, build the selected ID list and every marker together. Review the final serialized request after any template expansion or AI drafting. Do not let a later transformation remove an array entry while leaving its marker behind.

Diagnose literal tags before sending again

Observation	Check	Correction
{{@...}} remains visible	Marker-to-ID matching	Generate the array and marker from the same selected identity
Request uses provider_data.mentions	Legacy field placement	Move to the documented top-level mentions; the legacy field is no longer honored
Only @Alex appears in the draft	Missing structured identity and marker	Select the intended member and construct both inputs
LINE media caption has a mention	Channel/content support	Use a separately reviewed text message; do not silently send an extra message
Telegram, X, Zalo, or TikTok request includes mentions	Provider boundary	Disable this mention control rather than treating an accepted send as a tag

These rules come from the current message-support contract, not a promise that every account or upstream deployment behaves identically. whatsapp-protocol is a separate provider and does not inherit WhatsApp mention support.

For WhatsApp media captions, the file still needs a valid media request. Follow the media-send troubleshooting guide for source access and delivery checks; mention formatting does not fix a broken media URL.

Keep native LINE syntax separate

LINE’s official message-types documentation describes text messages (v2), with strings enclosed in braces substituted by mentions and emojis. That is the native Messaging API’s contract. It does not make a LINE native message object interchangeable with UnifyPort’s message and top-level mentions fields.

Use native documentation when integrating directly with the official API. UnifyPort is an unofficial interface; a shared endpoint does not reproduce every native message feature or guarantee that the recipient sees a notification.

Acceptance checks and FAQ

Before enabling the control, test a matching full ID, a deliberately unmatched marker, the legacy field, a LINE text mention, and an unsupported provider in an authorized test environment. Inspect the received rendering as well as the HTTP result. These are proposed checks, not reported test results.

Does accepted prove the user was tagged or notified?

No. Keep request acceptance, message delivery, mention rendering, and notification behavior separate. A timeout also does not prove nothing was sent; investigate before repeating the request.

Can I use inbound data.message.mentions as the send body?

Not unchanged. The event reference exposes optional inbound data.message.mentions. Outbound mentions belongs at the top level, and its IDs must match your generated content markers. Review the destination and intended people instead of automatically tagging everyone from an incoming message.

Will mentions work across every connected channel?

No. This sending contract supports WhatsApp text/captions and LINE text. Other providers ignore the field.

Next step and sources

Start with the group-mention request reference and one intentionally selected member before enabling generated group replies.

References checked on 2026-10-10:

• UnifyPort: Mention members
• UnifyPort: Message support
• LINE: Message types