Skip to main content

Shared Chat

Supported since v1.22.0

Twitch now allows creators using Stream Together to effectively merge their chat rooms together. In the future, Twitch will also allow Shared Chat sessions without mandating Stream Together usage.

info

A Stream Together session currently supports up to six (6) participating channels. Upon joining a Stream Together session, a broadcaster has a limited window of time wherein they can opt out of shared chat.

From a user's perspective, their chat window includes more messages (sourced from the other channels) and when they send a message, it is automatically shared with those other channels. As messages arrive, the first-party interface includes the profile picture of the channel the message is sourced from.

tip

Update to Twitch4J v1.22.0 (or later) to avoid edge cases where your bot could spam responses to Shared Chat messages.

By default, we drop mirrored messages that have already been observed, so each unique message is only acted upon once. If you run a distributed bot, you will need to write Shared Chat logic yourself to avoid such edge cases.

As a result, each user message (PRIVMSG) sent in one chat is mirrored to the other chats in the Shared Chat session.

Similarly, most user notifications (USERNOTICE) are also shared with the other chat rooms in the session.
In particular, subs, resubs, sub gifts, community sub gifts, gift paid upgrades, prime paid upgrades, pay it forward gifts, incoming raids, and mod announcements are forwarded (while bits badge unlocks and charity donations are not forwarded).

note

Twitch has suggested that the current set of supported USERNOTICE types that are forwarded during shared chat is subject to change.

In addition, moderation actions (i.e., ban, timeout, unban, untimeout, warn) in one channel are automatically applied to all channels in the Shared Chat session. Message deletions are mirrored to the other channels if the deletion occurred in the source channel (by source moderators). Once the Shared Chat session concludes, mirrored bans, timeouts, and warnings are automatically lifted. Streamers can use "Shared Ban Info" to keep users that were banned during the Shared Chat session as restricted chatters after the session ends. These intricacies are explained in further detail within the official help article.

Since IRC tags do not indicate the source channel of mirrored moderation events, you can obtain this information via EventSub instead.

tip

You can detect which channels are participating in a given Shared Chat session via TwitchHelix#getSharedChatSession(OAuth2Credential, String), where the second argument is a channel's ID.
This endpoint does not require any scopes, so even app access tokens are sufficient.

Similarly, there are EventSub subscription types to track Shared Chat session updates in real-time.

You can read more about this feature in the official third-party developer documentation.

note

While this page focuses on IRC, these concepts also apply to the chat-related EventSub subscription types.

How do I detect Shared Chat messages?​

IRC events that can be mirrored during the Shared Chat session implement the MirrorableEvent interface.

MirrorableEvent#isMirrored tells you whether the given event originally came from a different source channel.

Then you can use MirrorableEvent#getSourceChannelId to obtain the true source channel.

Further, you can use MirrorableEvent#getSourceBadges (and MirrorableEvent#getSourceBadgeInfo) to obtain the chat badges associated with the message in the source channel.

When messages are mirrored, they are assigned new message IDs, so you can obtain the original message ID via MirrorableEvent#getSourceMessageId (which is unnecessary for most bots).

info

The following EventSub subscription types also distinguish shared events: channel.chat.message, channel.chat.notification, and channel.moderate.

Please read the Twitch documentation or the javadoc to understand the updated event payloads.

What does this mean for my application?​

Now, when you receive a message (e.g., ChannelMessageEvent), it could be directly sent to the channel you have joined (i.e., AbstractChannelEvent#getChannel), or it could be mirrored from another channel (i.e., MirrorableEvent#getSourceChannelId).

Most moderation bots may not need to change their logic regarding acting upon user messages. If such a bot observes the same message twice, it may try to execute duplicate moderation actions, but that is not a substantial concern.

However, bots that respond to chat commands should avoid replying to duplicated shared messages.
The simplest approach is to ignore chat commands where MirrorableEvent#isMirrored is true.
More sophisticated bots can conditionally reply to mirrored messages if the bot is not joined to the source channel and the source message id has not been observed already.

tip

Twitch4J v1.22.0+ automatically drops duplicate mirrored messages, so most developers will not need to update any logic! You can adjust the library's treatment of Shared Chat messages via MirroredMessagePolicy.

What edge cases should I know about?​

  1. The main edge case to consider is when your bot is joined to multiple channels in a single Shared Chat session.
    As a result, for each user message, you could receive up to six (6) events! When user messages can trigger bot responses in chat, you should validate the source channel to avoid replying up to six times. Since messages are mirrored, all six response messages would appear in each of the six chat rooms (which can look like spam).
    However, when using MirroredMessagePolicy.REJECT_IF_OBSERVED (or REJECT_ALL), this concern does not apply (unless you are running a distributed bot across multiple servers).

  2. When your bot is joined to multiple channels in a single Shared Chat session, the two channels could have different configurations for the bot, which can complicate determination of appropriate responses.

  3. Since moderation actions are forwarded, the stricter response will tend to prevail (as timed-out users can be banned, but banned users cannot be timed-out).

  4. While channel points redemptions with text input are mirrored to the other channels, currently redemptions without user input are not.

  5. Mirrored channel points redemptions (with user input) lack context as to what reward was redeemed.

  6. Channel-specific emotes do render accurately in the mirrored channels (in first-party chat), including cheermotes and follower emotes.

  7. If your bot is /restricted in one channel in the Shared Chat session, it cannot send messages to other channels in the session (unless it is a moderator). Yet, if a user is /monitored in one channel, this does not automatically apply to the other channels in the Shared Chat session.

  8. Neither the first-msg nor the returning-chatter flags are populated on the mirrored messages.

  9. When sending messages to a channel in a Shared Chat session, if you are joined to other channels in the same session on a different websocket, you will receive events for your own messages. However, if the other channels are joined on the same websocket, you will not receive events for your own messages.

  10. If you are joined to many channels and start observing random disconnects, some channels may have started Shared Chat sessions causing your message buffer to fill up. As a workaround, you can reduce the number of channels joined on each websocket connection via TwitchChatConnectionPoolBuilder#maxSubscriptionsPerConnection.

  11. First-party moderation settings such as AutoMod configuration, Blocked Terms, and Chat Mode (e.g., emote only) only apply to messages sent in the corresponding source channel. Thus, it can be possible to send a message in a Shared Chat session that contains a blocked term of another channel within the session.

  12. Since this feature is complex and not widely tested yet, there may be bugs in Twitch's implementation.