User Mentions

Overview

You can mention users in both activities and comments. When you include mentioned_user_ids, the API stores the mentions and returns enriched mentioned_users in the response. Optionally, you can create notification activities for mentioned users or send push notifications.

Adding user mentions

mentioned_user_ids can only contain existing user ids, you can use queryUsers endpoint to search for users to mention.

Please note that it's up to you to include user mentions (for example @Alice) in the activity/comment text, the Stream API won't modify these fields based on mentioned_user_ids.

Adding an activity with mentions

final activity = await feed.addActivity(
  request: const FeedAddActivityRequest(
    type: 'post',
    text: 'Hey @bob and @alice, check this out!',
    mentionedUserIds: ['bob', 'alice'],
    // Put an activity on each mentioned user's notification feed
    createNotificationActivity: true,
  ),
);

// The response carries the enriched user objects
print(activity.getOrThrow().mentionedUsers.map((u) => u.name));

Adding a comment with mentions

final comment = await feed.addComment(
  request: const ActivityAddCommentRequest(
    activityId: 'activity_123',
    activityType: 'activity',
    comment: 'Thanks @bob for the tip!',
    mentionedUserIds: ['bob'],
    createNotificationActivity: true,
  ),
);

print(comment.getOrThrow().mentionedUsers.map((u) => u.name));

Reading mentioned users

Activities and comments returned by the API include a mentioned_users array with enriched user objects (id, name, image, etc.). Use them to render @mentions in your UI.

final activity = client.activity(
  activityId: 'activity_123',
  fid: const FeedId.user('john'),
);
await activity.get();

// `mentionedUsers` is never null: it defaults to an empty list
final activityData = activity.state.activity;
if (activityData != null && activityData.mentionedUsers.isNotEmpty) {
  for (final user in activityData.mentionedUsers) {
    print('${user.id}: ${user.name}');
  }
}

// Comments carry their own mentioned users
for (final comment in activity.state.comments) {
  for (final user in comment.mentionedUsers) {
    print('mentioned in a comment: ${user.id}');
  }
}

Mentions in notification feed

• Activities: When create_notification_activity is true, each mentioned user receives a mention notification in their notification feed.
• Comments: When create_notification_activity is true, each mentioned user receives a comment_mention notification (the activity author does not get an extra notification for mentions; they already get a comment notification).

For updating or deleting activities/comments and managing mention notifications (e.g. handle_mention_notifications, delete_notification_activity), see Notification feeds.

Push notifications

Use the skip_push parameter to control if push notifications are sent to mentioned users or not. For more information check the Push notification guide that contains all relevant information about setting up push notification providers, customizing notifications and user preferences.