Mentions

Telegram allows mentioning other users in case of urgent duckling matters, and quickly navigating to those mentions in order to read them as swiftly as possible.

messageEntityMention#fa04579d offset:int length:int = MessageEntity;
messageEntityMentionName#352dca58 offset:int length:int user_id:int = MessageEntity;
inputMessageEntityMentionName#208e68c9 offset:int length:int user_id:InputUser = MessageEntity;

message#58ae39c9 flags:# out:flags.1?true mentioned:flags.4?true media_unread:flags.5?true silent:flags.13?true post:flags.14?true from_scheduled:flags.18?true legacy:flags.19?true edit_hide:flags.21?true pinned:flags.24?true id:int from_id:flags.8?Peer peer_id:Peer fwd_from:flags.2?MessageFwdHeader via_bot_id:flags.11?int reply_to:flags.3?MessageReplyHeader date:int message:string media:flags.9?MessageMedia reply_markup:flags.6?ReplyMarkup entities:flags.7?Vector<MessageEntity> views:flags.10?int forwards:flags.10?int replies:flags.23?MessageReplies edit_date:flags.15?int post_author:flags.16?string grouped_id:flags.17?long restriction_reason:flags.22?Vector<RestrictionReason> = Message;

channelParticipantsMentions#e04b5ceb flags:# q:flags.0?string top_msg_id:flags.1?int = ChannelParticipantsFilter;

---functions---

messages.sendMessage#520c3870 flags:# no_webpage:flags.1?true silent:flags.5?true background:flags.6?true clear_draft:flags.7?true peer:InputPeer reply_to_msg_id:flags.0?int message:string random_id:long reply_markup:flags.2?ReplyMarkup entities:flags.3?Vector<MessageEntity> schedule_date:flags.10?int = Updates;

channels.getParticipants#123e05e9 channel:InputChannel filter:ChannelParticipantsFilter offset:int limit:int hash:int = channels.ChannelParticipants;

Mentions are implemented as message entities, passed to the messages.sendMessage method:

• inputMessageEntityMentionName - Used when sending messages, allows mentioning a user inline, even for users that don't have a @username
• messageEntityMentionName - Incoming message counterpart of inputMessageEntityMentionName
• messageEntityMention - @botfather (this entity is generated automatically server-side for @usernames in messages, no need to provide it manually)

Incoming messages mentioning to the current user will have the mentioned flag set, and will contain one or more messageEntityMention and messageEntityMentionName constructors.

Graphical clients can show a list of mentionable users when the user starts entering an @ in the text bar; for this purpose, the channelParticipantsMentions filter can be used in channels.getParticipants.
This filter can be enhanced by providing an additional query string q (anything the user enters after @); it will also return non-participant users, in case of channel users commenting in post comment sections.

Dialog mentions

dialog#2c171f72 flags:# pinned:flags.2?true unread_mark:flags.3?true peer:Peer top_message:int read_inbox_max_id:int read_outbox_max_id:int unread_count:int unread_mentions_count:int notify_settings:PeerNotifySettings pts:flags.0?int draft:flags.1?DraftMessage folder_id:flags.4?int = Dialog;

---functions---

messages.getUnreadMentions#46578472 peer:InputPeer offset_id:int add_offset:int limit:int max_id:int min_id:int = messages.Messages;
messages.readMentions#f0189d3 peer:InputPeer = messages.AffectedHistory;

Graphical clients are supposed to show a blue mention indicator next to the message counter of chats in the dialog list.
The dialog constructor contains an unread_mentions_count field to isolate chats with unread mentions; the actual mention counter should be shown inside of the chat itself, above an @ button that can be used, by clicking multiple times, to navigate back (using messages.getUnreadMentions) through the mention history.

When the last unread mention is read, or when long-clicking on the @ button, all mentions for a chat should marked as read using messages.readMentions.