Tip of the day: If you want to bypass access checks for channels as an IRCOp, use SAMODE or SAJOIN. Or use OperOverride.

Message tags

From UnrealIRCd documentation wiki
Jump to navigation Jump to search

Message tags communicate additional details in an IRC protocol message, such as the services account a user is using. End-users typically do NOT see the actual raw message tags in their client, but their IRC client can use them to display additional useful information (eg: registered account status, history playback, etc) or make better decisions (eg: if the user is trusted, should be auto-banned, etc).

Technical information

A JOIN looks like this in regular IRC protocol:
:nick!~user@localhost JOIN #test
If a client has enabled message tags and other capabilities it may look like this instead:
@time=2019-12-31T18:30:50.123Z;msgid=tjtArKOTqfcdY0FmaUGaHI;account=SomeAccount :nick!~user@localhost JOIN #test

Clients need to indicate support for receiving message tags, either by a specific CAP (such as CAP REQ account-tag) or by indicating support in general for message tags (CAP REQ message-tags).

The general rules on message tags parsing are described in https://ircv3.net/specs/extensions/message-tags.html

Supported message tags

UnrealIRCd supports the following message tags:

Tag name (specification) Module (source) Requirements Description and example
account account-tag CAP REQ account-tag Shows the account name of users who identified to Services.

@account=someone :nick!~user@host PRIVMSG #test :hi!

batch batch CAP REQ batch Allows grouping of multiple protocol messages into a batch. Used by labeled-response, history playback, etc.
bot bot-tag CAP REQ message-tags The bot tag is attached to messages/events from users that have user mode +B (users that are identified as bots).
label labeled-response CAP REQ label Allows IRC clients to easily correlate requests and responses

@label=zzzz :irc1.test.net ISON somenick
Note: uses BATCH for multi-line responses

unrealircd.org/json-log json-log CAP REQ unrealircd.org/json-log

+IRCOp privileges

In server notices you see the underlying JSON data. See JSON logging.
msgid message-ids CAP REQ message-tags Attaches an unique (network-wide) message id to messages.

@msgid=tjtArKOTqfcdY0FmaUGaHI :nick!~user@localhost PRIVMSG #test :hello everyone

time server-time CAP REQ server-time Attaches a label with the server date and time on which the message was sent.

@time=2019-12-31T18:30:50.123Z :nick!~user@localhost JOIN #test

unrealircd.org/userhost userhost-tag CAP REQ message-tags

+IRCOp privileges

The real uncloaked user@host - shown to IRC Operators only.

@unrealircd.org/[email protected] :[email protected] JOIN #test

unrealircd.org/userip userip-tag CAP REQ message-tags

+IRCOp privileges

The real user@ip - shown to IRC Operators only.

@unrealircd.org/[email protected] :[email protected] JOIN #test

unrealircd.org/geoip geoip-tag CAP REQ message-tags

+IRCOp privileges

The country code - shown to IRC Operators only.

@unrealircd.org/geoip=NL :[email protected] JOIN #test

+typing typing-indicator CAP REQ message-tags Client tag to show that the user is typing a message. Supported by f.e. IRCCloud and KiwiIRC nextclient.

@+typing=active TAGMSG #main

+draft/reply reply-tag CAP REQ message-tags This tag shows to which message a user is replying to. Often used by bots to refer to the !trigger.

@+draft/reply=msgid PRIVMSG #main :good idea


Changes between UnrealIRCd versions (in chronological order):

  • label: In UnrealIRCd 5.0.0, 5.0.1 and 5.0.2 the tag was draft/label, and the capability was draft/labeled-response. This because the specification was still in draft at that time. Starting with UnrealIRCd 5.0.3 the draft/ prefix was dropped.
  • unrealircd.org/userhost: added in UnrealIRCd 5.0.3
  • unrealircd.org/userip: added in UnrealIRCd 5.0.3
  • +typing: added in UnrealIRCd 5.0.5
  • draft/bot: added in UnrealIRCd 5.2.0
  • +draft/reply: added in UnrealIRCd 5.2.0
  • unrealircd.org/json-log: added in UnrealIRCd 6.0.0
  • unrealircd.org/geoip: added in UnrealIRCd 6.0.4
  • bot: added in UnrealIRCd (in addition to existing draft/bot, which will be removed at a later point)

Support for other message tags

In UnrealIRCd every message tag, including client message tags, need to have a message tag handler, usually added via a module. See FAQ: How can I allow other message tags?.