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 prop to add people to the mention suggestions:


1const mentionableNonParticipants = [
2  { id: 'john', name: 'John' },
3  { id: 'ada', name: 'Ada' },
4];
5
6<Chatbox
7  appId="<APP_ID>"
8  userId="sample_user_alice"
9  conversationId="sample_conversation"
10  transformMentions={(suggestions) => [
11    ...suggestions,
12    ...mentionableNonParticipants,
13  ]}
14/>

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:


1import { getTalkSession } from '@talkjs/core';
2import { Chatbox } from '@talkjs/react-components';
3
4const appId = '<APP_ID>';
5const userId = 'sample_user_alice';
6const conversationId = 'sample_conversation';
7const mentionableNonParticipants = [
8  { id: 'john', name: 'John' },
9  { id: 'ada', name: 'Ada' },
10];
11
12const session = getTalkSession({ appId, userId });
13const conversation = session.conversation(conversationId);
14
15export function Chat() {
16  return (
17    <Chatbox
18      appId={appId}
19      userId={userId}
20      conversationId={conversationId}
21      transformMentions={(suggestions) => [
22        ...suggestions,
23        ...mentionableNonParticipants,
24      ]}
25      beforeSendMessage={(message) => {
26        const mentions = getMentions(message.content);
27        for (const userId of mentions) {
28          conversation.participant(userId).createIfNotExists();
29        }
30      }}
31    />
32  );
33}
34
35function 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}

You don't need to await createIfNotExists(). The React 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.