SharedChatQueue User Guide

SharedChatQueue is a Twitch Shared Chat-aware queue bot for play-with-viewers streams, community games, and multi-channel shared-chat sessions.

The bot keeps queues fair when multiple channels are connected through Twitch Shared Chat. Instead of treating the queue as one simple first-come-first-served list, SharedChatQueue can rotate picks by the viewer's origin channel so one channel does not flood out the others.

Quick start

For viewers in a channel where SharedChatQueue is active:

1. Type !join to enter the queue.
2. Type !queue to see the current queue status.
3. Type !leave if you want to leave the queue.
4. Type !queuehelp to see a short command reminder in chat.

For streamers who want to add the bot:

1. Go to SharedChatQueue's Twitch chat.
2. Type !join.
3. After the bot joins your channel, mod the bot in your own channel with /mod sharedchatqueue.
4. Use !part from SharedChatQueue's chat if you want the bot to leave your channel later.

How SharedChatQueue works

SharedChatQueue is built for Twitch Shared Chat.

When channels are not linked by shared chat, each channel has its own separate queue. When SharedChatQueue detects that channels are participating in the same shared-chat session, it can treat those channels as one linked queue group.

In the default queue mode, picks rotate fairly by origin channel. That means viewers are still picked in join order within their own channel, but the bot tries to alternate between participating channel origins.

Example:

Origin	Viewers waiting
Channel A	Alice, Bob, Erin
Channel B	Charlie, Dana

In the default fair-rotation mode, the pick order would be:

Alice -> Charlie -> Bob -> Dana -> Erin

This helps keep shared-chat queues from becoming dominated by whichever channel has the fastest or busiest chat.

Viewer commands

Use these commands in a channel where SharedChatQueue is active.

Command	Description
!join	Enters you into the queue.
!leave	Removes you from the queue.
!queue	Shows whether the queue is open or closed, how many viewers are waiting, which origins are represented, and a preview of upcoming picks.
!queuehelp	Shows a short command reminder in chat.

If the queue is closed or frozen, !join will not add new viewers until the queue is opened again.

Moderator and broadcaster commands

These commands are for moderators and broadcasters in channels where SharedChatQueue is active.

Command	Description
!next	Picks the next viewer from the queue.
!pick <count>	Picks one or more viewers from the queue.
!queueremove <user>	Removes a specific viewer from the queue.
!queueopen	Opens the queue so viewers can join.
!queueclose	Closes the queue. Existing entries are preserved.
!queuefreeze	Freezes the queue so new joins are paused.
!queueunfreeze	Unfreezes the queue so viewers can join again.
!queueclear	Clears the queue.
!queuemode roundrobin-origin	Uses fair rotation by origin channel.
!queuemode oldest	Uses classic first-come-first-served order by join time.

!pick <count> can be used to pick multiple viewers at once, such as !pick 3.

Queue modes

SharedChatQueue supports two queue modes.

roundrobin-origin

This is the default mode.

The queue rotates between origin channels while preserving join order inside each origin. This is the mode intended for shared-chat play-with-viewers streams.

oldest

This mode uses classic first-come-first-served queue order by join time, regardless of origin channel.

Streamer setup commands

These commands are used in SharedChatQueue's own Twitch chat.

Command	Description
!join	Adds your channel to SharedChatQueue's joined-channel list.
!part	Removes your channel from SharedChatQueue's joined-channel list.

After using !join, SharedChatQueue will try to join your channel. If the bot joins but does not speak, make sure it is modded in your channel with /mod sharedchatqueue.

The !join command behaves differently depending on where it is used:

Where you use it	What !join does
In SharedChatQueue's own chat	Adds your channel to the bot's joined-channel list.
In a joined queue channel	Enters you into that channel's queue.

Channel safety commands

Channel owners can mute or restore SharedChatQueue in their own channel.

Command	Permission	Description
!mutescq	Channel owner	Mutes SharedChatQueue chat output in that channel.
!unmutescq	Channel owner	Restores SharedChatQueue chat output in that channel.

Muting one channel does not mute the bot everywhere. It only affects that channel.

Shared chat behavior

SharedChatQueue watches Twitch shared-chat metadata to understand where messages originated.

When it detects linked channels, it can merge those channels into one shared queue scope. Responses stay inside the detected queue scope so unrelated channels do not receive queue updates.

If shared-chat linkage is no longer seen for a while, the link can expire and the channels will return to separate queue behavior.

Troubleshooting

The bot joined but does not speak

Try the following:

1. Make sure the bot is modded in your channel with /mod sharedchatqueue.
2. Check whether your channel has verified chatter restrictions that block unmodded bots.
3. Make sure the bot is not banned or timed out.
4. Try a simple queue command such as !queue.
5. If needed, go to SharedChatQueue's Twitch chat, use !part, then use !join again.

I used !join but entered the queue instead of adding my channel

Use !join in SharedChatQueue's own Twitch chat to add your channel.

Use !join in a joined queue channel to enter that channel's queue.

The queue is not accepting new viewers

The queue may be closed or frozen. A moderator or broadcaster can use !queueopen or !queueunfreeze to allow new joins again.

Picks are not simple first-come-first-served

The queue may be using roundrobin-origin, which rotates fairly between origin channels. This is the default behavior for shared-chat queues.

A moderator or broadcaster can use !queuemode oldest to switch to classic first-come-first-served order.

I want the bot to leave my channel

Go to SharedChatQueue's Twitch chat and use !part.

I need the bot to stop talking in my channel right now

If you are the channel owner, use !mutescq in your channel. Use !unmutescq when you want to restore bot chat output.

Privacy and data notes

SharedChatQueue stores the information needed to manage joined channels, queue state, shared-chat linkage, and channel mute state.

This public guide does not include token details, deployment secrets, private configuration, or internal storage details.