IRCv3.3 Message Tags

This specification is a work-in-progress and may have major incompatible changes without warning.

This specification may change at any time and we do not recommend implementing it in a production environment.

Copyright © 2016 Kiyoshi Aman <>

Copyright © 2016 James Wheare <>

Unlimited redistribution and modification of this document is allowed provided that the above copyright notice and this permission notice remains intact.


This specification adds a new capability for general message tags support and a prefix for expressing client-only tags.


Previously, clients were required to negotiate a capability with servers for each supported tag. This made tags inappropriate for client-only features. By adding a new base capability, this specification allows clients to indicate support for receiving any well-formed tag, whether or not it is recognised or used. This also frees servers from having to filter messages tags for each individual client response.

The client-only tag prefix allows servers to safely relay untrusted client tags, keeping them distinct from server-initiated tags that carry verified meaning.



This specification adds the message-tags capability. Clients requesting this capability indicate that they are capable of parsing all well-formed tags, even if they don’t handle them specifically.

Servers advertising this capability indicate that they are capable of handling client-only tags.


Client-only tags are client-initiated tags that servers MUST attach as-is to any relevant event relayed to other clients. A client-only tag is prefixed with a plus sign (+) and otherwise conforms to the format specified in IRCv3.2 tags.

Client-only tags MUST be relayed on PRIVMSG and NOTICE events, and MAY be relayed on other events.

The expected client behaviour of individual client-only tags SHOULD be defined in separate specifications, in the same way as server-initiated tags.

This means client-only tags that aren’t specified in the IRCv3 extension registry MUST use a vendor prefix and SHOULD be submitted to the IRCv3 working group for consideration if they are appropriate for more widespread adoption.

The updated BNF for keys is as follows:

<key>           ::= [ '+' ] [ <vendor> '/' ] <sequence of letters, digits, hyphens (`-`)>

Individual tag keys MUST only be used a maximum of once per message. Clients receiving messages with more than one occurrence of a tag key SHOULD discard all but the final occurrence.

Security considerations

Client-only tags should be treated as untrusted data. They can contain any value and are not validated by servers in any way.

Client implementation considerations

There is no guarantee that other clients will support or display the client-only tags they receive, so these tags should only be used to enhance messages with non-critical information. Messages should still make sense to clients with no support for tags.

Moderation considerations

This section is non-normative.

Moderation tools available to channel and network operators typically operate on message text and sender information only. To avoid abusive content being sent in client-only tags, servers, services and management bot implementations may wish to enable moderation features that act on tag content as well.


This section is non-normative.

A bot that provides titles for URLs shared in channel could use a client-only tag to provide an icon enhancement for its response:

:nick! PRIVMSG #channel :
@+icon= :url_bot! PRIVMSG #channel A News Story

An example of a vendor-prefixed client-only tag: NOTICE #channel :A vendor-prefixed client-only tagged message