New Message Fields (flags, message_reference, mention_channels)

[faultyserver]

There are a few new fields on messages that haven't yet been documented (sorry). This PR should bring the Message Object docs all the way up to date with what's currently happening in production.

This PR supersedes and replaces both #1030 and #1031 as it covers the changes from both.

So what's new here?

Channel Mentions

A few weeks ago we shipped a feature that changed/added a new channel mention format to allow mentions to channels that are in other guilds. This was in support of Channel Following and making sure that crossposted messages are able to appear just like normal messages with all of the same features, and to enable linking back to the source guild in a meaningful way (i.e., not just "viewing the server" through the popout, but going directly to a mentioned channel to check out something that's happening there).

After various iterations and feedback, we decided to forego this route and find another way that is less disruptive and more scalable and flexible for the future.

The result is the mention_channels field on messages. No more new mention format in messages or any breaking changes, this is just a new field containing information needed to resolve and display channel mentions for channels that the user might not currently have information for (e.g., if they aren't in that guild). The field contains a list of Channel Mention objects, which are just a channel id (to match with the ID in the mention from the message), the guild id for that channel, and the name and type.

Importantly, not all messages will have this field set, and not all channels mentioned in a message will necessarily be included in this list. For now, only crossposted messages (and potentially the source message of those crossposts) will have this field at all. Then, for a channel to get included in the list, it must be a textual guild channel (currently GUILD_TEXT or GUILD_NEWS) in a guild that has the LURKABLE feature.

Message References

Message references are set on crossposted messages identifying the source message the was published to create them. They include the original message id, and the channel and guild ids the message was published from.

Notably, message_id is not always included, specifically in the case of the initial System message sent when a user starts following a channel, where there is no originating message to reference. guild_id may also be null on some messages from the initial rollout of this feature, but should never be null going forward (really as of >3 weeks ago).

Message Flags

Message flags are an integer bitset indicating various additional features of a message. So far, the 2 use cases for these flags are with crossposts and suppressing embeds.

Crossposts will either have the IS_CROSSPOST flag for the messages sent to other guilds, or CROSSPOSTED on the source message once it has been published.

Embed suppression, as documented in #1003, has not been finalized in terms of the API, but the flag on messages has been set and is part of the bit set already.

[SinisterRectus]

I notice that there is a new system message of type 12 for following news channels. Is this documentable?

[faultyserver]

Yes! Thanks for catching that.

[Doc94]

About the message reference...
In what cases guild_id is null?

[faultyserver]

From the original post:

guild_id may also be null on some messages from the initial rollout of this feature, but should never be null going forward (really as of >3 weeks ago).

We can't guarantee that it will be present on every message because there were a number of messages sent in the time of the initial rollout where it wasn't being set properly. In some cases we're able to populate this by loading the guild_id from the channel, but that also is not guaranteed.