Adding “for_source_only” parameter for Shared Chat and a behavior update for “Send Chat Message” API endpoint - May 19, 2025

Announcements
1

Shared Chat launched last year as a feature within Stream Together to combine multiple streamer communities into a unified chat experience. As usage continues to grow, we are incorporating feedback from developers, streamers, and viewers regarding how Shared Chat interacts with chatbots. One particular observation is that some programmatic chat messages sent through the Twitch API can appear irrelevant or lack context if they are sent to all channels during a Shared Chat session.

What’s changing?

A new optional body parameter (for_source_only) has been added to the Send Chat Message API endpoint to indicate, during a Shared Chat session, whether the message should be sent only in the source channel (true) or all channels (false).

The behavior of this body parameter will change depending on the type of access token provided.

User Access Token: When a user access token is used, for_source_only cannot be specified and developers can expect a 400 error response. This is to ensure that chatters using third-party chat clients, for example, will always have their message sent to all channels similar to the experience on the Twitch website or app.

App Access Token: When an app access token is used, for_source_only can be specified to indicate where the message should be sent in the source channel or all channels in the Shared Chat session.

The current default value for this new body parameter has been set to false so that there is no disruption to applications at this time. However, the default value will be changed to true on May 19, 2025. This window is meant to allow developers to evaluate the behavior they prefer for their application and explicitly take action if needed.

How does this affect response payloads?

  • There are no changes to the response payload for the “Send Chat Message” API.
  • A “is_source_only” field has been added to the Channel Chat Message Event payload for EventSub and will only be included during Shared Chat sessions.
  • A “source-only” PRIVMSG tag has been added to IRC and will only be included during Shared Chat sessions.

Who will be impacted by these changes and what action is needed?

This update applies to all developers who are using an app access token with the “Send Chat Message” API endpoint. Developers should review the details above and decide whether the for_source_only body parameter should be added to their API calls with a value of false before May 19, 2025 if their chatbot messages should continue to be sent to all channels in a Shared Chat session.

1 Like
2

Does this mean the key is null when not in shared chat or omitted?

3

No, the key is not included when there a Shared Chat session is not active.

4

I find it a bit sad this parameter isn’t accessible from a user token.
Having an app that allows tons of automation in the broadcaster’s name, my app would definitely benefit this.
They can make it so their own account posts chat message in response to non-chat interactions/events (clicks on stream via Heat extension, tips from external platforms, obs events, goxlr events, voicemod events, and other external tools, giveaways, and other sort of channel specific games). All these messages make no sense for shared chat.

Sure I could make an app that posts these messages but that involves much more server-side complexity both in terms of quotas and load. Because I rely on a user token on the frontend, a very small server can easily handle hundreds/thousands of concurrent users. Depending on users count and their chat activity, I would definitely have to scale up my server and probably my whole code architecture, which would involve higher costs.

It would clearly not be a good idea to have this parameter set to true by default for user tokens, but having it set to false with the possibility to explicitely set it to true would definitely be a very good addition IMHO.

Also, if I understand correctly, when a message is sent with for_source_only set to true, the channel(s) sharing chat with the target channel won’t receive the message at all?
In other words, the for_source_only ES field (source-only on IRC) is only here to let the channel know that the given message has only be sent to them and not the other ones?

5

I’d argue most of those should shut down or won’t be active in such an event. Espeically if chat powered as all the chatters in other channels will see the source channel get noisy and be confused why. So chat games should probably shut down or be played across all channels.

Giveaways get complicated legally if you discount people in chat (consult a lawyer)

Id also consider that most tip type things are more likely to be charity when shared chat is occurring or all chats need to know what a caster is reacting to (charity or tip, especially if user x from chat Y gives to z but then don’t see the tip becuase they are in chat Y instead of chat Z) (but I digress, broadcaster and tool preference here for sure, and should be on app access for chat presense permissions)

I disagree. I find the opposite to be true

Don’t have to maintain x number of user tokens (that die every 4 hours) when I only need to maintain one app access token.

And can use auth revoke eventsub to shutdown instead of the streamer banning my bot account (for example).

Logically you don’t need any user tokens on file at all. Or deal with mystery refresh token death.

Use auth grant to track “setups”
And auth revoke to track “leaves”

And sending runs off an app access good for 60 days that you just remake from clientID secret. Conceptually don’t even need to store that token in peristent/process restart memory. (and the secret must be on file in .env or equivalent if you are using refresh tokens to continue user tokens existing)

So yeah I disgree here.

Also: thats before we consider that you should be on app access token as well for chat rate or access limits. And/or to post/recieve without the user account having/requiring moderator permissions.

If shared chat mode with this Boolean set true. Only the broadcaster_id in the send chat message post body chat will receive that given message.

For source only tells a consumer that the message was local. And not sent to other channels.

So source only is only (possible to be) true in channels where the source_broadcaster_id matches the broadcaster_id in the condition of the eventsub subscriptions.

For eventsub, my understanding/read is:

  • condition.broadcaster_user_id == event.source_broadcaster_user_id - for_source_only can be either
  • condition.broadcaster_user_id != event.source_broadcaster_user_id - for_source_only can only ever be false
6

Maintaining the token front-side is not much more complicated to me. It’s the same code for all users, i basically just have to refresh token more frenquently. And my server don’t have to take the load from eventsub which is big part of the issue with the app-token way.
Also I need a User token anyways as lots of endpoints I’m calling are user-token only.
So even if handling only one app session server-side was actually easier, i’d need a user token anyways so that would be double work for the same result.

We could argue on weither it’s the right way to share chats for every cases, there will still be valid use cases for chats being sent on the broadcaster’s but not the others. Basically, all cases that justfiy this with an app access token are also valid with a user token.
Very simple use case, i made it so viewers can click on OBS sources via Heat extension to trigger things including sending chat messages (to get socials or anything for example, which avoids users from going out of lurk by sending chat commands), these don’t make sense to be sent on everyone’s chat during a shared chat session. Sure we could just say that they should turn it off, but that would be valid for ALL possible interactions on their stream which would be pretty sad. Not saying this specific example has broad usage (although i know for sure that many actually use it) but that’s only one amongst probably an infinite of similar use cases.

That’s perfectly clear thank you :folded_hands: !
I just wanted to make sure my app doesn’t have to filter out anything to comply with the new flag.

7

Thanks for this feedback and the detailed use cases. Sharing more broadly internally for discussion. And if there is anything unclear in the docs (re: the filtering comment), glad to take suggestions here as well to make sure the behavior is as straightforward as possible. Appreciate Barry jumping in for some clarity here.

1 Like
9

I find it a bit unclear in the docs what the note means.

NOTE: Can only be set when utilizing an App Access Token at the top. Cannot be specified when a User Access Token is used and will result in a 400 error.

Does this mean that after May 19, when the default is changed from false to true, that all messages sent with Send Chat Message from a user token will be for source only?

10

Choosing where a chat goes (all or source only) is an App Access Token Specific feature. Only app access tokens can choose and/or be effected by the default. And this feature is only applicable to app access tokens.

User tokens will operate the same as the website. Where you can only send to all chats.

User tokens can only send to all chats.

To user tokens this variable/parameter doesn’t exist

11

Yes, that’s why I specified User tokens in my post.

This is what I’m not parsing in the current documentation, it doesn’t say that User tokens will not be affected. Only

On May 19, 2025 the default value for the for_source_only parameter will be updated to “true” (i.e. chat messages will be only shared with the source channel by default)

Which to me suggests that even though the param is not settable by User tokens, the default will still change (for user tokens).

That’s my understanding as well, then I’d ask for clarification in the documentation as it’s not evident when read. A statement like User tokens will send messages to all shared chats and are not affected by the change that will happen in May

12

Unfortunately, this will cause a problem for me as well.
Many bots use user access tokens because the bot’s user in chat is not tied to its own Twitch application. This is especially true for locally run bots.

What will likely happen now is that many bots will still cross-post to the other chat during Shared Chat, which I assume you wanted to avoid after May 19th. However, the bots will now have no option to turn that off.

The only alternative I see here is to default for_source_only to false and allow both app and user tokens to set it. This would ensure all chat clients and bots maintain their current behavior while allowing bots to adopt the for_source_only parameter as needed, regardless of whether they operate with user or app access tokens.

13

We updated the documentation today to better describe this:

NOTE: When sending messages to a Shared Chat session, behaviors differ depending on your authentication token type:

  • When using an App Access Token, messages will only be sent to the source channel (defined by the broadcaster_id parameter) by default starting on May 19, 2025. Messages can be sent to all channels by using the for_source_only parameter and setting it to false.
  • When using a User Access Token, messages will be sent to all channels in the shared chat session, including the source channel. This behavior cannot be changed with this token type.
2 Likes
14

I agree.

I understand the point “user messages should be sent everywhere as if the user actually sent it themself from first party site”, fact is that ignores the many tools used by those people.

Mine is still very niche but what about tools like streamer.bot, SAMMI or mixitup ? Or streamdeck and touchportal?
They’re all wildly used for automations including sending chat messages that probably make no much sens to be shared in others chats for a significant part, and all rely on a user token because it allows for more than what app access token gives access to.

Even wizebot/nightbot/streamlabs/streamelements that I believe, at least some, allow to send messages in our own name with paid offer (might be wrong on this but I think I’ve seen it’s possible)

15

Which can be done with app access token after authenticating the user to the client id

In fact can be done using the same app access token as used by the “main account” for the service (assuming this is done from the server and not locally to the streamer)

So don’t need to load and maintain that token for the purpose of just sending messages (sure still needed for moderation actions/etc)

But that would be my approach to these “purchased addon” to a service (and will be once I’ve migrated to eventsub), so we can only guess what the big services are doing rather than speculating what they would prefer until they chime in with their feedback. Which given their size might be privately rather than publically. Or they miss the announcement as busy

Course this is all choice of architecture in line with available features. I know what I would do and I can guess what the big guys do. And build to fit the feature set for what I want to do.

Would it be nice to have for user tokens sure. With the default for user tokens to be the opposite to app access maybe. Just thinking here of support gotchas when people are using tools and not understanding. And just don’t read the tool documentation.

Either way “feature parity” would be nice, but the feature parity here on a user token is “choice” in line with the first party product (on a first party user token) doesn’t offer this feature. And the “I’m a bot” comes in with app access usage after oAuth has occured. So I can see why it’s done this way and I suspect it won’t be changed.

So I’m with moocat here I think