Упоминания в группах UnifyPort: почему теги WhatsApp и LINE остаются текстом

Если в групповом сообщении UnifyPort маркер упоминания отображается буквально, проверьте обе части запроса. Массив mentions верхнего уровня определяет участников, а {{@<id>}} в message.text или message.caption задаёт место тега. Маркер должен совпадать с полным ID из массива либо с его частью до @. Несопоставленный маркер отправляется как обычный текст — это не признак неудачной отправки всего сообщения.

Главное

• Одного отображаемого имени вроде @Alex недостаточно для документированной структуры упоминания.
• mentions находится рядом с message, а не внутри provider_data.
• WhatsApp поддерживает упоминания в тексте и подписях к медиа; LINE — только в тексте через этот контракт.
• Остальные провайдеры игнорируют mentions. Успешная отправка не доказывает, что упоминание сработало.

Сопоставьте группу, участника и маркер

Справочник отправки упоминаний разделяет три входных значения:

Вход	Назначение	Типичная ошибка
to.id и to.type: group	Группа назначения	Подставить участника вместо группы
Верхнеуровневый mentions[].id	Кого отметить	Передать только отображаемое имя
Маркер в тексте или подписи	Где показать тег	Указать ID, которого нет в массиве

Например, для ID 100000000000002@lid правило допускает {{@100000000000002@lid}} и {{@100000000000002}}. Это пример синтаксиса, а не реальный получатель. В генерируемых сообщениях лучше использовать полный 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 в POST /v1/messages с серверной аутентификацией X-Api-Key. Функция не проверяет членство в группе, права оператора и готовность аккаунта: это отдельные проверки перед отправкой. Завершённая авторизация не равнозначна работающему соединению.

Для нескольких упоминаний формируйте список выбранных ID и все маркеры вместе. После обработки шаблона или подготовки текста моделью проверяйте итоговый сериализованный запрос. Последующее преобразование не должно удалять элемент массива, оставляя его маркер в тексте.

Найдите причину до повторной отправки

Наблюдение	Что проверить	Исправление
Видно буквальное {{@...}}	Совпадение маркера и ID	Генерировать обе части из одного выбранного участника
Используется provider_data.mentions	Устаревшее расположение	Перенести в верхнеуровневый mentions; старое поле больше не учитывается
В черновике только @Alex	Отсутствие структурированного ID и маркера	Выбрать участника и создать обе части
Упоминание в подписи к медиа LINE	Поддержка контента	Отдельно согласовать текстовое сообщение, не отправлять дополнительное автоматически
mentions передан для Telegram, X, Zalo или TikTok	Ограничения провайдера	Отключить этот элемент управления, не считать принятие запроса успешным тегом

Эти правила основаны на текущей таблице поддержки сообщений. Они не гарантируют одинакового поведения каждого аккаунта или развёртывания внешнего сервиса. whatsapp-protocol — отдельный провайдер, не наследующий поддержку упоминаний WhatsApp.

Для подписи к медиа WhatsApp сам запрос отправки файла тоже должен быть корректным. Проверяйте доступность источника и доставку по руководству по отправке медиа. Исправление упоминания не восстановит неработающий URL файла.

Не смешивайте с нативным синтаксисом LINE

Официальная документация типов сообщений LINE описывает текстовые сообщения v2: строки в фигурных скобках можно заменять упоминаниями и эмодзи. Это контракт нативного Messaging API, а не основание подставлять объект LINE вместо message и верхнеуровневого mentions в UnifyPort.

При прямой интеграции с официальным API используйте его документацию. UnifyPort предоставляет неофициальный интерфейс. Общий endpoint не воспроизводит все нативные функции и не гарантирует показ уведомления получателю.

Проверки и FAQ

До включения функции в разрешённой тестовой среде проверьте полный совпадающий ID, намеренно несовпадающий маркер, старое поле, текстовое упоминание LINE и неподдерживаемого провайдера. Оценивайте и HTTP-ответ, и отображение у получателя. Это предлагаемые проверки, а не результаты проведённых испытаний.

Доказывает ли accepted, что пользователь отмечен или уведомлён?

Нет. Принятие запроса, доставка, отображение упоминания и уведомление — разные состояния. Тайм-аут тоже не доказывает отсутствие отправки. Сначала выясните результат, затем решайте вопрос повтора.

Можно ли отправить входящий data.message.mentions без изменений?

Нет. Справочник событий описывает необязательный входящий data.message.mentions. В исходящем запросе массив находится на верхнем уровне, а ID должны соответствовать сгенерированным маркерам. Проверьте назначение и нужных людей, вместо того чтобы автоматически отмечать всех из входящего сообщения.

Работает ли это на всех подключённых каналах?

Нет. Этот контракт поддерживает текст и подписи WhatsApp, а также текст LINE. Другие провайдеры игнорируют поле.

Следующий шаг и источники

Начните со спецификации групповых упоминаний и одного явно выбранного участника, прежде чем включать автоматически генерируемые ответы группе.

Источники проверены 2026-10-10:

• UnifyPort: отправка упоминаний
• UnifyPort: поддержка сообщений
• LINE: типы сообщений