Mention in Messages

The mention feature in chat can be used to call attention to specific members. By @mentioning their names, this will promptly notify them so you can get a faster response to your message. Mention is only supported on TEXT message type.

Mention is supported in these channel types:

• Community

• Live

Mention is not supported in the Conversation channel type.

Create a message with mentions

There are 2 types of mentions:

1. USER - When using mention of this type, a specific member being mentioned will receive a push notification. Up to 30 channel members can be mentioned per message.

   import { MentionType, MessageRepository, MessageTools } from '@amityco/js-sdk';
   
   MessageRepository.createTextMessage({
     channelId: 'channelId',
     text: 'hi @user1 @user2',
     mentionees: [{ type: MentionType.User, userIds: ['userId1', 'userId2'] }],
     metadata: MessageTools.createMentionMetadata([
       { type: MentionType.User, userId: 'userId1', index: 3, length: 5 },
       { type: MentionType.User, userId: 'userId2', index: 10, length: 5 },
     ]),
   });

2. CHANNEL - When using mention of this type, all channel members will receive push notification.

   import { MentionType, MessageRepository, MessageTools } from '@amityco/js-sdk';
   
   MessageRepository.createTextMessage({
     channelId: 'channelId',
     text: 'hi @all',
     mentionees: [{ type: MentionType.Channel }],
     metadata: MessageTools.createMentionMetadata([
       { type: MentionType.Channel, index: 3, length: 3 },
     ]),
   });

Mentioning banned users

Banned users cannot be mentioned. However, admins can still find the banned users' names in the suggestion list during search when composing the message. But once the message is sent, the banned users’ information will not be included in the message payload anymore.

Banned users will not be notified nor receive any push notification.

Users who are not admins will not be able to search for the banned users' names as the latter will not appear in the suggestion list.

Update mentions for a text message

import { MentionType, MessageRepository, MessageTools } from '@amityco/js-sdk';

MessageRepository.updateMessage({
  messageId: 'messageId',
  data: { text: 'hi @user3' },
  mentionees: [{ type: MentionType.User, userIds: ['userId3'] }],
  metadata: MessageTools.createMentionMetadata([{ type: MentionType.User, userId: 'userId3', index: 3, length: 5 }]),
});

Search members

To search members when mentioning, you must use AmityChannelParticipation’s searchMembers function:

import { ChannelRepository, MemberFilter } from '@amityco/js-sdk';

const liveCollection = ChannelRepository.queryMembers({
  channelId: 'channelId',
  memberships: [MemberFilter.Member, MemberFilter.Muted],
  search: 'Mik'
});

liveCollection.on('dataUpdated', members => {
  console.log(members);
});

Viewing mentions

SDK only sends push notifications according to mention input during message creation. The system doesn't handle any data related to UI rendering. However, AmityMessage has a property called metadata which can hold an object and will not be tampered by the system. So, it can be utilized as a storage for UI-related data.

UI helper

SDK provides a helper which helps in generating a metadata containing sufficient data to highlight text with indices.

import { MentionType, MessageRepository, MessageTools } from '@amityco/js-sdk';

let messages = [];

const liveCollection = MessageRepository.queryMessages({ channelId: channelId });

messages = liveCollection.models;

liveCollection.on('dataUpdated', models => {
  messages = models;
});

messages.forEach(message => {
  const channelMentions = MessageToos.getMentionChannels(message.metadata);
  
  channelMentions.forEach(mention => {
    mention.index;
    mention.length;
  });

  const userMentions = MessageToos.getMentionUsers(message.metadata);
  
  userMentions.forEach(mention => {
    mention.index;
    mention.length;
  });
});

Mention notifications

When users are being mentioned, they will receive push notifications. You can customize the push notification content such as the title and the body using the notification setting API.

Provide the notification title and body in the titleTemplate and bodyTemplate parameters respectively. Here is a sample model:

{
  "level": "network",
  "isPushNotifiable": true,
  "notifiableEvents": [
   {
      "name": "text-mention-message.created",
      "isPushNotifiable": true,
      "titleTemplate": "{{UserDisplayName}} mentioned you in {{ChannelName}}",
      "bodyTemplate": "{{Message}}"
    }
  ]
}

Name	Data Type	Description
name	String	Event name
isPushNotifiable	Boolean	If set to true,push notification will be received for all text messages. If set to false, only messages with mention will have push notifications.
titleTemplate	String	Notification title
bodyTemplate	String	Notification body