Customizing mentions

Customize who users can mention and notify mentioned non-participants.

By default, users can mention the participants in a conversation. You can also let them mention people who aren't currently participants, or otherwise control the contents of the mentions dropdown.

A team chat message field in which a user has typed '@', showing an autocomplete pop-up list with the names 'Taylor', 'Sebastian', 'Alice', 'Emma', and 'James'. — Mention suggestions shown above the message field

Mention people outside a conversation

Use the transformMentions property to add people to the mention suggestions:


1<t-chatbox
2  id="chatbox"
3  app-id="<APP_ID>"
4  user-id="sample_user_alice"
5  conversation-id="sample_conversation"
6></t-chatbox>
7
8<script type="module">
9  import '@talkjs/web-components';
10
11  const mentionableNonParticipants = [
12    { id: 'john', name: 'John' },
13    { id: 'ada', name: 'Ada' },
14  ];
15
16  const chatbox = document.querySelector('#chatbox');
17  chatbox.transformMentions = (suggestions) => [
18    ...suggestions,
19    ...mentionableNonParticipants,
20  ];
21</script>

This only adds the people to the mention suggestions. It doesn't add them to the conversation or notify them when they're mentioned.

Note: the callback may be called at any time and any number of times, and possibly with an incomplete participant list (eg while loading). It must have no side effects.

Notify mentioned non-participants

To notify a mentioned non-participant, add them to the conversation just before the message is sent. Use beforeSendMessage to find mentions in the message content, and the Data API to add every mentioned user as a participant:


1<t-chatbox
2  id="chatbox"
3  app-id="<APP_ID>"
4  user-id="sample_user_alice"
5  conversation-id="sample_conversation"
6></t-chatbox>
7
8<script type="module">
9  import { getTalkSession } from '@talkjs/core';
10  import '@talkjs/web-components';
11
12  const appId = '<APP_ID>';
13  const userId = 'sample_user_alice';
14  const conversationId = 'sample_conversation';
15  const mentionableNonParticipants = [
16    { id: 'john', name: 'John' },
17    { id: 'ada', name: 'Ada' },
18  ];
19
20  const session = getTalkSession({ appId, userId });
21  const conversation = session.conversation(conversationId);
22  const chatbox = document.querySelector('#chatbox');
23
24  chatbox.transformMentions = (suggestions) => [
25    ...suggestions,
26    ...mentionableNonParticipants,
27  ];
28  chatbox.beforeSendMessage = (message) => {
29    const mentions = getMentions(message.content);
30    for (const userId of mentions) {
31      conversation.participant(userId).createIfNotExists();
32    }
33  };
34
35  function getMentions(nodes) {
36    return nodes.flatMap((node) => {
37      if (typeof node === 'string') return [];
38      if (node.type === 'mention') return [node.id];
39      return 'children' in node ? getMentions(node.children) : [];
40    });
41  }
42</script>

You don't need to await createIfNotExists(). The Web Component and Data API share a session, and the Data API's pipelining preserves the order of these operations, so the participant is added before the message is sent.

The person must already exist as a TalkJS user before you can add them as a participant.